🗺 A tour of Unison

Running the UCM

By default, running ucm in a directory will interact with any .u suffixed file in the directory where the command was issued while opening the default codebase in your home directory. You'll get a message in the UCM like:

Now starting the Unison Codebase Manager (UCM)...

[…]

Get started:

  📖 Type help to list all commands, or help <cmd> to view help for one command
  🎨 Type ui to open the Codebase UI in your default browser
  📚 Read the official docs at https://www.unison-lang.org/docs/
  🌏 Visit Unison Share at https://share.unison-lang.org to discover libraries
  👀 I'm watching for changes to .u files under ~/unisonCode

 scratch/main>

What's happening here? This is the Unison Codebase Manager starting up and initializing a fresh codebase. We're used to thinking about our codebase as a bag of text files that's mutated as we make changes to our code, but in Unison the codebase is saved and updated programatically, with the aid of this CLI.

The Unison codebase format has a few key properties:

• Terms and types are identified by their implementation, not just their name. The codebase stores a hash of the syntax tree of a term or type.
• It is append-only: all changes to the codebase, including actions like deleting a term or deleting a branch, are appended to a log representing the codebase state.
• As a result, a Unison codebase has its own notion of versioning and synchronization independent of git, and a robust set of tools has been developed for managing and viewing changes in Unison code over time.

If you have never used UCM before, or are creating a new codebase, it will drop you into the “main” branch of a fresh project called “scratch”. This is represented by the scratch/main in the prompt, scratch/main>. Most of the time your prompt will be prefixed with the name of the most recent project you've worked on.

Names are stored separately from definitions so renaming is fast and 100% accurate

The Unison codebase, in its definition for List.reverse, doesn't store names for the definitions it depends on (like the List.foldLeft function); it references these definitions via their hash. As a result, changing the name(s) associated with a definition is easy.

Let's try this out. List.reverse is defined using List.foldLeft. Let's rename that to List.foldl temporarily. Try out the following command (you can use tab completion here if you like):

tour/main> move lib.base.data.List.foldLeft lib.base.data.List.foldl

  Done.

tour/main> view lib.base.data.List.reverse

  lib.base.data.List.reverse : [a] -> [a]
  lib.base.data.List.reverse as =
     use base.data.List +:
     base.data.List.foldl (acc a -> a +: acc) [] as

Notice that view shows the foldl name now, so the rename has taken effect. Nice!

So rename and move things around as much as you want! Don't worry about picking a perfect name the first time. Naming things is hard enough, renaming them shouldn't be a trial.

The fact that Unison codebases are immutable and append-only means that we can "rewind" our project to an earlier point in time. Use the reflog command to see a log of changes to the project. You should see some help text and a numbered list of hashes.

     Branch      When          Hash          Description
1.   tour/main   39 secs ago   #ijqrr5987q   move tour/main:lib.base.data.List.foldLeft tour/main:lib.bas...
2.   tour/main   18 mins ago   #a1vh3f0sa1   Include latest base library
3.   tour/main   18 mins ago   #sg60bvjo91   Project Created

A reflog keeps track of the history of a particular project, changes to the project like renames, updates, or deletions, form a log of hashes representing the codebase state. When we renamed List.foldLeft, conceptually, the "state" of the codebase changed, but the log-based format of the project history means those changes are retrievable.

Let's try to undo the rename action. Use the reset command to pick a prior project state to return to. We'll give it the hash of the project state from just before the move command was issued.

tour/main> reset #a1vh3f0sa1

  Done.

Great! OK, go drink some water, 🚰 and then let's start writing some Unison code!

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.

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

Testing your code

Next let's add a test for our square function:

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

test> square.tests.ex1 =
 verify '(ensureEqual (square 4) 16)

Save the file, and Unison comes back with:

8 | test> square.tests.ex1 = check (square 4 == 16)

✅ Passed : Proved.

Some syntax notes:

• The test> prefix tells Unison that what follows is a test watch expression. Note that we're also giving a name to this expression, square.tests.ex1.
• There's nothing special about the name square.tests.ex1; we could call those bindings anything we wanted. Here we use the convention that tests for a definition foo go in foo.tests.

The test.verify function has the signature test.verify : '{g, Exception, Each, Random, Label} () ->{g} [test.Result]. It handles the Each, Random and Exception abilities. These are common abilities used in testing. The test.ensureEqual function raises an Exception if the two values are not equal, failing the test. In this case, the two values were equal, so the test passes.

A property-based test

Let's test this a bit more thoroughly. square should have the property that square a * square b == square (a * b) for all choices of a and b. The testing library supports writing property-based tests like this. There's some new syntax here, explained afterwards:

use base

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

use test

test> square.tests.ex1 = verify '(ensureEqual (square 4) 16)

test> square.tests.prop1 =
   verify do
     Each.repeat 100
     a = Random.natIn 0 100
     b = Random.natIn 0 100
     ensure (square a * square b == square (a * b))

10 |               verify do

✅ Passed

This will test our function with a bunch of different inputs using the Each and Random abilities. Each is being used to generate 100 Random numbers, which the the test then verifies the property holds for.

Moving and renaming terms

When we added square, we were at the tour namespace, so square and its tests are at tour.square. We can also move the terms and namespaces to different locations in our codebase with the move command. move is recursive, so it will move the term and all the things inside the square namespace to the new name.

tour/main> move square mySquare

  Done.

When you're done shuffling some things around, you can use find with no arguments to view all the definitions under the current namespace:

tour/main> find

  1. mySquare : Nat -> Nat
  2. mySquare.tests.ex1 : [Result]
  3. mySquare.tests.prop1 : [Result]

Also notice that we don't need to rerun our tests after this reshuffling.

tour/main> test

  Cached test results (`help testcache` to learn more)

  ◉ mySquare.tests.ex1       : Passed
  ◉ mySquare.tests.prop1     : Passed

  ✅ 2 test(s) passing

  Tip:  Use view square.tests.ex1 to view the source of a test.

The tests are still cached because the test cache is keyed by the hash of the test itself, not by what the test happens to be called.

When you're starting out writing some code, sometimes it's nice to put it in a temporary namespace, perhaps called temp or wip. Later, without breaking anything, you can move that namespace or bits and pieces of it elsewhere, using the move command.

Updating existing definitions

Here we'll make a change to the implementation of our mySquare function.

Try entering edit mySquare in the UCM:

tour/main> edit mySquare
  ☝️

  I added these definitions to the top of ~/unisoncode/scratch.u

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

  You can edit them there, then do `update` to replace the definitions currently in this branch.

This copies the pretty-printed definition of mySquare into your scratch file "above the fold." That is, it adds a line starting with --- and puts whatever was already in the file below this line. Unison ignores any file contents below the fold.

Let's edit mySquare and instead define mySquare x (just for fun) as the sum of the first x odd numbers (here's a nice geometric illustration of why this gives the same results):

use base

mySquare : Nat -> Nat
mySquare x =
  sum (map (x -> x * 2 + 1) (range 0 x))

sum : [Nat] -> Nat
sum = foldLeft (+) 0

✅

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`:

      sum : [Nat] -> Nat

    ⍟ These names already exist. You can `update` them to your new definition:

      mySquare : Nat -> Nat

Adding an updated definition to the codebase

Notice the message says that mySquare is ok to update. Let's try that:

tour/main> update

  ⍟ I've added these definitions:

    sum : [Nat] -> Nat

  ⍟ I've updated these names to your new definition:

    mySquare : Nat -> Nat

Only affected tests are rerun on update

If we rerun the tests, the tests won't be cached this time, since one of their dependencies has actually changed:

tour/main> test

  ✅

    New test results:

  ◉ mySquare.tests.ex1      : Passed
  ◉ mySquare.tests.prop1    : Passed

  ✅ 2 test(s) passing

  Tip: Use view mySquare.tests.ex1 to view the source of a test.

The dependency tracking for determining whether a test needs rerunning is 100% accurate and is tracked at the level of individual definitions. You'll only rerun a test if one of the individual definitions it depends on has changed.