Motoko

A comprehensive overview

Overview

Motivation and Goals

A simple, useful language for the Internet Computer (IC)

Familiar syntax
Safe by default
Incorporating ~~actor~~ canister model
Seamless integration of IC features
Making most of present and future WebAssembly

Key Design Points

Object-oriented, functional & imperative
Objects as records of members
async/await for sequential programming of asynchronous messaging
Structural typing with simple generics and subtyping
Safe arithmetic (unbounded and checked)
Non-nullable types by default
JavaScript-like syntax but statically typed & sane

Inspirations: Java(Script), C#, Swift, Pony, ML, Haskell

Semantics

call-by-value (like Java, C, JS, ML; unlike Haskell, Nix)
declarations are locally mutually recursive
parametric, bounded polymorphism
subtyping as subsumption, not coercion.
no dynamic casts
no inheritance

Implementation(s)

implemented in OCaml (leverages wasm libary)
simple reference interpreter
less simple compiler to WebAssembly
- multipass with typed IR in each pass.
- uniform representation, unboxed arithmetic
- two-space gc (for now), gc between messages
polymorphism by erasure

The language

Expressions

Identifiers:
x, foo_bar, test', List, Map
Parentheses for grouping
Type annotations (to help type inference):
(42 : Int)

Blocks and declarations

  type Delta = Nat;
  func print() {
    Debug.print(Int.toText(counter));
  };
  let d : Delta = 42;
  var counter = 1;
  counter := counter + tmp;
  print();

Semicolon after each declaration!
Mutually recursive
Mutable variables marked explicitly

Control flow

if (b) …
if (b) … else …
switch x { case (pat1) e1; …; case _ en }
while (b) …
loop …
loop … while (b)
for (pat in e) …

Primitive types

Unbounded integers

Int

Inferred by default for negative literals.

Literals: 13, 0xf4, -20, +1, 1_000_000

Unbounded naturals

Nat

Non-negative, trap upon underflow.

Inferred by default for non-negative literals

Literals: 13, 0xf4, 1_000_000

Bounded numbers (trapping)

Nat8, Nat16, Nat32, Nat64, Int8, Int16, Int32, Int64

Trap on over- and underflow. Wrap-on-trap and bit-manipulating operations available.

Needs type annotations (somewhere)

Literals: 13, 0xf4, -20, 1_000_000

Floating point numbers

Float

IEEE 754 double precision (64 bit) semantics, normalized NaN

Inferred for fractional literals

Literals: 0, -10, 2.71, -0.3e+15, 3.141_592_653_589_793_12

Numeric operations

No surprises here

- x
a + b
a & b
…

Characters and text

Char, Text

Unicode! No random access.

'x', '\u{6a}', '☃',
"boo", "foo \u{62}ar ☃"
"Concat" # "enation"

Booleans

Bool

Literals: true, false

a or b
a and b
not b
if (b) e1 else e2

Functions

Function types

Simple functions:
```
Int.toText : Int -> Text
```
multiple arguments and return values
```
divRem : (Int, Int) -> (Int, Int)
```

can be generic/polymorphic

Option.unwrapOr : <T>(?T, default : T) -> T

first-class (can be passed around, stored)

map : <A, B>(f : A -> B, xs : [A]) -> [B]
let funcs : [<T>(T) -> T] = …

Function Declarations & Use

func add(x : Int, y : Int) : Int = x + y;

func applyNTimes<T>(n : Nat, x : T, f : T -> ()) {
  if (n == 0) return;
  f(x);
  applyNTimes(n-1, x, f);
}

applyNTimes<Text>(10, "Hello!", func(x) = { Debug.print(x) } );

func() { … } short for func() : () = { … }
Parametric functions
Type instantiations may sometimes be omitted
Anonymous functions (a.k.a. lambdas)

Composite types

Tuples

(Bool, Float, Text)

immutable, heterogeneous, fixed size

let tuple = (true, 1.2, "foo");
tuple.1 > 0.0;
let (_,_,t) = tuple;

Options

?Text

is either a value of that type, or null

func foo(x : ?Text) : Text {
  switch x {
    case (null) { "No value" };
    case (?y) { "Value: " # y };
  };
};
foo(null);
foo(?"Test");

Arrays (immutable)

[Text]

let days = ["Monday", "Tuesday", … ];
assert(days.len() == 7);
assert(days[1] == "Tuesday");
// days[7] will trap (fixed size)
for (d in days.vals()) { Debug.print(d) };

Arrays (mutable)

[var Nat]

let counters = [var 1, 2, 3];
assert(counters.len() == 3);
counters[1] := counters[1] + 1;
// counters[3] will trap (fixed size)

Records

{name : Text; points : var Int}

let player = { name = "Joachim";  var points = 0 };
Debug.print(
  player.name # " has " #
  Int.toText(player.points) # " points."
);
player.points += 1;

Objects

{ get : () -> Int; add : Int -> () }

object self {
  var points = 0; // private by default
  public func get() = points;
  public func add(p : Int) { points += p };
}

Different syntax, same type as records

Variants

{ #invincible; #alive : Int; #dead }

type Health = { #invincible; #alive : Nat; #dead };
func takeDamage(h : Health, p : Nat) : Health {
  switch (h) {
    case (#invincible) #invincible;
    case (#alive hp) {
      if (hp > p) (#alive (hp-p)) else #dead
    };
    case (#dead) #dead;
  }
}

Packages and modules

Modules

// the type of base/Int.mo
module {
  toText : Int -> Text;
  abs : Int -> Nat;
  …
}

types and values like objects

but restricted to static content (pure, no state, …)

Module imports

import Debug "mo:base/Debug";
import Int "mo:base/Int";

base package provides basic features.

More libraries popping up!

Platform features

Actor types

Like object types, but marked as actor:

type Receiver = actor { recv : Text -> async Nat };
type Broadcast = actor {
  register : Receiver -> ();
  send : Text -> async Nat;
}

sharable arguments and no or async result type.

“canister” ≈ “actor”

sharable ≈ serializable

all primitive types
records, tuples, arrays, variants, options
with immutable sharable components
actor types
shared function type

Not sharable:
mutable things
local functions
objects (with methods)

A complete actor

import Array "mo:base/Array";
actor {
  var r : [Receiver] = [];
  public func register(a : Receiver) {
    r := Array.append(r, [a]);
  };
  public func send(t : Text) : async Nat {
    var sum := 0;
    for (a in r.values()) {
      sum += await a.recv(t);
    };
    return sum;
  };
}

a typical canister main file

Async/await

async T

asychronous future or promise

introduced by async { … }
(implicit in async function declaration)

await e
suspends computation pending e’s result

Actor import

import Broadcast "ic:ABCDEF23";
actor Self {
  public func go() {
    Broadcast.register(Self);
  };
  public func recv(msg : Text) : async Nat {
    …
  }
}

Principal and caller

actor Self {
  let myself : Principal = Principal.fromActor(Self);
  public shared(context) func hello() : async Text {
    if (context.caller == myself) {
      "Talking to yourself is the first sign of madness";
    } else {
      "Hello, nice to see you";
    };
  };
}

Principal: identity of a user or canister/actor

Type system

Structural

type Health1 = { #invincible; #alive : Nat; #dead };
type Health2 = { #invincible; #alive : Nat; #dead };

let takeDamage : (Health1, Nat) -> Health1 = …;
let h : Health2 = #invincible;
let h' = takeDamage(h, 100); // works

Type definitions
do not create types,
but name existing types

Subtyping

Mortal <: Health

type Health = { #invincible; #alive : Nat; #dead };
type Mortal = { #alive : Nat; #dead };

let takeDamage : (Health, Nat) -> Health = …;
let h : Mortal = #alive 1000;
let h' = takeDamage(h, 100); // also works

t1 <: t2: t1 can be used wherever t2 is expected

Generic types

type List<T> = ?{head : T; tail : List<T>};

…
let l : List<Nat> = ?{head = 0; tail = ?{head = 1 ; tail = null }};

Fin

Not covered

Polymorphic functions with type bounds
Classes
Error handling (try … catch … & throw …)

Old slides

Classes

Classes as functions returning objects:

 class Counter(init : Int) {
    private var state : Int = init;
    public func inc() { state += 1; };
    public func get() : Int { state; };
  }

Class instantiation as function call (no new):

let c = Counter(666);
c.inc();
let 667 = c.get();

Generic Classes

class Dict< K, V > (cmp : (K,K)-> Int ) {
  add(k: K, v: V) { ... };
  find(k: K) : ? V { ... };
};

let d = Dict<Int,Text> (func (i:Int, j:Int) : Int = i - j);
d.add(1,"Alice");
let ? name = d.find(1);

Language prelude

connects internal primitives with surface syntax (types, operations)
conversions like intToNat32
side-effecting operations debugPrintInt (tie into execution environment)
utilities like hashInt, clzNat32

Sample App

Implementing Chat

type example
one server actor
multiple clients, each an instance of (actor) class Client.

Chat Server

actor Server {
  private var clients : List<Client> = null;

  private shared broadcast(message : Text) {
    var next = clients;
    loop {
      switch next {
        case null { return; }
        case (?l) { l.head.send(message); next := l.tail; };
      };
    };
  };

  public func subscribe(client : Client) : async Post {
    let cs = {head = client; var tail = clients};
    clients := ?cs;
    return broadcast;
  };
};

Example: The client class

type Server = actor { subscribe : Client -> async Post; };

actor class Client() = this {
  private var name : Text = "";
  public func start(n : Text , s : Server) {
    name := n;
    let _ = async {
       let post = await s.subscribe(this);
       post("hello from " # name);
       post("goodbye from " # name);
    }
  };

  public func send(msg : Text) {
    debugPrint(name # " received " # msg # "\n");
  };
};

Example: test

test

let bob = Client();
let alice = Client();
let charlie = Client();

bob.start("Bob", Server);
alice.start("Alice", Server);
charlie.start("Charlie", Server);

output

[nix-shell:~/motoko/guide]$ ../src/moc -r chat.mo
charlie received hello from bob
alice received hello from bob
bob received hello from bob
charlie received goodbye from bob
alice received goodbye from bob
bob received goodbye from bob
charlie received hello from alice
alice received hello from alice
bob received hello from alice
charlie received goodbye from alice
alice received goodbye from alice
bob received goodbye from alice
charlie received hello from charlie
alice received hello from charlie
bob received hello from charlie
charlie received goodbye from charlie
alice received goodbye from charlie
bob received goodbye from charlie