2024-07-10 17:46:18 +03:00
# Hello\!
2019-09-24 19:09:20 +03:00
This markdown file is also a Unison transcript file. Transcript files are an easy way to create self-documenting Unison programs, libraries, and tutorials.
The format is just a regular markdown file with some fenced code blocks that are typechecked and elaborated by `ucm` . For example, you can call this transcript via:
2024-07-15 21:10:27 +03:00
```
$ ucm transcript hello.md
```
2019-09-24 19:09:20 +03:00
2021-10-24 05:29:27 +03:00
This runs it on a freshly generated empty codebase. Alternately `ucm transcript.fork --codebase /path/to/code hello.md` runs the transcript on a freshly generated copy of the provided codebase. Do `ucm help` to learn more about usage.
2019-09-24 19:09:20 +03:00
Fenced code blocks of type `unison` and `ucm` are treated specially:
2024-07-10 17:46:18 +03:00
- `ucm` blocks are executed, and the output is interleaved into the output markdown file after each command, replacing the original `ucm` block.
- `unison` blocks are typechecked, and a `ucm` block with the output of typechecking and execution of the file is inserted immediately afterwards.
2019-09-24 19:09:20 +03:00
2019-12-14 00:29:31 +03:00
Take a look at [the elaborated output ](hello.output.md ) to see what this file looks like after passing through the transcript runner.
2024-07-10 17:46:18 +03:00
## Let's try it out\!\!
2019-09-24 19:09:20 +03:00
In the `unison` fenced block, you can give an (optional) file name (defaults to `scratch.u` ), like so:
2024-07-10 17:46:18 +03:00
``` unison
2019-09-24 19:09:20 +03:00
---
title: myfile.u
---
x = 42
```
2024-07-10 19:17:15 +03:00
``` ucm
2019-09-24 19:09:20 +03:00
2023-12-22 14:55:24 +03:00
Loading changes detected in myfile.u.
2019-10-07 22:55:01 +03:00
I found and typechecked these definitions in myfile.u. If you
do an `add` or `update` , here's how your codebase would
change:
2019-09-24 19:09:20 +03:00
2019-10-07 22:55:01 +03:00
⍟ These new definitions are ok to `add` :
2019-11-14 00:57:51 +03:00
x : Nat
2019-10-07 22:55:01 +03:00
2019-09-24 19:09:20 +03:00
```
Let's go ahead and add that to the codebase, then make sure it's there:
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-12 01:22:09 +03:00
scratch/main> add
2019-09-24 19:09:20 +03:00
2019-10-07 22:55:01 +03:00
⍟ I've added these definitions:
2019-11-14 00:57:51 +03:00
x : Nat
2019-10-07 22:55:01 +03:00
2024-06-12 01:22:09 +03:00
scratch/main> view x
2019-10-07 22:55:01 +03:00
2019-11-14 00:57:51 +03:00
x : Nat
2019-10-07 22:55:01 +03:00
x = 42
2019-09-24 19:09:20 +03:00
```
If `view` returned no results, the transcript would fail at this point.
## Hiding output
2020-01-21 01:46:32 +03:00
You may not always want to view the output of typechecking and evaluation every time, in which case, you can add `:hide` to the block. For instance:
2019-09-24 19:09:20 +03:00
2024-07-10 17:46:18 +03:00
``` unison
2019-09-24 19:09:20 +03:00
y = 99
```
This works for `ucm` blocks as well.
2020-01-21 01:46:32 +03:00
Doing `unison:hide:all` hides the block altogether, both input and output - this is useful for doing behind-the-scenes control of `ucm` 's state.
2019-09-24 19:09:20 +03:00
## Expecting failures
2024-07-10 17:46:18 +03:00
Sometimes, you have a block which you are *expecting* to fail, perhaps because you're illustrating how something would be a type error. Adding `:error` to the block will check for this. For instance, this program has a type error:
2019-09-24 19:09:20 +03:00
2024-07-10 17:46:18 +03:00
``` unison
2019-09-24 19:09:20 +03:00
hmm : .builtin.Nat
hmm = "Not, in fact, a number"
```
2024-07-10 19:17:15 +03:00
``` ucm
2019-09-24 19:09:20 +03:00
2023-12-22 14:55:24 +03:00
Loading changes detected in scratch.u.
2022-12-02 22:50:20 +03:00
I found a value of type: Text
2021-04-08 08:24:00 +03:00
where I expected to find: Nat
2019-10-07 22:55:01 +03:00
1 | hmm : .builtin.Nat
2 | hmm = "Not, in fact, a number"
2022-12-02 22:53:10 +03:00
from right here:
2 | hmm = "Not, in fact, a number"
2019-09-24 19:09:20 +03:00
```