mirror of
https://github.com/unisonweb/unison.git
synced 2024-09-11 02:25:39 +03:00
70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
|
|
# Hello!
|
|
|
|
```ucm:hide
|
|
scratch/main> builtins.merge
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
$ ucm transcript hello.md
|
|
```
|
|
|
|
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.
|
|
|
|
Fenced code blocks of type `unison` and `ucm` are treated specially:
|
|
|
|
* `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.
|
|
|
|
Take a look at [the elaborated output](hello.output.md) to see what this file looks like after passing through the transcript runner.
|
|
|
|
## Let's try it out!!
|
|
|
|
In the `unison` fenced block, you can give an (optional) file name (defaults to `scratch.u`), like so:
|
|
|
|
```unison myfile.u
|
|
x = 42
|
|
```
|
|
|
|
Let's go ahead and add that to the codebase, then make sure it's there:
|
|
|
|
```ucm
|
|
scratch/main> add
|
|
scratch/main> view x
|
|
```
|
|
|
|
If `view` returned no results, the transcript would fail at this point.
|
|
|
|
## Hiding output
|
|
|
|
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:
|
|
|
|
```unison:hide
|
|
y = 99
|
|
```
|
|
|
|
This works for `ucm` blocks as well.
|
|
|
|
```ucm:hide
|
|
scratch/main> rename.term x answerToUltimateQuestionOfLife
|
|
```
|
|
|
|
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.
|
|
|
|
```unison:hide:all
|
|
> [: you won't see me :]
|
|
```
|
|
|
|
## Expecting failures
|
|
|
|
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:
|
|
|
|
```unison:error
|
|
hmm : .builtin.Nat
|
|
hmm = "Not, in fact, a number"
|
|
```
|