Unison's interactive scratch files

The codebase manager listens for changes to any file ending in .u in the current directory. When any such file is saved (which we call a "scratch file"), Unison parses and typechecks that file. Let's try this out.

Keep your ucm terminal running and open up a file, scratch.u (or foo.u, or whatever you like) in your preferred text editor.

Now put the following in your scratch file:

square : Nat -> Nat
square x =
  use Nat *
  x * x

This defines a function called square. It takes an argument called x and it returns x multiplied by itself.

When you save the file, Unison replies:

✅

I found and typechecked these definitions in ~/unisoncode/scratch.u. If you do an
`add` or `update` , here's how your codebase would change:

  ⍟ These new definitions are ok to `add`:

    square : Nat -> Nat

Now evaluating any watch expressions (lines starting with `>`)… Ctrl+C cancels.

It typechecked the square function and tells us that square is "ok to add." We'll do that shortly, but first, let's try calling our function right in the scratch.u file, just by starting a line with >:

square : Nat -> Nat
square x =
  use Nat *
  x * x

> square 4

And Unison prints:

6 | > square 4
      ⧩
      16

The > square 4 on line 6 is called a "watch expression". Unison uses these watch expressions instead of having a separate read-eval-print-loop (REPL). The code you are editing can be run interactively as you go, with a full text editor at your disposal, with the same definitions all in scope, without needing to switch to a separate tool.

The use Nat * is a use clause which specifies which "*" operator we want to use. This one is from the Nat namespace in our lib.base standard library. Use clauses mean we can refer to base.Nat as simply Nat and can refer to * without prefixing it Nat.*.

Question: do we really want to reevaluate all watch expressions on every file save? What if they're expensive? Luckily, Unison keeps a cache of results for expressions it evaluates, keyed by the hash of the expression, and you can clear this cache at any time without ill effects. If a result for a hash is in the cache, Unison returns that instead of evaluating the expression again. So you can think of and use your .u scratch files a bit like spreadsheets, which only recompute the minimal amount when dependencies change.

🤓
There's one more ingredient that makes this work effectively, and that's functional programming. When an expression has no side effects, its result is deterministic, and you can cache it as long as you have a good key to use for the cache, like the Unison content-based hash. Unison's type system won't let you do I/O inside one of these watch expressions or anything else that would make the result change from one evaluation to the next.

Let's try out a few more watch expressions:

-- A comment, ignored by Unison

> List.reverse [1,2,3,4]
> 4 + 6
> 5.0 / 2.0
> not true
✅

~/unisoncode/scratch.u changed.

Now evaluating any watch expressions (lines starting with
`>`)… Ctrl+C cancels.

  6 | > List.reverse [1,2,3,4]
        ⧩
        [4, 3, 2, 1]

  7 | > 4 + 6
        ⧩
        10

  8 | > 5.0 / 2.0
        ⧩
        2.5

  9 | > not true
        ⧩
        false