👀 Unison at a glance

This document contains code snippets with a minimum of exposition. Links are provided throughout to more comprehensive docs sections. If you haven't downloaded the UCM,you might want to do that first. 😎

Hello World

Write your Unison code in any.usuffixed"scratch" file.

The classichelloWorldprogram performs console interactions via the IO ability.Read about how abilities model effects in Unison.

usingAbilitiesPt1.helloWorld : '{IO, Exception} ()

usingAbilitiesPt1.helloWorld : '{IO, Exception} ()
usingAbilitiesPt1.helloWorld _ = printLine "Hello World!"

Execute the entry point to your program with therunUCM command.

.> project.create hello-world
hello-world/main> run helloWorld

OraddyourhelloWorldprogram to the codebase and run it by packaging it up in a binary executable!

hello-world/main> add
hello-world/main> compile helloWorld helloFile

This will produce an executable file calledhelloFile.ucin the same directory as the codebase. You can then start your program in your terminal.

$ ucm run.compiled helloFile.uc

📚Learn more about executing Unison programs

Basic functions

The following introduces a functiondoublewith one parameter.Unison conventions for defining functions are detailed here

glance.double : Nat -> Nat

glance.double : Nat -> Nat
glance.double x =
  use Nat *
  x * 2

> double 4

The>in a scratch file runs thedoublefunction in awatch expression.

📚The Unison tour walks through watch expressions and other workflow features

Delayed computation syntax

The'symbol is syntactic sugar for introducing athunkand the!symbol is syntactic sugar for calling the thunk.

atAGlance.greet : '{IO, Exception} ()

atAGlance.greet : '{IO, Exception} ()
atAGlance.greet _ =
  use Text ++
  printLine "Enter your name:"
  name = !readLine
  printLine ("Hello " ++ name)

delayGreet : 'Text

delayGreet : 'Text
delayGreet = do greet "Joy"

!delayGreet⧨"Hi Joy"

A more detailed look at delayed computations

List literals

Square brackets introduce aUnison list.

[0, 1, 2, 3] List.++ [4, 5]⧨[0, 1, 2, 3, 4, 5]

TheList.++is ouroperatorfor list concatenation.

use List +: :+
head = 1 +: [2, 3, 4]
head :+ 5⧨[1, 2, 3, 4, 5]

A variety of list patterns are available for lists.

📚Learn more about common collection types in Unison

List transformations

Nat.range 0 10
  |> lib.base.data.List.map (x -> x Nat.* 100)
  |> lib.base.data.List.filter (const true)
  |> lib.base.data.List.foldLeft (Nat.+) 0⧨4500

The|>operator is a "pipe" which passes the result of executing the expression on the left as an argument to function on right.

The parenthesizedx -> x Nat.* 100argument tolib.base.data.List.mapis an example oflambdas in Unison.

📚Learn more about operators like|>

if/else and pattern matching

The expression below is written with bothif then and else syntaxand withpattern matching syntax

use Nat mod
isEven1 num =
  if mod num 2 === 0 then true else false
isEven2 num = match num with
  n | mod n 2 === 0 -> true
  _ -> false

Unison'spattern matching featuresinclude variable binding, pattern guards (separated by|),and as-patterns (indicated with an@).

match Some 12 with
  None -> "none"
  Some n| Nat.isEven n  -> "n is a variable and | is a pattern guard"
  opt@(Some n) -> "opt binds to the entire optional value"⧨"n is a variable and | is a pattern guard"

Type declarations

A unison data type with uniqueness determined by its name:

type LivingThings

type LivingThings
  = glance.LivingThings.Animal
  | glance.LivingThings.Plant
  | glance.LivingThings.Fungi
  | glance.LivingThings.Protists
  | glance.LivingThings.Monera

A recursive Tree data type with a single type parameter:

structural type Tree a

structural type Tree a
  = glance.Tree.Empty
  | glance.Tree.Node a (Tree a) (Tree a)

The structural keyword means that types defined with the same structure are identical.

More on data types and the difference between structural and unique.

Record types allow you to name the fields of your type.

unique type Pet = {
   age : Nat,
   species : Text,
   foodPreferences : [Text]
}

Creating a record type generates a series of helper methods to access and update the fields of the data type.

myProject/main> add Pet

 ⍟ I've added these definitions:

     unique type Pet
     Pet.age                    : Pet -> Nat
     Pet.age.modify             : (Nat ->{g} Nat) -> Pet ->{g} Pet
     Pet.age.set                : Nat -> Pet -> Pet

Record type syntax in depth

Exception handling

nonZero : Nat ->{Exception} Nat

nonZero : Nat ->{Exception} Nat
nonZero = cases
  n
    | n Nat.== 0  ->
      Exception.raise (Generic.failure "Zero was found" n)
    | otherwise   -> n

catch '(nonZero 0)⧨Left (Failure (typeLink Generic) "Zero was found" (Any 0))

An exception is "raised" with theExceptionability and "caught" with a handler.

Our error handling with abilities doc describes this pattern and more error types in detail.

Using abilities

Abilities are used for effect management in Unison.

getRandomElem : [a] ->{Abort, Random} a

getRandomElem : [a] ->{Abort, Random} a
getRandomElem list =
  index = base.abilities.Random.natIn 0 (List.size list)
  List.at! index list

toOptional! '(splitmix 42 '(getRandomElem [1, 2, 3, 4, 5]))⧨Some 5

This plucks a random element from the list by its index withbase.abilities.Random.natIn,a function using theRandom ability.If the index is not present in the list, it uses theAbortability to halt execution.

splitmixandtoOptional!are examples ofability handlers.

Distributed computations

Distributed computations can be expressedin the Unison language itselfthrough theRemoteability.Read about the Remote ability and its features

distributed : Seq k Nat ->{Remote} Nat

distributed : Seq k Nat ->{Remote} Nat
distributed dseq =
  use Nat + ==
  dseq
    |> Seq.map (x -> x + 1)
    |> Seq.filter (x -> Nat.mod x 7 == 0)
    |> Seq.reduce 0 (+)

This simple map/reduce code can operate over a distributed sequence, where the data may live in many different nodes in a cluster.This distributed computation use case has been fleshed out in an article.

Issuing an http request

Pull the library fromUnison Share.with thepullcommand.

myProject/main> pull @unison/httpclient/releases/latest lib.httpclient

exampleGet : '{IO, Exception} HttpResponse

exampleGet : '{IO, Exception} HttpResponse
exampleGet _ =
  uri =
    match URI.parse
      "https://share.unison-lang.org/@unison/httpclient" with
      Some uri -> uri
      None ->
        Exception.raiseFailure
          (typeLink IOError) "unable to parse URI" ()
  req = do Http.get uri
  Http.run req

The first part of this code uses data constructors from the http library to create a full uri out of an authority and path. The request is handled by passing it to the Http handler.

The http library has great docs!

Basic file operations

readFileUtf8       : FilePath ->{IO, Exception} Text
FilePath.writeFile : FilePath -> Bytes ->{IO, Exception} ()
renameFile         : FilePath -> FilePath ->{IO, Exception} ()

Our standard library has a number of helpful File operations built in. They're located under theFilePathandHandlenamespaces.

Concurrency primitives

Concurrency primitives likeMVar,TVar,andSTMare built into the base library.TVarandSTMmake it easy to write lock-free concurrent mutable data structures. For instance, here’s a simple lock-free queue implementation and a few helper functions:

type TQueue a

type TQueue a
  = lib.base.IO.concurrent.STM.TQueue.TQueue (TVar [a]) (TVar Nat)

enqueue : a -> TQueue a ->{STM} ()

enqueue : a -> TQueue a ->{STM} ()
enqueue a = cases
  TQueue elems _ -> TVar.modify elems (es -> a List.+: es)

dequeue : TQueue a ->{STM} a

dequeue : TQueue a ->{STM} a
dequeue tq = match tryDequeue tq with
  None   -> !STM.retry
  Some a -> a

The block introduced bySTM.atomicallybelow ensures that no one can access state of the queue until after the actions in the block have taken place.

queueExample : '{IO, Exception} ()

queueExample : '{IO, Exception} ()
queueExample _ =
  runQueue : '{STM} Nat
  runQueue _ =
    queue = TQueue.fromList [1, 2, 3, 4, 5]
    enqueue 6 queue
    dequeue queue
    dequeue queue
  result = STM.atomically runQueue
  printLine (Nat.toText result)

run

myProgram : '{IO, Exception} ()
myProgram = '(printLine "Hello World")

myProgramWithArgs : '{IO, Exception} ()
myProgramWithArgs = 'let
  printLine ("Hello " ++ Optional.getOrElse "World" (List.head !getArgs) ++ "!")

.> run myProgram
.> run myProgramWithArgs Rebecca

Theruncommand is used to evaluate terms that require the IO ability within ucm. A program that performs IO cannot be evaluated in a watch expression but can be executed withrun.

Run takes a delayed computation and performs!myProgram,wheremyProgramis searched for in the most recent typechecked file, or in the codebase. The function provided to theruncommand must have a final return type of unit,(),and may perform the IO andExceptionabilities.

Any arguments following theruncommand will be passed as program arguments.

add

myProject/main> add

myProject/main> add myNewTerm

Adds all the definitions from the most recently typechecked file to the codebase.

FAQ about theaddcommand

I got an error about "these definitions failed" on add

This message happens when some of the definitions couldn't be added to the codebase. UCM shows a table of definitions along with the reason why they didn't succeed, like this:

x These definitions failed:

Reason
needs update   myFunction : Doc

Here's what these reasons mean:

needs update:The scratch file has a definition with the same name as an existing definition. Doingupdateinstead of add will turn this failure into a successful update.
conflicted:The file has a definition whose name is currently conflicted. Resolving the conflict and then trying an update again will turn this into a successful update.
term/ctor collision:A definition with the same name as an existing constructor for some data type. Rename your definition or the data type before trying again toaddorupdate.
ctor/term collision:A type defined in the file has a constructor that's named the same as an existing term. Rename that term or your constructor before trying again toaddorupdate.
needs alias:A definition in the file already has another name. You can use thealias.termoralias.typecommands to create new names for existing definitions.
blocked:This definition couldn't be added because it dependended on another definition in the file that had a failed status.
extra dependency:This definition was added because it was a dependency of a definition explicitly selected.

I want to undo a partially completed add where some of the definitions failed

You can use theundocommand in the case of an undesired partially completed add.

Operators

Operators are functions which are called in an infix manner, as in5 Nat.* 8.They're commonly expressed in terms of short symbols like+or<<.

Examples

Nat.* : Nat -> Nat -> Nat

Weighted.<|> : Weighted a -> Weighted a -> Weighted a

pull

Downloading a project dependency:

myProject/main> pull @unison/base/releases/X.Y.Z lib.base

Pulling a public namespace:

.> pull unison.public.base.latest lib.base

Using git urls:

.> pull git(git@github.com:unisonweb/base).latest .base
.> pull git(https://github.com/org/repo:some-branch).some.path

Thepullcommand is used to pull definitions from another codebase into the current codebase. Commonly used to download Unison dependencies.

You can pull Unison code from unison's own code-hosting platform,unison shareor from a git repo using thegit url format.

The first argument topullis any Git URL that identifies the namespace to pull from and the second argument (if given) identifies a namespace that the remote codebase will be merged into. If a second argument is not supplied, then the remote codebase will be merged into the current namespace.

To optionally pull from a Git branch, the repository name is followed by:and the name of the branch.