Transcripts provide a way to script interactions between Unison code and the Unison Codebase Manager (UCM.) They are written as markdown documents containing fenced codeblocks which define the Unison code and UCM commands to be performed. These interactions are called "stanzas" and they're evaluated starting from the top of the file.
When writing Unison code in a transcript, start a code block with triple backticks followed by "unison":
``` unison
myTerm = "Hello world"
```Let's say you want to add this term to a Unison codebase. You can describe that in a fenced code block started by triple backticks followed by the word "ucm":
``` ucm
.> add myTerm
```The > is a prompt indicator that you'll use to separate the directory structure indicator on the left and the ucm commands on the right. . means that the prompt is located at the root . of the codebase. You can change this to reflect the results of running commands like creating new namespaces in your script or cd-ing around the codebase. To the right of the prompt, you can issue UCM commands for interacting with the codebase.
To run a transcript when you start up the UCM, provide the transcript option and a path to the markdown file like so:
ucm transcript path/to/transcript.md
By default, transcripts are run against a new codebase each time. When a transcript is run it creates a temporary file to house the new codebase and deletes it upon finishing the run. Note that unlike the default behavior of initializing a new codebase with the UCM codebase-create argument, transcripts do not contain the base library. It's common to start your transcripts with a ```ucm block which contains the command builtins.merge so that you have a minimal set of built-ins to work with (these are things like Nat and List).
```ucm:hide
.> builtins.merge
```If you would like your codebase to run against a codebase with the base library in scope, you can add a ucm block which issues a pull command for your desired base library.
Also… be prepared to grab a cup of tea 🫖 - pulling base in a transcript adds a few seconds to the runtime of the transcript.
If a transcript can be successfully executed, the UCM will create an output file which captures the results of the interactions being described. The output of the transcript run will be written in a .output suffixed file with the same name and file path as the original.
Expecting failures
It's possible to write a transcript which expects a failure. Add the ucm:error tag to the fenced code block to indicate that the UCM should expect a failure when running the enclosed block.
```ucm:error
.> add myTerm
```This will enable the transcript runner to continue with subsequent stanzas in the script.
Hiding output
If there's ever an interaction which is too noisy to be included in the .output file, you can append the :hide modifier to any stanza.
```ucm:hide
.> builtins.merge
```
```unison:hide
> List.range 0 99
```Stateful stanzas
In some circumstances, the stanzas of a transcript might entail a back and forth interaction between the UCM and a scratch file. An example of this would be if a bug surfaces upon updating an edited term, but not during the initial typechecking. To do this you need to "edit" the term, but by default, stanzas don't reflect "re-opened" unison terms.
If you need to save and edit terms to a transcript codebase, the UCM edit command will open your scratch.u file and render the terms to it. You can mimic the back and forth of editing terms by loading a the file to bring it into the transcript codebase's scope.
```unison
myTerm = "hi"
```
```ucm
.> add myTerm
.> edit myTerm
```
At this point the scratch.u file contains ''myTerm'' at the top.
```ucm
.> load scratch.u
```
```unison
myTerm = "hi there!"
```Transcript codebase options
- You can save the codebase that your transcript produced with the
--save-codebaseflag for debugging and sharing. At the end of the transcript run, the UCM will print out the location of the directory where you can find your codebase and give you instructions for how to open it! - If you would like to run your transcript against a particular codebase, use the
transcript.forkoption. Here's an example of how it might be called:ucm transcript.fork path/to/transcript.md --codebase aParticularCodebaseThis will make a copy of the codebase given as an argument and run the transcript against it. Don't worry—your original codebase will remain unaltered.