Language quick reference

Space, newline, horizontal tab, carriage return, line feed and form feed are considered as whitespace. Whitespace is ignored but used to separate adjacent keywords, identifiers and operators.

In the definition of some lexemes, the quick reference uses the symbol ␣ to denote a single whitespace character.

Single line comments are all characters following // until the end of the same line.

Single or multi-line comments are any sequence of characters delimited by /* and */:

Comments delimited by /* and */ may be nested, provided the nesting is well-bracketed.

Documentation comments start with /// followed by a space until the end of line, and get attached to the definition immediately following them.

Deprecation comments start with /// @deprecated followed by a space until the end of line, and get attached to the definition immediately following them. They are only recognized in front of public declarations.

All comments are treated as whitespace.

The following keywords are reserved and may not be used as identifiers:

Identifiers are alpha-numeric, start with a letter and may contain underscores:

Integers are written as decimal or hexadecimal, Ox-prefixed natural numbers. Subsequent digits may be prefixed a single, semantically irrelevant, underscore.

Negative integers may be constructed by applying a prefix negation - operation.

Floating point literals are written in decimal or Ox-prefixed hexadecimal scientific notation.

The 'e' (or 'E') prefixes a base 10, decimal exponent; 'p' (or 'P') prefixes a base 2, binary exponent. In both cases, the exponent is in decimal notation.

A character is a single quote (') delimited:

A text literal is "-delimited sequence of characters:

Literals are constant values. The syntactic validity of a literal depends on the precision of the type at which it is used.

Note that equality (==) and inequality (!=) do not have categories. Instead, equality and inequality are applicable to arguments of all shared types, including non-primitive, compound types such as immutable arrays, records, and variants.

Equality and inequality are structural and based on the observable content of their operands (as determined by their static type).

The category of a compound assignment <unop>=/<binop>= is given by the category of the operator <unop>/<binop>.

The following table defines the relative precedence and associativity of operators and tokens, ordered from lowest to highest precedence. Tokens on the same line have equal precedence with the indicated associativity.

The syntax of a program <prog> is as follows:

A program is a sequence of imports <imp>;* followed by a sequence of declarations <dec>;* that ends with an optional actor or actor class declaration. The actor or actor class declaration determines the main actor, if any, of the program.

For now, compiled programs must obey the following additional restrictions (not imposed on interpreted programs):

The last two restrictions are designed to forbid programmatic actor class recursion, pending compiler support.

Note that the parameters (if any) of an actor class must have shared type (see Sharability). The parameters of a program’s final actor class provide access to the corresponding canister installation argument(s); the Candid type of this argument is determined by the Candid projection of the Motoko type of the class parameter.

The syntax of an import <imp> is as follows:

An import introduces a resource referring to a local source module, module from a package of modules, or canister (imported as an actor). The contents of the resource are bound to <pat>.

Though typically a simple identifier, <id>, <pat> can also be any composite pattern binding selective components of the resource.

The pattern must be irrefutable.

The syntax of a library (that can be referenced in an import) is as follows:

A library <lib> is a sequence of imports <imp>;* followed by:

Libraries stored in .mo files may be referenced by import declarations.

In a module library, the optional name <id>? is only significant within the library and does not determine the name of the library when imported. Instead, the imported name of a library is determined by the import declaration, giving clients of the library the freedom to choose library names (e.g. to avoid clashes).

An actor class library, because it defines both a type constructor and a function with name <id>, is imported as a module defining both a type and a function named <id>. The name <id> is mandatory and cannot be omitted. An actor class constructor is always asynchronous, with return type async T where T is the inferred type of the class body. Because actor construction is asynchronous, an instance of an imported actor class can only be created in an asynchronous context (i.e. in the body of a (non-query) shared function or async expression).

The syntax of a declaration is as follows:

The syntax of a shared function qualifier with call-context pattern is as follows:

For <shared-pat>, an absent <pat>? is shorthand for the wildcard pattern _.

The visibility qualifier <vis>? determines the accessibility of every field <id> declared by <dec>:

The stability qualifier <stab> determines the upgrade behaviour of actor fields:

The syntax of an expression is as follows:

The syntax of a pattern is as follows:

Motoko provides the following primitive type identifiers, including support for Booleans, signed and unsigned integers and machine words of various sizes, characters and text.

The category of a type determines the operators (unary, binary, relational and in-place update via assignment) applicable to values of that type.

Although many of these types have linguistic support for literals and operators, each primitive type also has an eponymous base library providing related functions and values (see Motoko Base Library). For example, the Text library provides common functions on Text values.

The type Bool of category L (Logical) has values true and false and is supported by one and two branch if _ <exp> (else <exp>)?, not <exp>, _ and and or _ expressions. Expressions if, and and or are short-circuiting.

A Char of category O (Ordered) represents a character as a code point in the Unicode character set.

Base library function Char.toNat32(c) converts a Char value, c to its Nat32 code point. Function Char.fromNat32(n) converts a Nat32 value, n, in the range 0x0..xD7FF or 0xE000..0x10FFFF of valid code points to its Char value; this conversion traps on invalid arguments. Function Char.toText(c) converts the Char c into the corresponding, single character Text value.

The type Text of categories T and O (Text, Ordered) represents sequences of Unicode characters (i.e. strings). Function t.size returns the number of characters in Text value t. Operations on text values include concatenation (_ # _) and sequential iteration over characters via t.chars as in for (c : Char in t.chars()) { …​ c …​ }.

The type Float represents 64-bit floating point values of categories A (Arithmetic) and O (Ordered).

The semantics of Float and its operations is in accordance with standard IEEE 754-2019 (See [IEEE754]).

Common functions and values are defined in base library "base/Float".

The types Int and Nat are signed integral and natural numbers of categories A (Arithmetic) and O (Ordered).

Both Int and Nat are arbitrary precision, with only subtraction - on Nat trapping on underflow.

The subtype relation Nat <: Int holds, so every expression of type Nat is also an expression of type Int (but not vice versa). In particular, every value of type Nat is also a value of type Int, without change of representation.

The types Int8, Int16, Int32 and Int64 represent signed integers with respectively 8, 16, 32 and 64 bit precision. All have categories A (Arithmetic), B (Bitwise) and O (Ordered).

Operations that may under- or overflow the representation are checked and trap on error.

The operations +%, -%, *% and **% provide access to wrap-around, modular arithmetic.

As bitwise types, these types support bitwise operations and (&), or (|) and exclusive-or (^). Further, they can be rotated left (<<>), right (<>>), and shifted left (<<), right (>>). The right-shift preserves the two’s-complement sign. All shift and rotate amounts are considered modulo the numbers’s bit width n.

Bounded integer types are not in subtype relationship with each other or with other arithmetic types, and their literals need type annotation if the type cannot be inferred from context, e.g. (-42 : Int16).

The corresponding module in the base library provides conversion functions: Conversion to Int, checked and wrapping conversions from Int and wrapping conversion to the bounded natural type of the same size.

The types Nat8, Nat16, Nat32 and Nat64 represent unsigned integers with respectively 8, 16, 32 and 64 bit precision. All have categories A (Arithmetic), B (Bitwise) and O (Ordered).

Operations that may under- or overflow the representation are checked and trap on error.

The operations +%, -%, *% and **% provide access to the modular, wrap-on-overflow operations.

As bitwise types, these types support bitwise operations and (&), or (|) and exclusive-or (^). Further, they can be rotated left (<<>), right (<>>), and shifted left (<<), right (>>). The right-shift is logical. All shift and rotate amounts are considered modulo the number’s bit width n.

The corresponding module in the base library provides conversion functions: Conversion to Int, checked and wrapping conversions from Int and wrapping conversion to the bounded natural type of the same size.

The type Blob of category O (Ordered) represents binary blobs or sequences of bytes. Function b.size returns the number of characters in Blob value b. Operations on blob values include sequential iteration over bytes via function b.vals as in for (v : Nat8 in b.vals()) { …​ v …​ }.

The type Principal of category O (Ordered) represents opaque principals such as canisters and users that can, for example, be used to identify callers of shared functions and used for simple authentication. Although opaque, principals may be converted to binary Blob values for more efficient hashing and other applications (see module Principal from the base library).

Assuming base library import,

Errors are opaque values constructed and examined with operations:

Type E.ErrorCode is equivalent to variant type:

A constructed error e = E.reject(t) has E.code(e) = #canister_reject and E.message(e) = t.

Error values can be thrown and caught within an async expression or shared function (only). See Throw and Try.

Errors with codes other than #canister_reject (i.e. system errors) may be caught and thrown, but not user-constructed.

<path> <typ-args>? is the application of a type identifier or path, either built-in (i.e. Int) or user defined, to zero or more type arguments. The type arguments must satisfy the bounds, if any, expected by the type constructor’s type parameters (see Well-formed types).

Though typically a type identifier, more generally, <path> may be a .-separated sequence of actor, object or module identifiers ending in an identifier accessing a type component of a value (for example, Acme.Collections.List).

<sort>? { <typ-field>;* } specifies an object type by listing its zero or more named type fields.

Within an object type, the names of fields must be distinct (both by name and hash value).

Object types that differ only in the ordering of the fields are equivalent.

When <sort>? is actor, all fields have shared function type (specifying messages).

{ <typ-tag>;* } specifies a variant type by listing its variant type fields as a sequence of `<typ-tag>`s.

Within a variant type, the tags of its variants must be distinct (both by name and hash value).

Variant types that differ only in the ordering of their variant type fields are equivalent.

{ # } specifies the empty variant type.

[ var? <typ> ] specifies the type of arrays with elements of type <typ>.

Arrays are immutable unless specified with qualifier var.

The Null type has a single value, the literal null. Null is a subtype of the option ? T, for any type T.

? <typ> specifies the type of values that are either null or a proper value of the form ? <v> where <v> has type <typ>.

Type <shared>? <typ-params>? <typ1> -> <typ2> specifies the type of functions that consume (optional) type parameters <typ-params>, consume a value parameter of type <typ1> and produce a result of type <typ2>.

Both <typ1> and <typ2> may reference type parameters declared in <typ-params>.

If <typ1> or <typ2> (or both) is a tuple type, then the length of that tuple type determines the argument or result arity of the function type.

The optional <shared> qualifier specifies whether the function value is shared, which further constrains the form of <typ-params>, <typ1> and <typ2> (see Sharability below).

(Note that a <shared> function may itself be shared or shared query, determining the persistence of its state changes.)

async <typ> specifies a future producing a value of type <typ>.

Future types typically appear as the result type of a shared function that produces an await-able value.

( ((<id> :)? <typ>),* ) specifies the type of a tuple with zero or more ordered components.

The optional identifier <id>, naming its components, is for documentation purposes only and cannot be used for component access. In particular, tuple types that differ only in the names of components are equivalent.

The empty tuple type () is called the unit type.

Type Any is the top type, i.e. the super-type of all types. All values have type Any.

Type None is the bottom type, a subtype of all other types. No value has type None.

As an empty type, None can be used to specify the impossible return value of an infinite loop or unconditional trap.

The type expression <typ1> and <typ2> denotes the syntactic intersection between its two type operands, that is, the greatest type that is a subtype of both. If both types are incompatible, the intersection is None.

The intersection is syntactic, in that it does not consider possible instantiations of type variables. The intersection of two type variables is None, unless they are equal, or one is declared to be a (direct or indirect) subtype of the other.

The type expression <typ1> or <typ2> denotes the syntactic union between its two type operands, that is, the smallest type that is a supertype of both. If both types are incompatible, the union is Any.

The union is syntactic, in that it does not consider possible instantiations of type variables. The union of two type variables is the union of their bounds, unless the variables are equal, or one is declared to be a (direct or indirect) subtype of the other.

A function that takes an immediate, syntactic tuple of length n >= 0 as its domain or range is a function that takes (respectively returns) n values.

When enclosing the argument or result type of a function, which is itself a tuple type, ( <tuple-typ> ) declares that the function takes or returns a single (boxed) value of type <tuple-type>.

In all other positions, ( <typ> ) has the same meaning as <typ>.

A type field specifies the name and type of a field of an object. The field names within a single object type must be distinct and have non-colliding hashes.

<id> : <typ> specifies an immutable field, named <id> of type <typ>.

var <id> : <typ> specifies a mutable field, named <id> of type <typ>.

A variant type field specifies the tag and type of a single variant of an enclosing variant type. The tags within a single variant type must be distinct and have non-colliding hashes.

# <id> : <typ> specifies an (immutable) field, named <id> of type <typ>. # <id> is sugar for an (immutable) field, named <id> of type ().

When enclosed by an actor object type, <id> <typ-params>? <typ1> : <typ2> is syntactic sugar for an immutable field named <id> of shared function type shared <typ-params>? <typ1> → <typ2>.

When enclosed by a non-actor object type, <id> <typ-params>? <typ1> : <typ2> is syntactic sugar for an immutable field named <id> of ordinary function type <typ-params>? <typ1> → <typ2>.

A type constructors, function value or function type may be parameterised by a vector of comma-separated, optionally constrained, type parameters.

<id> <: <typ> declares a type parameter with constraint <typ>. Any instantiation of <id> must subtype <typ> (at that same instantiation).

Syntactic sugar <id> declares a type parameter with implicit, trivial constraint Any.

The names of type parameters in a vector must be distinct.

All type parameters declared in a vector are in scope within its bounds.

Type constructors and functions may take type arguments.

The number of type arguments must agree with the number of declared type parameters of the type constructor.

For a function, the number of type arguments, when provided, must agree with the number of declared type parameters of the function’s type. Note that type arguments in function applications can typically be omitted and inferred by the compiler.

Given a vector of type arguments instantiating a vector of type parameters, each type argument must satisfy the instantiated bounds of the corresponding type parameter.

A type T is well-formed only if (recursively) its constituent types are well-formed, and:

Two types T, U are related by subtyping, written T <: U, whenever, one of the following conditions is true:

A type T is shared if it is

Stability extends sharability to include mutable types. More precisely:

A type T is stable if it is

This definition implies that every shared type is a stable type. The converse does not hold: there are types that are stable but not shared (notably types with mutable components).

The types of actor fields declared with the stable qualifier must have stable type.

The (current) value of such a field is preserved upon upgrade, whereas the values of other fields are reinitialized after an upgrade.

A program <imp>;* <dec>;* has type T provided:

All type and value declarations within <dec>;* are mutually-recursive.

A program evaluates by (transitively) evaluating the imports, binding their values to the identifiers in <imp>;* and then evaluating the sequence of declarations in <dec>;*.

Restrictions on the syntactic form of modules means that libraries can have no side-effects.

The imports of a library are local and not re-exported in its interface.

Multiple imports of the same library can be safely deduplicated without loss of side-effects.

An import import <pat> =? <url> declares a pattern <pat> bound to the contents of the text literal <url>.

<url> is a text literal that designates some resource: a local library specified with a relative path, a named module from a named package, or an external canister, referenced either by numeric canister id or by a named alias, and imported as a Motoko actor.

In detail, if <url> is of the form:

The case sensitivity of file references depends on the host operating system so it is recommended not to distinguish resources by filename casing alone.

(Remark: when building multi-canister projects with the DFINITY Canister SDK, Motoko programs can typically import canisters by alias (e.g. import C "canister:counter"), without specifying low-level canister ids (e.g. import C "ic:lg264-qjkae"). The SDK tooling takes care of supplying the appropriate command-line arguments to the Motoko compiler.)

(Remark: sensible choices for <pat> are identifiers, such as Array, or object patterns like { cons; nil = empty }, which allow selective importing of individual fields, under original or other names.)

A declaration field <vis>? <stab>? <dec> defines zero or more fields of an actor or object, according to the set of variables defined by <dec>.

Any identifier bound by a public declaration appears in the type of enclosing object, module or actor and is accessible via the dot notation.

An identifier bound by a private or system declaration is excluded from the type of the enclosing object, module or actor and thus inaccessible.

The declaration field has type T provided:

(Actor fields declared flexible (implicitly or explicitly) can have any type, but will not be preserved across upgrades.)

Sequences of declaration fields are evaluated in order by evaluating their constituent declarations, with the following exception:

During an upgrade only, the value of a stable declaration is obtained as follows:

For an upgrade to be safe:

This condition ensures that every stable variable is either fresh, requiring initialization, or its value can be safely inherited from the retired actor. Note that stable variables may be removed across upgrades, or may simply be deprecated by an upgrade to type Any.

A sequence of declarations <dec>;* occurring in a block, a program or embedded in the <dec-field>;* sequence of an object body has type T provided:

Declarations in <dec>;* are evaluated sequentially. The first declaration that traps causes the entire sequence to trap. Otherwise, the result of the declaration is the value of the last declaration in <dec>;*. In addition, the set of value bindings defined by <dec>;* is the union of the bindings introduced by each declaration in <dec>;*.

It is a compile-time error if any declaration in <dec>;* might require the value of an identifier declared in <dec>;* before that identifier’s declaration has been evaluated. Such use-before-define errors are detected by a simple, conservative static analysis not described here.

Patterns bind function parameters, declare identifiers and decompose values into their constituent parts in the cases of a switch expression.

Matching a pattern against a value may succeed, binding the corresponding identifiers in the pattern to their matching values, or fail. Thus the result of a match is either a successful binding, mapping identifiers of the pattern to values, or failure.

The consequences of pattern match failure depends on the context of the pattern.

The wildcard pattern _ matches a single value without binding its contents to an identifier.

The identifier pattern <id> matches a single value and binds it to the identifier <id>.

The literal pattern <unop>? <lit> matches a single value against the constant value of literal <lit> and fails if they are not (structurally) equal values.

For integer literals only, the optional <unop> determines the sign of the value to match.

The tuple pattern ( <pat>,* ) matches a n-tuple value against an n-tuple of patterns (both the tuple and pattern must have the same number of items). The set of identifiers bound by each component of the tuple pattern must be distinct.

The empty tuple pattern () is called the unit pattern.

Pattern matching fails if one of the patterns fails to match the corresponding item of the tuple value. Pattern matching succeeds if every pattern matches the corresponding component of the tuple value. The binding returned by a successful match is the disjoint union of the bindings returned by the component matches.

The object pattern { <pat-field>;* } matches an object value, a collection of named field values, against a sequence of named pattern fields. The set of identifiers bound by each field of the object pattern must be distinct. The names of the pattern fields in the object pattern must be distinct.

Object patterns support punning for concision. A punned field <id> is shorthand for <id> = <id>; Similarly, a typed, punned field <id> : <typ> is short-hand for <id> = <id> : <typ>. Both bind the matched value of the field named <id> to the identifier <id>.

Pattern matching fails if one of the pattern fields fails to match the corresponding field value of the object value. Pattern matching succeeds if every pattern field matches the corresponding named field of the object value. The binding returned by a successful match is the union of the bindings returned by the field matches.

The <sort> of the matched object type must be determined by an enclosing type annotation or other contextual type information.

The variant pattern # <id> <pat>? matches a variant value (of the form # <id'> v) against a variant pattern. An absent <pat>? is shorthand for the unit pattern (()). Pattern matching fails if the tag <id'> of the value is distinct from the tag <id> of the pattern (i.e. <id> <> <id'>); or the tags are equal but the value v does not match the pattern <pat>?. Pattern matching succeeds if the tag of the value is <id> (i.e. <id'> = <id>) and the value v matches the pattern <pat>?. The binding returned by a successful match is just the binding returned by the match of v against <pat>?.

The annotated pattern <pat> : <typ> matches value of v type <typ> against the pattern <pat>.

<pat> : <typ> is not a dynamic type test, but is used to constrain the types of identifiers bound in <pat>, e.g. in the argument pattern to a function.

The option ? <pat> matches a value of option type ? <typ>.

The match fails if the value is null. If the value is ? v, for some value v, then the result of matching ? <pat> is the result of matching v against <pat>.

Conversely, the null literal pattern may be used to test whether a value of option type is the value null and not ? v for some v.

The or pattern <pat1> or <pat2> is a disjunctive pattern.

The result of matching <pat1> or <pat2> against a value is the result of matching <pat1>, if it succeeds, or the result of matching <pat2>, if the first match fails.

(Note, statically, neither <pat1> nor <pat2> may contain identifier (<id>) patterns so a successful match always binds zero identifiers.)

The declaration <exp> has type T provided the expression <exp> has type T . It declares no bindings.

The declaration <exp> evaluates to the result of evaluating <exp> (typically for `<exp>’s side-effect).

Note that if <exp> appears within a sequence of declarations, but not as the last declaration of that sequence, then T must be ().

The let declaration let <pat> = <exp> has type T and declares the bindings in <pat> provided:

The declaration let <pat> = <exp> evaluates <exp> to a result r. If r is trap, the declaration evaluates to trap. If r is a value v then evaluation proceeds by matching the value v against <pat>. If matching fails, then the result is trap. Otherwise, the result is v and the binding of all identifiers in <pat> to their matching values in v.

All bindings declared by a let (if any) are immutable.

The variable declaration var <id> (: <typ>)? = <exp> declares a mutable variable <id> with initial value <exp>. The variable’s value can be updated by assignment.

The declaration var <id> has type () provided:

Within the scope of the declaration, <id> has type var T (see Assignment).

Evaluation of var <id> (: <typ>)? = <exp> proceeds by evaluating <exp> to a result r. If r is trap, the declaration evaluates to trap. Otherwise, the r is some value v that determines the initial value of mutable variable <id>. The result of the declaration is () and <id> is bound to a fresh location that contains v.

The declaration type <id> <typ-params>? = <typ> declares a new type constructor <id>, with optional type parameters <typ-params> and definition <typ>.

The declaration type C < X0 <: T0>, …​, Xn <: Tn > = U is well-formed provided:

In scope of the declaration type C < X0<:T0>, …​, Xn <: Tn > = U, any well-formed type C < U0, …​, Un> is equivalent to its expansion U [ U0/X0, …​, Un/Xn ]. Distinct type expressions that expand to identical types are inter-changeable, regardless of any distinction between type constructor names. In short, the equivalence between types is structural, not nominal.

Declaration <sort> <id>? <obj-body>, where <obj_body> is of the form =? { <dec-field>;* }, declares an object with optional identifier <id> and zero or more fields <dec-field>;*. Fields can be declared with public or private visibility; if the visibility is omitted, it defaults to private.

The qualifier <sort> (one of actor, module or object) specifies the sort of the object’s type. The sort imposes restrictions on the types of the public object fields.

Let T = <sort> { [var0] id0 : T0, …​ , [varn] idn : T0 } denote the type of the object. Let <dec>;* be the sequence of declarations embedded in <dec-field>;*. The object declaration has type T provided that:

Note that requirement 1. imposes further constraints on the field types of T. In particular, if the sort is actor then:

Because actor construction is asynchronous, an actor declaration can only occur in an asynchronous context (i.e. in the body of a (non-query) shared function or async expression).

Evaluation of <sort>? <id>? =? { <dec-field>;* } proceeds by by binding <id> (if present), to the eventual value v, and evaluating the declarations in <dec>;*. If the evaluation of <dec>;* traps, so does the object declaration. Otherwise, <dec>;* produces a set of bindings for identifiers in Id. let v0, …​, vn be the values or locations bound to identifiers <id0>, …​, <idn>. The result of the object declaration is the object v == sort { <id0> = v1, …​, <idn> = vn}.

If <id>? is present, the declaration binds <id> to v. Otherwise, it produces the empty set of bindings.

The function declaration <shared-pat>? func <id>? <typ-params>? <pat> (: <typ>)? =? <exp> is syntactic sugar for a named let or anonymous declaration of a function expression.

That is, when <id>? is present and the function is named:

But when <id>? is absent and the function is anonymous:

Named function definitions support recursion (a named function can call itself).

The class declaration <shared-pat>? <sort>? class <id>? <typ-params>? <pat> (: <typ>)? <class-body> is sugar for pair of a type and function declaration:

where:

Note <shared-pat>? must not be of the form shared query <pat>?: a constructor, unlike a function, cannot be a query.

An absent <shared-pat>? defaults to shared when sort = actor.

If sort is actor, then:

If (: <typ>) is present, then the type <async?> <sort> { <typ_field>;* } must be a subtype of the annotation <typ>. In particular, the annotation is used only to check, but not affect, the inferred type of function <id>.

The class declaration has the same type as function <id> and evaluates to the function value <id>.

The identifier expression <id> has type T provided <id> is in scope, defined and declared with explicit or inferred type T.

The expression <id> evaluates to the value bound to <id> in the current evaluation environment.

A literal has type T only when its value is within the prescribed range of values of type T.

The literal (or constant) expression <lit> evaluates to itself.

The unary operator <unop> <exp> has type T provided:

The unary operator expression <unop> <exp> evaluates <exp> to a result. If the result is a value v, it returns the result of <unop> v. If the result is trap, the entire expression results in trap.

The binary operator expression <exp1> <binop> <exp2> has type T provided:

The binary operator expression <exp1> <binop> <exp2> evaluates exp1 to a result r1. If r1 is trap, the expression results in trap.

Otherwise, exp2 is evaluated to a result r2. If r2 is trap, the expression results in trap.

Otherwise, r1 and r2 are values v1 and v2 and the expression returns the result of v1 <binop> v2.

The relational expression <exp1> <relop> <exp2> has type Bool provided:

The binary operator expression <exp1> <relop> <exp2> evaluates exp1 to a result r1. If r1 is trap, the expression results in trap.

Otherwise, exp2 is evaluated to a result r2. If r2 is trap, the expression results in trap.

Otherwise, r1 and r2 are values v1 and v2 and the expression returns the Boolean result of v1 <relop> v2.

For equality and inequality, the meaning of v1 <relop> v2 depends on the compile-time, static choice of T (not the run-time types of v1 and v2, which, due to subtyping, may be more precise).

Tuple expression (<exp1>, …​, <expn>) has tuple type (T1, …​, Tn), provided <exp1>, …​, <expn> have types T1, …​, Tn.

The tuple expression (<exp1>, …​, <expn>) evaluates the expressions exp1 …​ expn in order, trapping as soon as some expression <expi> traps. If no evaluation traps and exp1, …​, <expn> evaluate to values v1,…​,vn then the tuple expression returns the tuple value (v1, …​ , vn).

The tuple projection <exp> . <nat> has type Ti provided <exp> has tuple type (T1, …​, Ti, …​, Tn), <nat> == i and 1 <= i <= n.

The projection <exp> . <nat> evaluates <exp> to a result r. If r is trap, then the result is trap. Otherwise, r must be a tuple (v1,…​,vi,…​,vn) and the result of the projection is the value vi.

The empty tuple expression () is called the unit value.

The option expression ? <exp> has type ? T provided <exp> has type T.

The literal null has type Null. Since Null <: ? T for any T, literal null also has type ? T and signifies the "missing" value at type ? T.

The variant injection # <id> <exp> has variant type {# id T} provided: * <exp> has type T.

The variant injection # <id> is just syntactic sugar for # <id> ().

The variant injection`# <id> <exp>` evaluates <exp> to a result r. If r is trap, then the result is trap. Otherwise, r must be a value v and the result of the injection is the tagged value # <id> v.

The tag and contents of a variant value can be tested and accessed using a variant pattern.

Objects can be written in literal form { <exp-field>;* }, consisting of a list of expression fields:

Such an object literal, sometimes called a record, is equivalent to the object declaration object { <dec-field>;* } where the declaration fields are obtained from the expression fields by prefixing each of them with public let, or just public in case of var fields. However, unlike declarations, the field list does not bind each <id> as a local name within the literal, i.e., the field names are not in scope in the field expressions.

Object expressions support punning for concision. A punned field <id> is shorthand for <id> = <id>; Similarly, a typed, punned field <id> : <typ> is short-hand for <id> = <id> : <typ>. Both associate the field named <id> with the value of the identifier <id>.

The object projection <exp> . <id> has type var? T provided <exp> has object type sort { var1? <id1> : T1, …​, var? <id> : T, …​, var? <idn> : Tn } for some sort sort.

The object projection <exp> . <id> evaluates <exp> to a result r. If r is trap, then the result is trap. Otherwise, r must be an object value { <id1> = v1,…​, id = v, …​, <idn> = vn } and the result of the projection is the value v of field id.

If var is absent from var? T then the value v is the constant value of immutable field <id>, otherwise:

The iterator access <exp> . <id> has type T provided <exp> has type U, and U,<id> and T are related by a row of the following table:

The projection <exp> . <id> evaluates <exp> to a result r. If r is trap, then the result is trap. Otherwise, r must be a value of type U and the result of the projection is a value of type T whose semantics is given by the Description column of the previous table.

The assignment <exp1> := <exp2> has type () provided:

The assignment expression <exp1> := <exp2> evaluates <exp1> to a result r1. If r1 is trap, the expression results in trap.

Otherwise, exp2 is evaluated to a result r2. If r2 is trap, the expression results in trap.

Otherwise r1 and r2 are (respectively) a location v1 (a mutable identifier, an item of a mutable array or a mutable field of an object) and a value v2. The expression updates the current value stored in v1 with the new value v2 and returns the empty tuple ().

The unary compound assignment <unop>= <exp> has type () provided:

The unary compound assignment <unop>= <exp> evaluates <exp> to a result r. If r is trap the evaluation traps, otherwise r is a location storing value v and r is updated to contain the value <unop> v.

The binary compound assignment <exp1> <binop>= <exp2> has type () provided:

For binary operator <binop>, the compound assignment expression <exp1> <binop>= <exp2> evaluates <exp1> to a result r1. If r1 is trap, the expression results in trap. Otherwise, exp2 is evaluated to a result r2. If r2 is trap, the expression results in trap.

Otherwise r1 and r2 are (respectively) a location v1 (a mutable identifier, an item of a mutable array or a mutable field of object) and a value v2. The expression updates the current value, w stored in v1 with the new value w <binop> v2 and returns the empty tuple ().

The expression [ var? <exp>,* ] has type [var? T] provided each expression <exp> in the sequence <exp>,* has type T.

The array expression [ var <exp0>, …​, <expn> ] evaluates the expressions exp0 …​ expn in order, trapping as soon as some expression <expi> traps. If no evaluation traps and exp0, …​, <expn> evaluate to values v0,…​,vn then the array expression returns the array value [var? v0, …​ , vn] (of size n+1).

The array indexing expression <exp1> [ <exp2> ] has type var? T provided:

The expression <exp1> [ <exp2> ] evaluates exp1 to a result r1. If r1 is trap, then the result is trap.

Otherwise, exp2 is evaluated to a result r2. If r2 is trap, the expression results in trap.

Otherwise, r1 is an array value, var? [v0, …​, vn], and r2 is a natural integer i. If i > n the index expression returns trap.

Otherwise, the index expression returns the value v, obtained as follows:

If var is absent from var? T then the value v is the constant value vi.

Otherwise,

The function call expression <exp1> <T0,…​,Tn>? <exp2> has type T provided:

The call expression <exp1> <T0,…​,Tn>? <exp2> evaluates exp1 to a result r1. If r1 is trap, then the result is trap.

Otherwise, exp2 is evaluated to a result r2. If r2 is trap, the expression results in trap.

Otherwise, r1 is a function value, <shared-pat>? func <X0 <: V0, …​, n <: Vn> <pat1> { <exp> } (for some implicit environment), and r2 is a value v2. If <shared-pat> is present and of the form shared query? <pat> then evaluation continues by matching the record value {caller = p} against <pat>, where p is the Principal invoking the function (typically a user or canister). Matching continues by matching v1 against <pat1>. If pattern matching succeeds with some bindings, then evaluation returns the result of <exp> in the environment of the function value (not shown) extended with those bindings. Otherwise, some pattern match has failed and the call results in trap.

The function expression <shared-pat>? func < X0 <: T0, …​, Xn <: Tn > <pat1> (: U2)? =? <block-or-exp> has type <shared>? < X0 <: T0, ..., Xn <: Tn > U1-> U2 if, under the assumption that X0 <: T0, …​, Xn <: Tn:

<shared-pat>? func <typ-params>? <pat1> (: <typ>)? =? <block-or-exp> evaluates to a function value (a.k.a. closure), denoted <shared-pat>? func <typ-params>? <pat1> = <exp>, that stores the code of the function together with the bindings from the current evaluation environment (not shown) needed to evaluate calls to the function value.

Note that a <shared-pat> function may itself be shared <pat> or shared query <pat>:

In either case, <pat> provides access to a context value identifying the caller of the shared (query) function.

The block expression { <dec>;* } has type T provided the last declaration in the sequence <dec>;* has type T. All identifiers declared in block must be distinct type identifiers or distinct value identifiers and are in scope in the definition of all other declarations in the block.

The bindings of identifiers declared in { dec;* } are local to the block.

The type system ensures that a value identifier cannot be evaluated before its declaration has been evaluated, precluding run-time errors at the cost of rejection some well-behaved programs.

Identifiers whose types cannot be inferred from their declaration, but are used in a forward reference, may require an additional type annotation (see Annotated pattern) to satisfy the type checker.

The block expression { <dec>;* } evaluates each declaration in <dec>;* in sequence (program order). The first declaration in <dec>;* that results in a trap causes the block to result in trap, without evaluating subsequent declarations.

The do expression do <block> allows the use of a block as an expression, in positions where the syntax would not directly allow a block.

The expression do <block> has type T provided <block> has type T.

The do expression evaluates by evaluating <block> and returning its result.

The option block do ? <block> introduces scoped handling of null values.

The expression do ? <bock> has type ?T provided <block> has type T.

The do ? <block> expression evaluates <block> and returns its result as an optional value.

Within <block> the null break expression <exp1> ! exits the nearest enclosing do ? block with value null whenever <exp1> has value null, or continues evaluation with the contents of <exp1>'s option value. (See Null break.)

Option blocks nest with the target of a null break determined by the nearest enclosing option block.

The null break expression <exp> ! invokes scoped handling of null values and returns the contents of an option value or changes control-flow when the value is null.

It has type T provided:

The expression <exp> ! evaluates <exp> to a result r. If r is trap, then the result is trap; if r is null, execution breaks with value null from the nearest enclosing option block of form do ? <block>; otherwise, r is ? v and execution continues with value v.

The not expression not <exp> has type Bool provided <exp> has type Bool.

If <exp> evaluates to trap, the expression returns trap. Otherwise, <exp> evaluates to a Boolean value v and the expression returns not v, (the Boolean negation of v).

The and expression <exp1> and <exp2> has type Bool provided <exp1> and <exp2> have type Bool.

The expression <exp1> and <exp2> evaluates exp1 to a result r1. If r1 is trap, the expression results in trap. Otherwise r1 is a Boolean value v. If v == false the expression returns the value false (without evaluating <exp2>). Otherwise, the expression returns the result of evaluating <exp2>.

The or expression <exp1> or <exp2> has type Bool provided <exp1> and <exp2> have type Bool.

The expression <exp1> and <exp2> evaluates exp1 to a result r1. If r1 is trap, the expression results in trap. Otherwise r1 is a Boolean value v. If v == true the expression returns the value true (without evaluating <exp2>). Otherwise, the expression returns the result of evaluating <exp2>.

The expression if <exp1> <exp2> (else <exp3>)? has type T provided:

The expression evaluates <exp1> to a result r1. If r1 is trap, the result is trap. Otherwise, r1 is the value true or false. If r1 is true, the result is the result of evaluating <exp2>. Otherwise, r1 is false and the result is () (if <exp3> is absent) or the result of <exp3> (if <exp3> is present).

The switch expression switch <exp> { (case <pat> <block-or-exp>;)+ } has type T provided:

The expression evaluates <exp> to a result r. If r is trap, the result is trap. Otherwise, r is some value v. Let case <pat> <block-or-exp>; be the first case in (case <pat> <block-or-exp>;)+ such that <pat> matches v for some binding of identifiers to values. Then result of the switch is the result of evaluating <block-or-exp> under that binding. If no case has a pattern that matches v, the result of the switch is trap.

The expression while <exp1> <exp2> has type () provided:

The expression evaluates <exp1> to a result r1. If r1 is trap, the result is trap. Otherwise, r1 is the value true or false. If r1 is true, the result is the result of re-evaluating while <exp1> <exp2>. Otherwise, the result is ().

The expression loop <block-or-exp> has type None provided <block-or-exp> has type ().

The expression evaluates <block-or-exp> to a result r1. If r1 is trap, the result is trap. Otherwise, the result is the result of (re-)evaluating loop <block-or-exp>.

The expression loop <block-or-exp1> while <exp2> has type () provided:

The expression evaluates <block-or-exp1> to a result r1. If r1 is trap, the result is trap. Otherwise, evaluation continues with <exp2>, producing result r2. If r2 is trap the result is trap. Otherwise, if r2 is true, the result is the result of re-evaluating loop <block-or-exp1> while <exp2>. Otherwise, r2 is false and the result is ().

The iterator expression for ( <pat> in <exp1> ) <block-or-exp2> has type () provided:

The for-expression is syntactic sugar for

where x and l are fresh identifiers.

In particular, the for loop will trap if evaluation of <exp1> traps; as soon as x.next() traps, or the value of x.next() does not match pattern <pat>, or when <block-or-exp2> traps.

The label-expression label <id> (: <typ>)? <block-or-exp> has type T provided:

The result of evaluating label <id> (: <typ>)? <block-or-exp> is the result of evaluating <block-or-exp>.

If <exp> in label <id> (: <typ>)? <exp> is a looping construct:

the body, <exp1>, of the loop is implicitly enclosed in label <id_continue> (…​) allowing early continuation of the loop by the evaluation of expression continue <id>.

<id_continue> is fresh identifier that can only be referenced by continue <id> (through its implicit expansion to break <id_continue>).

The expression break <id> is equivalent to break <id> ().

The expression break <id> <exp> has type None provided:

The evaluation of break <id> <exp> evaluates exp to some result r. If r is trap, the result is trap. If r is a value v, the evaluation abandons the current computation up to dynamically enclosing declaration label <id> …​ using the value v as the result of that labelled expression.

The expression continue <id> is equivalent to break <id_continue>, where <id_continue> is implicitly declared around the bodies of <id>-labelled looping constructs (see Labeled loops).

The expression return is equivalent to return ().

The expression return <exp> has type None provided:

The return expression exits the corresponding dynamic function invocation or completes the corresponding dynamic async expression with the result of <exp>.

The async expression async <block-or-exp> has type async T provided:

Any control-flow label in scope for async <block-or-exp> is not in scope for <block-or-exp>. However, <block-or-exp> may declare and use its own, local, labels.

The implicit return type in <block-or-exp> is T. That is, the return expression, <exp0>, (implicit or explicit) to any enclosed return <exp0>? expression, must have type T.

Evaluation of async <block-or-exp> queues a message to evaluate <block-or-exp> in the nearest enclosing or top-level actor. It immediately returns a future of type async T that can be used to await the result of the pending evaluation of <exp>.

The await expression await <exp> has type T provided:

Expression await <exp> evaluates <exp> to a result r. If r is trap, evaluation returns trap. Otherwise r is a future. If the future is incomplete, that is, its evaluation is still pending, await <exp> suspends evaluation of the neared enclosing async or shared-function, adding the suspension to the wait-queue of the future. Execution of the suspension is resumed once the future is completed (if ever). If the future is complete with value v, then await <exp> suspends evaluation and schedules resumption of execution with value v. If the future is complete with (thrown) error value e, then await <exp> suspends evaluation and schedules resumption of execution by re-throwing the error e.

Note: suspending computation on await, regardless of the dynamic status of the future, ensures that all tentative state changes and message sends prior to the await are committed and irrevocable.

The throw expression throw <exp> has type None provided:

Expression throw <exp> evaluates <exp> to a result r. If r is trap, evaluation returns trap. Otherwise r is an error value e. Execution proceeds from the catch clause of the nearest enclosing try <block-or-exp1> catch <pat> <block-or-exp2> whose pattern <pat> matches value e. If there is no such try expression, e is stored as the erroneous result of the async value of the nearest enclosing async expression or shared function invocation.

The try expression try <block-or-exp1> catch <pat> <block-or-exp2> has type T provided:

Expression try <block-or-exp1> catch <pat> <block-or-exp2> evaluates <block-or-exp1> to a result r. If evaluation of <block-or-exp1> throws an uncaught error value e, the result of the try is the result of evaluating <block-or-exp2> under the bindings determined by the match of e against pat.

See Error type.

The assert expression assert <exp> has type () provided <exp> has type Bool.

Expression assert <exp> evaluates <exp> to a result r. If r is trap evaluation returns trap. Otherwise r is a Boolean value v. The result of assert <exp> is:

The type annotation expression <exp> : <typ> has type T provided:

Type annotation may be used to aid the type-checker when it cannot otherwise determine the type of <exp> or when one wants to constrain the inferred type, U of <exp> to a less-informative super-type T provided U <: T.

The result of evaluating <exp> : <typ> is the result of evaluating <exp>.

The Candid serialization expression to_candid ( <exp>,*) has type Blob provided:

Expression to_candid ( <exp>,* ) evaluates the expression sequence ( <exp>,* ) to a result r. If r is trap, evaluation returns trap. Otherwise, r is a sequence of Motoko values vs. The result of evaluating to_candid ( <exp>,* ) is some Candid blob b = encode((T1,...,TN))(vs), encoding vs.

The Candid deserialization expression from_candid <exp> has type ?(T1,…​,Tn) provided:

Expression from_candid <exp> evaluates <exp> to a result r. If r is trap, evaluation returns trap. Otherwise r is a binary blob b. If b Candid-decodes to Candid value sequence Vs of type ea((T1,...,TN)) then the result of from_candid is ?v where v = decode((T1,...,TN))(Vs). If b Candid-decodes to a Candid value sequence Vs that is not of Candid type ea((T1,...,TN)) (but well-formed at some other type) then the result is null. If b is not the encoding of any well-typed Candid value, but some arbitrary binary blob, then the result of from_candid is a trap.

(Informally, here ea(_) is the Motoko-to-Candid type sequence translation and encode/decode((T1,...,TN))(_) are type-directed Motoko-Candid value translations.)

The declaration expression <dec> has type T provided the declaration <dec> has type T.

Evaluating the expression <dec> proceeds by evaluating <dec>, returning the result of <dec> but discarding the bindings introduced by <dec> (if any).

(The expression <dec> is actually shorthand for the block expression { <dec> }.)

The expression ignore <exp> has type () provided the expression <exp> has type Any .

The expression ignore <exp> evaluates <exp> (typically for some side-effect) but discards its value.

Ignore is useful for evaluating an expression within a sequence of declarations when that expression has non-unit type (and the simpler <exp> declaration would be ill-typed). Then the semantics is equivalent to let _ = <exp> : Any.

The debug expression debug <block-or-exp> has type () provided the expression <block-or-exp> has type ().

When the program is compiled or interpreted with (default) flag --debug, evaluating the expression debug <exp> proceeds by evaluating <block-or-exp>, returning the result of <block-or-exp>.

When the program is compiled or interpreted with flag --release, evaluating the expression debug <exp> immediately returns the unit value (). The code for <block-or-exp> is never executed, nor is its code included in the compiled binary.

The actor reference actor <exp> has expected type T provided:

The argument <exp> must be, or evaluate to, the textual format of an IC canister identifier (specified elsewhere), otherwise the expression traps. The result of the expression is an actor value representing that canister.

The validity of the canister identifier and its asserted type T are promises and taken on trust.

An invalid canister identifier or type may manifest itself, if at all, as a later dynamic failure when calling a function on the actor’s proclaimed interface, which will either fail or be rejected.

The parenthesized expression ( <exp> ) has type T provided <exp> has type T.

The result of evaluating ( <exp> ) is the result of evaluating <exp>.

Whenever <exp> has type T and T <: U (T subtypes U) then by virtue of implicit subsumption, <exp> also has type U (without extra syntax).

In general, this means that an expression of a more specific type may appear wherever an expression of a more general type is expected, provided the specific and general types are related by subtyping. This static change of type has no runtime cost.