# Language quick reference This section serves as a technical reference for the previous chapters and has specific technical information for readers with specific interests. For example, this section provides technical details of interest to the following audiences: - Authors providing the higher-level documentation about the Motoko programming language. - Compiler experts interested in the details of Motoko and its compiler. - Advanced programmers who want to learn more about the lower-level details of Motoko. The language quick reference is intended to provide complete reference information about Motoko, but this section does *not* provide explanatory text or usage information. Therefore, this section is typically not suitable for readers who are new to programming languages or who are looking for a general introduction to using Motoko. Throughout, we use the term canister to refer to an Internet Computer canister smart contract. ## Basic language syntax This section describes the basic language conventions you need to know for programming in Motoko. ### Whitespace 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. ### Comments Single line comments are all characters following `//` until the end of the same line. ``` motoko no-repl // single line comment x = 1 ``` Single or multi-line comments are any sequence of characters delimited by `/*` and `*/`: ``` motoko no-repl /* multi-line comments look like this, as in C and friends */ ``` Comments delimited by `/*` and `*/` may be nested, provided the nesting is well-bracketed. ``` motoko no-repl /// I'm a documentation comment /// for a function ``` 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. ### Keywords The following keywords are reserved and may not be used as identifiers: ``` bnf actor and assert async async* await await* break case catch class composite continue debug debug_show do else flexible false for from_candid func if ignore import in module not null object or label let loop private public query return shared stable switch system throw to_candid true try type var while with ``` ### Identifiers Identifiers are alpha-numeric, start with a letter and may contain underscores: ``` bnf ::= Letter (Letter | Digit | _)* Letter ::= A..Z | a..z Digit ::= 0..9 ``` ### Integers Integers are written as decimal or hexadecimal, `Ox`-prefixed natural numbers. Subsequent digits may be prefixed a single, semantically irrelevant, underscore. ``` bnf digit ::= ['0'-'9'] hexdigit ::= ['0'-'9''a'-'f''A'-'F'] num ::= digit ('_'? digit)* hexnum ::= hexdigit ('_'? hexdigit)* nat ::= num | "0x" hexnum ``` Negative integers may be constructed by applying a prefix negation `-` operation. ### Floats Floating point literals are written in decimal or `Ox`-prefixed hexadecimal scientific notation. ``` bnf let frac = num let hexfrac = hexnum let float = num '.' frac? | num ('.' frac?)? ('e' | 'E') sign? num | "0x" hexnum '.' hexfrac? | "0x" hexnum ('.' hexfrac?)? ('p' | 'P') sign? num ``` 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. :::note the use of decimal notation, even for the base 2 exponent, is in keeping with the established hexadecimal floating point literal syntax of the `C` language. ::: ### Characters A character is a single quote (`'`) delimited: - Unicode character in UTF-8, - `\`-escaped newline, carriage return, tab, single or double quotation mark - `\`-prefixed ASCII character (TBR), - or `\u{` hexnum `}` enclosed valid, escaped Unicode character in hexadecimal (TBR). ``` bnf ascii ::= ['\x00'-'\x7f'] ascii_no_nl ::= ['\x00'-'\x09''\x0b'-'\x7f'] utf8cont ::= ['\x80'-'\xbf'] utf8enc ::= ['\xc2'-'\xdf'] utf8cont | ['\xe0'] ['\xa0'-'\xbf'] utf8cont | ['\xed'] ['\x80'-'\x9f'] utf8cont | ['\xe1'-'\xec''\xee'-'\xef'] utf8cont utf8cont | ['\xf0'] ['\x90'-'\xbf'] utf8cont utf8cont | ['\xf4'] ['\x80'-'\x8f'] utf8cont utf8cont | ['\xf1'-'\xf3'] utf8cont utf8cont utf8cont utf8 ::= ascii | utf8enc utf8_no_nl ::= ascii_no_nl | utf8enc escape ::= ['n''r''t''\\''\'''\"'] character ::= | [^'"''\\''\x00'-'\x1f''\x7f'-'\xff'] | utf8enc | '\\'escape | '\\'hexdigit hexdigit | "\\u{" hexnum '}' | '\n' // literal newline char := '\'' character '\'' ``` ### Text A text literal is `"`-delimited sequence of characters: ``` bnf text ::= '"' character* '"' ``` Note that a text literal may span multiple lines. ### Literals ``` bnf ::= literals natural float character Unicode text ``` Literals are constant values. The syntactic validity of a literal depends on the precision of the type at which it is used. ## Operators and types To simplify the presentation of available operators, operators and primitive types are classified into basic categories: | Abbreviation | Category | Supported opertions | | ------------ | ---------- | ------------------------------- | | A | Arithmetic | arithmetic operations | | L | Logical | logical/Boolean operations | | B | Bitwise | bitwise and wrapping operations | | O | Ordered | comparison | | T | Text | concatenation | Some types have several categories. For example, type `Int` is both arithmetic (A) and ordered (O) and supports both arithmetic addition (`+`) and relational less than (`<`) (amongst other operations). ### Unary operators | `` | Category | | | -------- | -------- | ---------------- | | `-` | A | numeric negation | | `+` | A | numeric identity | | `^` | B | bitwise negation | ### Relational operators | | | | | --------- | -------- | ----------------------------------------------- | | `` | Category | | | `==` | | equals | | `!=` | | not equals | | `␣<␣` | O | less than *(must be enclosed in whitespace)* | | `␣>␣` | O | greater than *(must be enclosed in whitespace)* | | `<=` | O | less than or equal | | `>=` | O | greater than or equal | 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). ### Numeric binary operators | `` | Category | | | --------- | -------- | -------------- | | `+` | A | addition | | `-` | A | subtraction | | `*` | A | multiplication | | `/` | A | division | | `%` | A | modulo | | `**` | A | exponentiation | ### Bitwise and wrapping binary operators | `` | Category | | | --------- | -------- | ---------------------------------------------- | | `&` | B | bitwise and | | `\|` | B | bitwise or | | `^` | B | exclusive or | | `<<` | B | shift left | | `␣>>` | B | shift right *(must be preceded by whitespace)* | | `<<>` | B | rotate left | | `<>>` | B | rotate right | | `+%` | A | addition (wrap-on-overflow) | | `-%` | A | subtraction (wrap-on-overflow) | | `*%` | A | multiplication (wrap-on-overflow) | | `**%` | A | exponentiation (wrap-on-overflow) | ### Text operators | `` | Category | | | --------- | -------- | ------------- | | `#` | T | concatenation | ### Assignment operators | `:=`, `=`, `=` | Category | | | --------------------------- | -------- | ------------------------------------------ | | `:=` | \* | assignment (in place update) | | `+=` | A | in place add | | `-=` | A | in place subtract | | `*=` | A | in place multiply | | `/=` | A | in place divide | | `%=` | A | in place modulo | | `**=` | A | in place exponentiation | | `&=` | B | in place logical and | | `\|=` | B | in place logical or | | `^=` | B | in place exclusive or | | `<<=` | B | in place shift left | | `>>=` | B | in place shift right | | `<<>=` | B | in place rotate left | | `<>>=` | B | in place rotate right | | `+%=` | B | in place add (wrap-on-overflow) | | `-%=` | B | in place subtract (wrap-on-overflow) | | `*%=` | B | in place multiply (wrap-on-overflow) | | `**%=` | B | in place exponentiation (wrap-on-overflow) | | `#=` | T | in place concatenation | The category of a compound assignment `=`/`=` is given by the category of the operator ``/``. ### Operator and keyword precedence 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. | Precedence | Associativity | Token | | ---------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | | LOWEST | none | `if _ _` (no `else`), `loop _` (no `while`) | | (higher) | none | `else`, `while` | | (higher) | right | `:=`, `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `#=`, `&=`, `\|=`, `^=`, `<<=`, `>>=`, `<<>=`, `<>>=`, `+%=`, `-%=`, `*%=`, `**%=` | | (higher) | left | `:` | | (higher) | left | `|>` | | (higher) | left | `or` | | (higher) | left | `and` | | (higher) | none | `==`, `!=`, `<`, `>`, `<=`, `>`, `>=` | | (higher) | left | `+`, `-`, `#`, `+%`, `-%` | | (higher) | left | `*`, `/`, `%`, `*%` | | (higher) | left | `\|` | | (higher) | left | `&` | | (higher) | left | `^` | | (higher) | none | `<<`, `>>`, `<<>`, `<>>` | | HIGHEST | left | `**`, `**%` | ### Programs The syntax of a *program* `` is as follows: ``` bnf ::= programs ;* ;* ``` A program is a sequence of imports `;*` followed by a sequence of declarations `;*` 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): - a `shared` function can only appear as a public field of an actor or actor class; - a program may contain at most one actor or actor class declaration, i.e. the final main actor or actor class; and - any main actor class declaration should be *anonymous*; if named, the class name should not be used as a value within the class and will be reported as an unavailable identifier. 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](#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. ### Imports The syntax of an *import* `` is as follows: ``` bnf ::= imports import =? ::= "" import module from relative .mo "mo:/" import module from package "canister:" import external actor by "canister:" import external actor by ``` 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 ``. Though typically a simple identifier, ``, `` can also be any composite pattern binding selective components of the resource. The pattern must be irrefutable. ### Libraries The syntax of a *library* (that can be referenced in an import) is as follows: ``` bnf ::= library ;* module ? module ;* ? actor class actor class ? (: )? ``` A library `` is a sequence of imports `;*` followed by: - a named or anonymous (module) declaration; or - a named actor class declaration. Libraries stored in `.mo` files may be referenced by `import` declarations. In a module library, the optional name `?` 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 ``, is imported as a module defining both a type and a function named ``. The name `` 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, asynchronous function, `async` expression or `async*` expression). ### Declaration syntax The syntax of a *declaration* is as follows: ``` bnf ::= declaration expression let = immutable, trap on match failure let = else immutable, handle match failure var (: )? = mutable ? =? object ? func ? ? (: )? =? function type ? = type ? ? class class ? ? (: )? ::= object body { ;* } field declarations ::= class body = ? object body, optionally binding to 'this' instance object body ``` The syntax of a shared function qualifier with call-context pattern is as follows: ``` bnf ::= composite? query ::= shared ? ? ``` For ``, an absent `?` is shorthand for the wildcard pattern `_`. ``` bnf ::= object declaration fields ? ? field ::= field visibility public private system ::= field stability (actor only) stable flexible ``` The *visibility* qualifier `?` determines the accessibility of every field `` declared by ``: - An absent `?` qualifier defaults to `private` visibility. - Visibility `private` restricts access to `` to the enclosing object, module or actor. - Visibility `public` extends `private` with external access to `` using the dot notation `.`. - Visibility `system` extends `private` with access by the run-time system. - Visibility `system` *may only* appear on `func` declarations that are actor fields, and *must not* appear anywhere else. The *stability* qualifier `` determines the *upgrade* behaviour of actor fields: - A stability qualifier *should* appear on `let` and `var` declarations that are actor fields. An absent stability qualifier defaults to `flexible`. - `` qualifiers must not appear on fields of objects or modules. - The pattern in a `stable let = ` declaration must be *simple* where, a pattern `pat` is simple if it (recursively) consists of - a variable pattern ``, or - an annotated simple pattern ` : `, or - a parenthesized simple pattern `( )`. ### Expression syntax The syntax of an *expression* is as follows: ``` bnf ::= expressions variable literal unary operator binary operator binary relational operator _ placeholder expression |> pipe operator ( ,* ) tuple . tuple projection ? option injection { ;* } object { (and )* (with ;+)? } object combination/extension # id ? variant injection . object projection/member access := assignment = unary update = binary update [ var? ,* ] array [ ] array indexing ? func function expression ? function call not negation and conjunction or disjunction if (else )? conditional switch { (case ;)+ } switch while while loop loop (while )? loop for ( in ) iteration label (: )? label break ? break continue continue return ? return async async expression await await future (only in async) async* delay an asynchronous computation await* await a delayed computation (only in async) throw raise an error (only in async) try catch catch an error (only in async) assert assertion : type annotation declaration ignore ignore value do block as expression do ? option block ! null break debug debug expression actor actor reference to_candid ( ,* ) Candid serialization from_candid Candid deserialization (system . ) System actor class constructor ( ) parentheses ::= ::= { ;* } ``` ### Patterns The syntax of a *pattern* is as follows: ``` bnf ::= patterns _ wildcard variable ? literal ( ,* ) tuple or brackets { ;* } object pattern # ? variant pattern ? option : type annotation or disjunctive pattern ::= object pattern fields (: ) = field (: ) punned field ``` ## Type syntax Type expressions are used to specify the types of arguments, constraints (a.k.a bounds) on type parameters, definitions of type constructors, and the types of sub-expressions in type annotations. ``` bnf ::= type expressions ? constructor ? { ;* } object { ;* } variant { # } empty variant [ var? ] array Null null type ? option ? ? -> function async future async* delayed, asynchronous computation ( (( :)? ),* ) tuple Any top None bottom and intersection or union Error errors/exceptions ( ) parenthesized type ::= (actor | module | object) ::= shared function type qualifier shared ? ::= paths type identifier . projection ``` An absent `?` abbreviates `object`. ### Primitive types 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. | Identifier | Category | Description | | ---------------------------------- | -------- | ---------------------------------------------------------------------- | | [`Bool`](./base/Bool.md) | L | Boolean values `true` and `false` and logical operators | | [`Char`](./base/Char.md) | O | Unicode characters | | [`Text`](./base/Text.md) | T, O | Unicode strings of characters with concatenation `_ # _` and iteration | | [`Float`](./base/Float.md) | A, O | 64-bit floating point values | | [`Int`](./base/Int.md) | A, O | signed integer values with arithmetic (unbounded) | | [`Int8`](./base/Int8.md) | A, O | signed 8-bit integer values with checked arithmetic | | [`Int16`](./base/Int16.md) | A, O | signed 16-bit integer values with checked arithmetic | | [`Int32`](./base/Int32.md) | A, O | signed 32-bit integer values with checked arithmetic | | [`Int64`](./base/Int64.md) | A, O | signed 64-bit integer values with checked arithmetic | | [`Nat`](./base/Nat.md) | A, O | non-negative integer values with arithmetic (unbounded) | | [`Nat8`](./base/Nat8.md) | A, O | non-negative 8-bit integer values with checked arithmetic | | [`Nat16`](./base/Nat16.md) | A, O | non-negative 16-bit integer values with checked arithmetic | | [`Nat32`](./base/Nat32.md) | A, O | non-negative 32-bit integer values with checked arithmetic | | [`Nat64`](./base/Nat64.md) | A, O | non-negative 64-bit integer values with checked arithmetic | | [`Blob`](./base/Blob.md) | O | binary blobs with iterators | | [`Principal`](./base/Principal.md) | O | principals | | [`Error`](./base/Error.md) | | (opaque) error values | 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](./base-intro.md)). For example, the [`Text`](./base/Text.md) library provides common functions on `Text` values. ### Type `Bool` The type `Bool` of category L (Logical) has values `true` and `false` and is supported by one and two branch `if _ (else )?`, `not `, `_ and _` and `_ or _` expressions. Expressions `if`, `and` and `or` are short-circuiting. ### Type `Char` 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. ### Type `Text` 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 …​ }`. ### Type `Float` 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](https://ieeexplore.ieee.org/document/8766229) (See [References](#references)). Common functions and values are defined in base library "base/Float". ### Types `Int` and `Nat` 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. ### Bounded integers `Int8`, `Int16`, `Int32` and `Int64` 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. ### Bounded naturals `Nat8`, `Nat16`, `Nat32` and `Nat64` 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. ### Type `Blob` 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 …​ }`. ### Type `Principal` 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). ### Error type Assuming base library import, ``` motoko no-repl import E "mo:base/Error"; ``` Errors are opaque values constructed and examined with operations: - `E.reject : Text -> Error` - `E.code : Error -> E.ErrorCode` - `E.message : Error -> Text` Type `E.ErrorCode` is equivalent to variant type: ``` motoko no-repl type ErrorCode = { // Fatal error. #system_fatal; // Transient error. #system_transient; // Destination invalid. #destination_invalid; // Explicit reject by canister code. #canister_reject; // Canister trapped. #canister_error; // Future error code (with unrecognized numeric code). #future : Nat32; // Error issuing inter-canister call // (indicating destination queue full or freezing threshold crossed). #call_error : { err_code : Nat32 } }; ``` 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](#throw) and [Try](#try). Errors with codes other than `#canister_reject` (i.e. *system* errors) may be caught and thrown, but not user-constructed. :::note Exiting an async block or shared function with a non-`#canister-reject` system error exits with a copy of the error with revised code `#canister_reject` and the original `Text` message. This prevents programmatic forgery of system errors. ::: :::note On the Internet Computer, the act of issuing a call to a canister function can fail, so that the call cannot (and will not be) performed. This can happen due to a lack of canister resources, typically because the local message queue for the destination canister is full, or because performing the call would reduce the current cycle balance of the calling canister to a level below its freezing threshold. Such call failures are reported by throwing an `Error` with code `#call_error { err_code = n }`, where `n` is the non-zero `err_code` value returned by the Internet Computer. Like other errors, call errors can be caught and handled using `try ... catch ...` expressions, if desired. ::: ### Constructed types ` ?` 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](#well-formed-types)). Though typically a type identifier, more generally, `` 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`). ### Object types `? { ;* }` 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 `?` is `actor`, all fields have `shared` function type (specifying messages). ### Variant types `{ ;* }` specifies a variant type by listing its variant type fields as a sequence of ``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. ### Array types `[ var? ]` specifies the type of arrays with elements of type ``. Arrays are immutable unless specified with qualifier `var`. ### Null type The `Null` type has a single value, the literal `null`. `Null` is a subtype of the option `? T`, for any type `T`. ### Option types `? ` specifies the type of values that are either `null` or a proper value of the form `? ` where `` has type ``. ### Function types Type `? ? -> ` specifies the type of functions that consume (optional) type parameters ``, consume a value parameter of type `` and produce a result of type ``. Both `` and `` may reference type parameters declared in ``. If `` or `` (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 `` qualifier specifies whether the function value is shared, which further constrains the form of ``, `` and `` (see [Sharability](#sharability) below). (Note that a `` function may itself be `shared` or `shared query` or `shared composite query`, determining the persistence of its state changes.) ### Async types `async ` specifies a future producing a value of type ``. Future types typically appear as the result type of a `shared` function that produces an `await`-able value. ### Async* types `async* ` specifies a delayed, asynchronous computation producing a value of type ``. Computation types typically appear as the result type of a `local` function that produces an `await*`-able value. (They cannot be used as the return types of `shared` functions.) ### Tuple types `( (( :)? ),* )` specifies the type of a tuple with zero or more ordered components. The optional identifier ``, 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*. ### Any type Type `Any` is the *top* type, i.e. the super-type of all types. All values have type `Any`. ### None type 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. ### Intersection type The type expression ` and ` 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. ### Union type The type expression ` or ` 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. ### Parenthesized type 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, `( )` declares that the function takes or returns a single (boxed) value of type ``. In all other positions, `( )` has the same meaning as ``. ### Type fields ``` bnf ::= object type fields : immutable value var : mutable value ? : function value (short-hand) type ? = type component ``` A type field specifies the name and type of a value field of an object, or the name and definition of a type component of an object. The value field names within a single object type must be distinct and have non-colliding hashes. The type component names within a single object type must also be distinct and have non-colliding hashes. Value fields and type components reside in separate name spaces and thus may have names in common. ` : ` specifies an *immutable* field, named `` of type ``. `var : ` specifies a *mutable* field, named `` of type ``. `type ? = ` specifies a *type* component, with field name ``, abbreviating (parameterized) type ``. Unlike type declarations, a type component is not, in itself, recursive (though it may abbreviate an existing recursive type). In particular, the name `` is not bound in `` nor in any other fields of the enclosing object type. The name `` only determines the label to use when accessing the definition through a record of this type (using the dot notation). ### Variant type fields ``` bnf ::= variant type fields # : tag # unit tag (short-hand) ``` 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. `# : ` specifies an (immutable) field, named `` of type ``. `# ` is sugar for an (immutable) field, named `` of type `()`. ### Sugar When enclosed by an `actor` object type, ` ? : ` is syntactic sugar for an immutable field named `` of `shared` function type `shared ? → `. When enclosed by a non-`actor` object type, ` ? : ` is syntactic sugar for an immutable field named `` of ordinary function type `? → `. ### Type parameters ``` bnf ::= type parameters < typ-param,* > <: constrained type parameter unconstrained type parameter ``` A type constructors, function value or function type may be parameterised by a vector of comma-separated, optionally constrained, type parameters. ` <: ` declares a type parameter with constraint ``. Any instantiation of `` must subtype `` (at that same instantiation). Syntactic sugar `` 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 arguments ``` bnf ::= type arguments < ,* > ``` 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. ### Well-formed types A type `T` is well-formed only if (recursively) its constituent types are well-formed, and: - if `T` is `async U` or `async* U` then `U` is shared, and - if `T` is `shared ? U -> V`: - `U` is shared and, - `V == ()` and `?` is absent, or - `V == async W` with `W` shared, and - if `T` is `C` where: - a declaration `type C = …​` is in scope, and - `Ti <: Ui[ T0/X0, …​, Tn/Xn ]`, for each `0 <= i <= n`. - if `T` is `actor { …​ }` then all fields in `…​` are immutable and have `shared` function type. ### Subtyping Two types `T`, `U` are related by subtyping, written `T <: U`, whenever, one of the following conditions is true: - `T` equals `U` (reflexivity). - `U` equals `Any`. - `T` equals `None`. - `T` is a type parameter `X` declared with constraint `U`. - `T` is `Nat` and `U` is `Int`. - `T` is a tuple `(T0, …​, Tn)`, `U` is a tuple `(U0, …​, Un)`, and for each `0 <= i <= n`, `Ti <: Ui`. - `T` is an immutable array type `[ V ]`, `U` is an immutable array type `[ W ]` and `V <: W`. - `T` is a mutable array type `[ var V ]`, `U` is a mutable array type `[ var W ]` and `V == W`. - `T` is `Null` and `U` is an option type `? W` for some `W`. - `T` is `? V`, `U` is `? W` and `V <: W`. - `T` is a future `async V`, `U` is a future `async W`, and `V <: W`. - `T` is an object type ` { fts0 }`, `U` is an object type ` { fts1 }` and - `` == ``, and, for all fields, - if field `id : W` is in `fts1` then `id : V` is in `fts0` and `V <: W`, and - if mutable field `var id : W` is in `fts1` then `var id : V` is in `fts0` and `V == W`. (That is, object type `T` is a subtype of object type `U` if they have same sort, every mutable field in `U` super-types the same field in `T` and every mutable field in `U` is mutable in `T` with an equivalent type. In particular, `T` may specify more fields than `U`. Note that this clause defines subtyping for all sorts of object type, whether `module`, `object` or `actor`.) - `T` is a variant type `{ fts0 }`, `U` is a variant type `{ fts1 }` and - if field `# id : V` is in `fts0` then `# id : W` is in `fts1` and `V <: W`. (That is, variant type `T` is a subtype of variant type `U` if every field of `T` subtypes the same field of `U`. In particular, `T` may specify fewer variants than `U`.) - `T` is a function type `? T1 -> T2`, `U` is a function type `? U1 -> U2` and - `T` and `U` are either both equivalently `?`, and - assuming constraints `X0 <: W0, …​, Xn <: Wn` then - for all `i`, `Wi == Vi`, and - `U1 <: T1`, and - `T2 <: U2`. (That is, function type `T` is a subtype of function type `U` if they have same `?` qualification, they have the same type parameters (modulo renaming) and assuming the bounds in `U`, every bound in `T` supertypes the corresponding parameter bound in `U` (contra-variance), the domain of `T` supertypes the domain of `U` (contra-variance) and the range of `T` subtypes the range of `U` (co-variance).) - `T` (respectively `U`) is a constructed type `C` that is equal, by definition of type constructor `C`, to `W`, and `W <: U` (respectively `U <: W`). - For some type `V`, `T <: V` and `V <: U` (*transitivity*). ### Sharability A type `T` is *shared* if it is - `Any` or `None`, or - a primitive type other than `Error`, or - an option type `? V` where `V` is shared, or - a tuple type `(T0, …​, Tn)` where all `Ti` are shared, or - an immutable array type `[V]` where `V` is shared, or - an `object` type where all fields are immutable and have shared type, or - a variant type where all tags have shared type, or - a shared function type, or - an `actor` type. ### Stability Stability extends sharability to include mutable types. More precisely: A type `T` is *stable* if it is - `Any` or `None`, or - a primitive type other than `Error`, or - an option type `? V` where `V` is stable, or - a tuple type `(T0, …​, Tn)` where all `Ti` are stable, or - a (mutable or immutable) array type `[var? V]` where `V` is stable, or - an `object` type where all fields have stable type, or - a variant type where all tags have stable type, or - a shared function type, or - an `actor` type. 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. ## Static and dynamic semantics Below, we give a detailed account of the semantics of Motoko programs. For each [expression form](#expression-syntax) and each [declaration form](#declaration-syntax), we summarize its semantics, both in static terms (based on typing) and dynamic terms (based on program evaluation). ### Programs A program `;* ;*` has type `T` provided: - `;*` has type `T` under the static environment induced by the imports in `;*`. All type and value declarations within `;*` are mutually-recursive. A program evaluates by (transitively) evaluating the imports, binding their values to the identifiers in `;*` and then evaluating the sequence of declarations in `;*`. ### Libraries 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. #### Module libraries A library `;* module ? ` is a sequence of imports `;*` followed by a single module declaration. A library has module type `T` provided - `module ? ` has (module) type `T` under the static environment induced by the imports in `;*`. A module library evaluates by (transitively) evaluating its imports, binding their values to the identifiers in `;*` and then evaluating `module ? `. #### Actor class libraries The actor class library `;* ` where `` is of the form `? actor class ? (: )? ` has type: ``` bnf module { type = T; : (U1,...,Un) -> async T } ``` provided that: - the actor class declaration `` has function type `(U1, ...​, Un) -> async T` under the static environment induced by the imports in `;*`. Notice that the imported type of the function `` must be asynchronous. An actor class library evaluates by (transitively) evaluating its imports, binding their values to the identifiers in `;*`, and evaluating the (derived) module: ``` bnf module { } ``` On the Internet Computer, if this library is imported as identifier `Lib`, then calling `await Lib.(, ..., )`, installs a fresh instance of the actor class as an isolated IC canister, passing the values of ``, ...​, `` as installation arguments, and returns a reference to a (remote) actor of *type* `Lib.`, that is, `T`. Installation is (necessarily) asynchronous. #### Actor class management On the Internet Computer, the primary constructor of an imported actor class always creates a new principal and installs a fresh instance of the class as the code for that principal. While that is one way to install a canister on the IC, it is not the only way. To provide further control over the installation of actor classes, Motoko endows each imported actor class with an extra, secondary constructor, for use on the Internet Computer. This constructor takes an additional first argument that tailors the installation. The constructor is only available via special syntax that stresses its `system` functionality. Given some actor class constructor: ``` motoko no-repl Lib. : (U1, ...​, Un) -> async T ``` Its secondary constructor is accessed as `(system Lib.)` with typing: ``` motoko no-repl (system Lib.) : { #new : CanisterSettings; #install : Principal; #reinstall : actor {} ; #upgrade : actor {} } -> (U1, ...​, Un) -> async T ``` where ``` motoko no-repl type CanisterSettings = { settings : ?{ controllers : ?[Principal]; compute_allocation : ?Nat; memory_allocation : ?Nat; freezing_threshold : ?Nat; } } ``` Calling `(system Lib.)()(, ...​, )` uses the first argument ``, a variant value, to control the installation of the canister further. Arguments `(, ..., )` are just the user-declared constructor arguments of types `U1, ..., Un` that would also be passed to the primary constructor. If `` is * `#new s`, where `s` has type `CanisterSettings`: the call creates a fresh Internet Computer principal `p`, with settings `s`, and installs the instance to principal `p`. * `#install p`, where `p` has type `Principal`, the call installs the actor to an already created Internet Computer principal `p`. The principal must be empty (have no previously installed code) or the call will return an error. * `#upgrade a`, where `a` has type (or supertype) `actor {}`, the call installs the instance as an _upgrade_ of actor `a`, using its current stable storage to initialize stable variables and stable memory of the new instance. * `#reinstall a`, where `a` has type (or supertype) `actor {}`, reinstalls the instance over the existing actor `a`, discarding its stable variables and stable memory. :::note On the Internet Computer, calling the primary constructor `Lib.` is equivalent to calling the secondary constructor `(system Lib.)` with argument `(#new {settings = null})` (i.e. using default settings). ::: :::note On the Internet Computer, calls to `Lib.` and `(system Lib.)(#new ...)` must be provisioned with enough cycles for the creation of a new principal. Other call variants will use the cycles of the already allocated principal or actor. ::: :::danger The use of `#upgrade a` may be unsafe. Motoko will currently not verify that the upgrade is compatible with the code currently installed at `a`. (A future extension may verify compatibilty with a dynamic check.) The use of `#reinstall a` may be unsafe. Motoko cannot verify that the reinstall is compatible with the code currently installed in actor `a` (even with a dynamic check). A change in interface may break any existing clients of `a`. The current state of `a` will be lost. ::: ### Imports and Urls An import `import =? ` declares a pattern `` bound to the contents of the text literal ``. `` 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 `` is of the form: - `""` then `` is bound to the library module defined in file `.mo`. `` is interpreted relative to the absolute location of the enclosing file. Note the `.mo` extension is implicit and should *not* be included in ``. For example, `import U "lib/Util"` defines `U` to reference the module in local file `./lib/Util`. - `"mo:/"` then `` is bound to the library module defined in file `/.mo` in directory `` referenced by package alias ``. The mapping from `` to `` is determined by a compiler command-line argument `--package `. For example, `import L "mo:base/List"` defines `L` to reference the `List` library in package alias `base`. - `"ic:"` then `` is bound to a Motoko actor whose Motoko type is determined by the canister’s IDL interface. The IDL interface of canister `` must be found in file `/.did`. The compiler assumes that `` is specified by command line argument `--actor-idl ` and that file `/.did` exists. For example, `import C "ic:lg264-qjkae"` defines `C` to reference the actor with canister id `lg264-qjkae` and IDL file `lg264-qjkae.did`. - `"canister:"` is a symbolic reference to canister alias ``. The compiler assumes that the mapping of `` to `` is specified by command line argument `--actor-alias ic:`. If so, `"canister:"` is equivalent to `"ic:"` (see above). For example, `import C "canister:counter"` defines `C` to reference the actor otherwise known as `counter`. 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 [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install), 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 `` are identifiers, such as `Array`, or object patterns like `{ cons; nil = empty }`, which allow selective importing of individual fields, under original or other names.) ### Declaration fields A declaration field `? ? ` defines zero or more fields of an actor or object, according to the set of variables defined by ``. 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: - `` has type `T`; - if `?` is `stable` then `T` must be a stable type (see [Stability](#stability)). (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: - if the stable declaration was previously declared stable in the retired actor, its initial value is inherited from the retired actor. - if the stable declaration was not declared stable in the retired actor, and is thus new, its value is obtained by evaluating ``. For an upgrade to be safe: - every stable identifier declared with type `T` in the retired actor and declared stable and of type `U` in the replacement actor, must satisfy `T <: U`. 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`. #### System fields The declaration `` of a `system` field must be a manifest `func` declaration with one of the following names and types: | name | type | description | | ------------- | ------------------------------------------------------------- | ------------------- | | `heartbeat` | `() -> async ()` | heartbeat action | | `timer` | `(Nat64 -> ()) -> async ()` | timer action | | `inspect` | `{ caller : Principal; msg : ; arg : Blob } -> Bool` | message predicate | | `preupgrade` | `() -> ()` | pre upgrade action | | `postupgrade` | `() -> ()` | post upgrade action | - `heartbeat`, when declared, is called on every Internet Computer subnet **heartbeat**, scheduling an asynchronous call to the `heartbeat` function. Due to its `async` return type, a heartbeat function may send messages and await results. The result of a heartbeat call, including any trap or thrown error, is ignored. The implicit context switch means that the time the heartbeat body is executed may be later than the time the heartbeat was issued by the subnet. - `timer`, when declared, is called as a response of the canister global timer's expiration. The canister's global timer can be manipulated with the passed-in function argument of type `Nat64 -> ()` (taking an absolute time in nanoseconds) upon which libraries can build their own abstractions. When not declared (and in absence of the `-no-timer` flag), this system action is provided with default implementation by the compiler (additionally `setTimer` and `cancelTimer` are available as primitives). - `inspect`, when declared, is called as a predicate on every Internet Computer ingress message (with the exception of HTTP query calls). The return value, a `Bool`, indicates whether to accept or decline the given message. The argument type depends on the interface of the enclosing actor (see [Inspect](#inspect)). - `preupgrade`, when declared, is called during an upgrade, immediately *before* the (current) values of the (retired) actor’s stable variables are transferred to the replacement actor. - `postupgrade`, when declared, is called during an upgrade, immediately *after* the (replacement) actor body has initialized its fields (inheriting values of the retired actors' stable variables), and before its first message is processed. These `preupgrade` and `postupgrade` system methods provide the opportunity to save and restore in-flight data structures (e.g. caches) that are better represented using non-stable types. During an upgrade, a trap occurring in the implicit call to `preupgrade()` or `postupgrade()` causes the entire upgrade to trap, preserving the pre-upgrade actor. ##### `inspect` Given a record of message attributes, this function produces a `Bool` that indicates whether to accept or decline the message by returning `true` or `false`. The function is invoked (by the system) on each ingress message issue as an Internet Computer *update call* (i.e. excluding non-replicated query calls). Similar to a query, any side-effects of an invocation are transient and discarded. A call that traps due to some fault has the same result as returning `false` (message denial). The argument type of `inspect` depends on the interface of the enclosing actor. In particular, the formal argument of `inspect` is a record of fields of the following types: - `caller : Principal`: the principal, possibly anonymous, of the caller of the message; - `arg : Blob`: the raw, binary content of the message argument; - `msg : `: a variant of *decoding* functions, where ` == {…​; #: () → T; …​}` contains one variant per `shared` or `shared query` function, ``, of the actor. The variant’s tag identifies the function to be called; The variant’s argument is a function that, when applied, returns the (decoded) argument of the call as a value of type `T`. Using a variant, tagged with `#`, allows the return type, `T`, of the decoding function to vary with the argument type (also `T`) of the shared function ``. The variant’s argument is a function so that one can avoid the expense of message decoding (when appropriate). :::danger An actor that fails to declare system field `inspect` will simply accept all ingress messages. ::: :::note Any `shared composite query` function in the interface is *not* included in `` since, unlike a `shared query`, it can only be invoked as a non-replicated query call, never as an update call. ::: ### Sequence of declarations A sequence of declarations `;*` occurring in a block, a program or embedded in the `;*` sequence of an object body has type `T` provided: - `;*` is empty and `T == ()`; or - `;*` is non-empty and: - all value identifiers bound by `;*` are distinct, and - all type identifiers bound by `;*` are distinct, and - under the assumption that each value identifier `` in `;*` has type `var_id? Tid`, and assuming the type definitions in `;*`: - each declaration in `;*` is well-typed, and - each value identifier `` in bindings produced by `;*` has type `var_id? Tid`, and - all but the last `` in `;*` of the form `` has type `()`; - the last declaration in `;*` has type `T`. Declarations in `;*` 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 `;*`. In addition, the set of value bindings defined by `;*` is the union of the bindings introduced by each declaration in `;*`. It is a compile-time error if any declaration in `;*` might require the value of an identifier declared in `;*` 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 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. - In a function application or `let`-binding, failure to match the formal argument pattern or `let`-pattern causes a *trap*. - In a `case` branch of a `switch` expression, failure to match that case’s pattern continues with an attempt to match the next case of the switch, trapping only when no such case remains. ### Wildcard pattern The wildcard pattern `_` matches a single value without binding its contents to an identifier. ### Identifier pattern The identifier pattern `` matches a single value and binds it to the identifier ``. ### Literal pattern The literal pattern `? ` matches a single value against the constant value of literal `` and fails if they are not (structurally) equal values. For integer literals only, the optional `` determines the sign of the value to match. ### Tuple pattern The tuple pattern `( ,* )` 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. ### Object pattern The object pattern `{ ;* }` 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 `` is shorthand for ` = `; Similarly, a typed, punned field ` : ` is short-hand for ` = : `. Both bind the matched value of the field named `` to the identifier ``. 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 `` of the matched object type must be determined by an enclosing type annotation or other contextual type information. ### Variant pattern The variant pattern `# ?` matches a variant value (of the form `# v`) against a variant pattern. An absent `?` is shorthand for the unit pattern (`()`). Pattern matching fails if the tag `` of the value is distinct from the tag `` of the pattern (i.e. `` \<\> ``); or the tags are equal but the value `v` does not match the pattern `?`. Pattern matching succeeds if the tag of the value is `` (i.e. `` = ``) and the value `v` matches the pattern `?`. The binding returned by a successful match is just the binding returned by the match of `v` against `?`. ### Annotated pattern The annotated pattern ` : ` matches value of `v` type `` against the pattern ``. ` : ` is *not* a dynamic type test, but is used to constrain the types of identifiers bound in ``, e.g. in the argument pattern to a function. ### Option pattern The option `? ` matches a value of option type `? `. The match *fails* if the value is `null`. If the value is `? v`, for some value `v`, then the result of matching `? ` is the result of matching `v` against ``. 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`. ### Or pattern The or pattern ` or ` is a disjunctive pattern. The result of matching ` or ` against a value is the result of matching ``, if it succeeds, or the result of matching ``, if the first match fails. (Note, an `or`-pattern may contain identifier (``) patterns with the restriction that both alternatives must bind the same set of identifiers. Each identifier's type is the least upper bound of its type in `` and ``. ### Expression declaration The declaration `` has type `T` provided the expression `` has type `T` . It declares no bindings. The declaration `` evaluates to the result of evaluating `` (typically for ``'s side-effect). Note that if `` appears within a sequence of declarations, but not as the last declaration of that sequence, then `T` must be `()`. ### Let declaration The `let` declaration `let = ` has type `T` and declares the bindings in `` provided: - `` has type `T`, and - `` has type `T`. The declaration `let = ` evaluates `` 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 ``. If matching fails, then the result is `trap`. Otherwise, the result is `v` and the binding of all identifiers in `` to their matching values in `v`. All bindings declared by a `let` (if any) are *immutable*. ### Let-else declaration The `let-else` declaration `let = else ` has type `T` and declares the bindings in `` provided: - `` has type `T`, - `` has type `T`, and - `` has type `None`. The declaration `let = else ` evaluates `` 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 ``. If matching succeeds, the result is `v` and the binding of all identifiers in `` to their matching values in `v`. If matching fails, then evaluation continues with ``, which, having type `None`, cannot proceed to the end of the declaration but may still alter control-flow to, for example `return` or `throw` to exit an enclosing function, break` from an enclosing expression or simply diverge. All bindings declared by a `let-else` (if any) are *immutable*. #### Handling pattern match failures In the presence of refutable patterns, the pattern in a `let` declaration may fail to match the value of its expression. In such cases, the `let`-declaration will evaluate to a trap. The compiler emits a warning for any `let`-declaration than can trap due to pattern match failure. Instead of trapping, a user may want to explicitly handle pattern match failures. The `let-else` declaration, `let = else `, has mostly identical static and dynamic semantics to `let`, but diverts the program's control flow to `` when pattern matching fails, allowing recovery from failure. The `else` expression, ``, must have type `None` and typically exits the declaration using imperative control flow constructs such as `throw`, `return`, `break` or non-returning functions such as `Debug.trap(...)` (that all produce a result of type `None`). Any compilation warning that is produced for a `let` can be silenced by handling the potential pattern-match failure using `let-else`. ### Var declaration The variable declaration `var (: )? = ` declares a *mutable* variable `` with initial value ``. The variable’s value can be updated by assignment. The declaration `var ` has type `()` provided: - `` has type `T`; and - If the annotation `(:)?` is present, then `T` == ``. Within the scope of the declaration, `` has type `var T` (see [Assignment](#assignment)). Evaluation of `var (: )? = ` proceeds by evaluating `` 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 ``. The result of the declaration is `()` and `` is bound to a fresh location that contains `v`. ### Type declaration The declaration `type ? = ` declares a new type constructor ``, with optional type parameters `` and definition ``. The declaration `type C< X0 <: T0, …​, Xn <: Tn > = U` is well-formed provided: - type parameters `X0`, …​, `Xn` are distinct, and - assuming the constraints `X0 <: T0`, …​, `Xn <: Tn`: - constraints `T0`, …​, `Tn` are well-formed. - definition `U` is well-formed. - it is productive (see [Productivity](#productivity)). - it is non-expansive (see [Expansiveness](#expansiveness)). 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. #### Productivity A type is *productive* if recursively expanding any outermost type constructor in its definition eventually produces a type other than the application of a type constructor. Motoko requires all type declarations to be productive. For example, the type definitions: ``` motoko no-repl type Person = { first : Text; last : Text }; type List = ?(T, List); type Fst = T; type Ok = Fst>; ``` are all productive and legal. But the type definitions, ``` motoko no-repl type C = C; type D = D; type E = F; type F = E; type G = Fst, Any>; ``` are all non-productive, since each definition will enter a loop after one or more expansions of its body. #### Expansiveness A set of mutually recursive type or class declarations will be rejected if the set is *expansive*. Expansiveness is a syntactic criterion. To determine whether a set of singly or mutually recursive type definitions, say ``` motoko no-repl type C<...,Xi,...> = T; ... type D<...,Yj,...> = U; ``` is expansive, construct a directed graph whose vertices are the formal type parameters (identified by position), `C#i`, with the following `{0,1}`-labeled edges: - For each occurrence of parameter `C#i` as immediate, `j`-th argument to type `D<…​,C#i,…​>`, add a *non-expansive*, `0`-labeled edge,`C#i -0-> D#j`. - For each occurrence of parameter `C#i` as a proper sub-expression of the `j`-th argument to type `D<…​,T[C#i],..>` add an *expansive* `1`-labeled edge, `C#i -1-> D#j`. The graph is expansive if, and only if, it contains a cycle with at least one expansive edge. For example, the type definition: ``` motoko no-repl type List = ?(T, List); ``` that recursively instantiates `List` at the same parameter `T`, is non-expansive and accepted, but the similar looking definition: ``` motoko no-repl type Seq = ?(T, Seq<[T]>); ``` that recursively instantiates `Seq` with a larger type, `[T]`, containing `T`, is *expansive* and rejected. - Type `List` is non-expansive because its graph, `{ List#0 -0-> List#0 }`, though cyclic, has no expansive edge. - Type `Seq`, on the other hand, is expansive, because its graph, `{ Seq#0 -1-> Seq#0 }`, has a cycle that includes an expansive edge. ### Object declaration Declaration ` ? `, where `` is of the form `=? { ;* }`, declares an object with optional identifier `` and zero or more fields `;*`. Fields can be declared with `public` or `private` visibility; if the visibility is omitted, it defaults to `private`. The qualifier `` (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 = { [var0] id0 : T0, …​ , [varn] idn : T0 }` denote the type of the object. Let `;*` be the sequence of declarations embedded in `;*`. The object declaration has type `T` provided that: 1. type `T` is well-formed for sort `sort`, and 2. under the assumption that ` : T`, - the sequence of declarations `;*` has type `Any` and declares the disjoint sets of private and public identifiers, `Id_private` and `Id_public` respectively, with types `T(id)` for `id` in `Id == Id_private union Id_public`, and - `{ id0, …​, idn } == Id_public`, and - for all `i in 0 <= i <= n`, `[vari] Ti == T(idi)`. 3. If `` is `module`, then the declarations in `;*` must be *static* (see [Static declarations](#static-declarations)). Note that requirement 1. imposes further constraints on the field types of `T`. In particular, if the sort is `actor` then: - all public fields must be non-`var` (immutable) `shared` functions (the public interface of an actor can only provide asynchronous messaging via shared functions); Because actor construction is asynchronous, an actor declaration can only occur in an asynchronous context (i.e. in the body of a (non-``) `shared` function, `async` expression or `async*` expression). Evaluation of `? ? =? { ;* }` proceeds by binding `` (if present), to the eventual value `v`, and evaluating the declarations in `;*`. If the evaluation of `;*` traps, so does the object declaration. Otherwise, `;*` produces a set of bindings for identifiers in `Id`. let `v0`, …​, `vn` be the values or locations bound to identifiers ``, …​, ``. The result of the object declaration is the object `v == sort { = v1, …​, = vn}`. If `?` is present, the declaration binds `` to `v`. Otherwise, it produces the empty set of bindings. :::danger Actor declaration is (implicitly) asynchronous and the state of the enclosing actor may change due to concurrent processing of other incoming actor messages. It is the programmer’s responsibility to guard against non-synchronized state changes. ::: #### Static declarations A declaration is *static* if it is: - a `type` declaration, or - a `class` declaration, or - a `let` declaration with a static pattern and a static expression, or - a module, function or object declaration that desugars to a static `let` declaration, or - a static expression. An expression is *static* if it is: - a literal expression, or - a tuple of static expressions, or - an object of static expressions, or - a variant or option with a static expression, or - an immutable array, or - field access and projection from a static expression, or - a module expression, or - a function expression, or - a static declaration, or - an `ignore` of a static expression, or - a block, all of whose declarations are static, or - a type annotation with a static expression. A pattern is *static* if it is: - an identifier, or - a wildcard, or - a tuple of static patterns, or - type annotation with a static pattern. Static phrases are designed to be side-effect free, allowing the coalescing of duplicate library imports (a.k.a deduplication). ### Function declaration The function declaration `? func ? ? (: )? =? ` is syntactic sugar for a named `let` or anonymous declaration of a function expression. That is, when `?` is present and the function is named: ``` bnf ? func ? (: )? =? := let = ? func ? (: )? =? ``` But when `?` is absent and the function is anonymous: ``` bnf ? func ? (: )? =? := ? func ? (: )? =? ``` Named function definitions support recursion (a named function can call itself). :::note In compiled code, `shared` functions can only appear as public actor fields. ::: ### Class declaration The *class* declaration `? ? class ? ? (: )? ` is sugar for pair of a type and function declaration: ``` bnf ? ? class ? (: )? := type = { ;* }; ? func ? : async? = async? ? ``` where: - `?`, when present, requires `` == `actor`, and provides access to the `caller` of an `actor` constructor, and - `?` is the sequence of type identifiers bound by `?` (if any), and - `;*` is the set of public field types inferred from `;*`. - `` is the object body of ``. - `?` is the optional *this* (a.k.a *self*), parameter of ``. - `async?` is present, if only if, `` == `actor`. Note `?` must not be of the form `shared ?`: a constructor, unlike a function, cannot be a `query` or `composite query`. An absent `?` defaults to `shared` when `sort` = `actor`. If `sort` is `actor`, then: - `?` must be absent or empty (`actor` classes cannot have type parameters); - ``'s type must be shared (see [Sharability](#sharability)). - `(: )?`, if present, must be of the form `: async T` for some actor type `T` (actor instantiation is asynchronous). If `(: )` is present, then the type ` { ;* }` must be a subtype of the annotation ``. In particular, the annotation is used only to check, but not affect, the inferred type of function ``. The class declaration has the same type as function `` and evaluates to the function value ``. ### Identifiers The identifier expression `` has type `T` provided `` is in scope, defined and declared with explicit or inferred type `T`. The expression `` evaluates to the value bound to `` in the current evaluation environment. ### Literals A literal has type `T` only when its value is within the prescribed range of values of type `T`. The literal (or constant) expression `` evaluates to itself. ### Unary operators The unary operator ` ` has type `T` provided: - `` has type `T`, and - The category of `` is a category of `T`. The unary operator expression ` ` evaluates `` to a result. If the result is a value `v`, it returns the result of ` v`. If the result is `trap`, the entire expression results in `trap`. ### Binary operators The binary operator expression ` ` has type `T` provided: - `` has type `T`, and - `` has type `T`, and - The category of `` is a category of `T`. The binary operator expression ` ` 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 v2`. ### Relational operators The relational expression ` ` has type `Bool` provided: - `` has type `T`, and - `` has type `T`, and - `` is equality `==` or inequality `!=`, `T` is *shared*, and `T` is the least type such that `` and `` have type `T`; - the category O (Ordered) is a category of `T` and ``; or The binary operator expression ` ` evaluates `` 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 v2`. For equality and inequality, the meaning of `v1 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). ### Pipe operators and placeholder expressions The pipe expression ` |> ` binds the value of `` to the special placeholder expression `_`, that can be referenced in `` (and recursively in ``). Referencing the placeholder expression outside of a pipe operation is a compile-time error. The pipe expression ` |> ` is just syntactic sugar for a `let` binding to a placeholder identifier, `p`: ``` bnf do { let p = ; } ``` The placeholder expression `_` is just syntactic sugar for the expression referencing the placeholder identifier: ``` bnf p ``` The placeholder identifier, `p`, is a fixed, reserved identifier that cannot be bound by any other expression or pattern other than a pipe operation, and can only be referenced using the placeholder expression `_`. `|>` has lowest precedence amongst all operators except `:` and associates to the left. Judicious use of the pipe operator allows one to express a more complicated nested expression by piping arguments of that expression into their nested positions within that expression. For example: ``` motoko no-repl Iter.range(0, 10) |> Iter.toList _ |> List.filter(_, func n { n % 3 == 0 }) |> { multiples = _ }; ``` may, according to taste, be a more readable rendition of: ``` motoko no-repl { multiples = List.filter( Iter.toList(Iter.range(0, 10)), func n { n % 3 == 0 }) }; ``` Above, each occurence of `_` refers to the value of the left-hand-size of the nearest enclosing pipe operation, after associating nested pipes to the left. Note that the evaluation order of the two examples is different, but consistently left-to-right. :::note Although syntactically identical, the placeholder expression is semantically distinct from, and should not be confused with, the wildcard pattern `_`. Occurrences of the forms can be distinguished by their syntactic role as pattern or expression. ::: ### Tuples Tuple expression `(, …​, )` has tuple type `(T1, …​, Tn)`, provided ``, …​, `` have types `T1`, …​, `Tn`. The tuple expression `(, …​, )` evaluates the expressions `exp1` …​ `expn` in order, trapping as soon as some expression `` traps. If no evaluation traps and `exp1`, …​, `` evaluate to values `v1`,…​,`vn` then the tuple expression returns the tuple value `(v1, …​ , vn)`. The tuple projection ` . ` has type `Ti` provided `` has tuple type `(T1, …​, Ti, …​, Tn)`, `` == `i` and `1 <= i <= n`. The projection ` . ` evaluates `` 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*. ### Option expressions The option expression `? ` has type `? T` provided `` 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`. ### Variant injection The variant injection `# ` has variant type `{# id T}` provided: - `` has type `T`. The variant injection `# ` is just syntactic sugar for `# ()`. The variant injection `# ` evaluates `` 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 `# v`. The tag and contents of a variant value can be tested and accessed using a [variant pattern](#variant-pattern). ### Objects Objects can be written in literal form `{ ;* }`, consisting of a list of expression fields: ``` bnf ::= object expression fields var? (: ) = field var? (: ) punned field ``` Such an object literal, sometimes called a *record*, is equivalent to the object declaration `object { ;* }` 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 `` 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 `` is shorthand for ` = `; Similarly, a typed, punned field ` : ` is short-hand for ` = : `. Both associate the field named `` with the value of the identifier ``. ### Object combination/extension Objects can be combined and/or extended using the `and` and `with` keywords. A record expression `{ (and )* (with ;+)? }` merges the objects (or modules) specified as *base* expressions, and augments the result to also contain the specified fields. The `with ;+` clause can be omitted when at least two bases appear and none have common field labels. Thus the field list serves to: - disambiguate field labels occurring more than once in the bases, - define new fields, - override existing fields and their types, and - add new `var` fields - redefine existing `var` fields from some base to prevent aliasing. The resulting type is determined by the bases' (and explicitly given fields') static type. Any `var` field from some base must be overwritten in the explicit field list. This prevents introducing aliases of `var` fields. The record expression `{ and ... with ; ... ; }` has type `T` provided: - The record `{ ; ... ; }` has record type `{ field_tys } == { var? : U1; ... var? : Um }`. - Let `newfields == { , ..., }` be the set of new field names. - Considering value fields: - Base expression `` has object or module type `sorti { field_tysi } == sorti { var? : Ti1, …​, var? : Tik }` where `sorti <> Actor`. Let `fields(i) == { , ..., }` be the set of static field names of base `i`. Then - `fields(i)` is disjoint from `newfields` (possibly by applying subtyping to the type of ``); - no field in `field_tysi` is a `var` field; - `fields(i)` is disjoint from `fields(j)` for `j < i`. - Considering type fields: - Base expression `` has object or module type `sorti { typ_fieldsi } == sorti { type = … , …, type = … }` where `sorti <> Actor`. - `typ_fieldsi` _agrees_ with `typ_fieldsj` for `j < i`. - `T` is `{ typ_fieldsi fields_tys1 ... typ_fieldsm fields_tysm field_tys }`. Here, two sequences of type fields _agree_ only when any two type fields of the same name in each sequence have equivalent definitions. The record expression `{ and ... with ; ... ; }` evaluates records `` through `` and `{ exp-field1; ... ) = fi()` if `` is in `fields(i)`, for some `i`, or `f()` if `` is in `newfields`. ### Object projection (member access) The object projection ` . ` has type `var? T` provided `` has object type `sort { var1? : T1, …​, var? : T, …​, var? : Tn }` for some sort `sort`. The object projection ` . ` evaluates `` to a result `r`. If `r` is `trap`, then the result is `trap`. Otherwise, `r` must be an object value `{ = v1,…​, id = v, …​, = vm }` and the result of the projection is the value `w` obtained from value or location `v` in field `id`. If `var` is absent from `var? T` then the value `w` is just the value `v` of immutable field ``, otherwise: - if the projection occurs as the target of an assignment expression then `w` is just `v`, the mutable location in field ``. - otherwise, `w` (of type `T`) is the value currently stored at the mutable location `v` in field ``. ### Special member access The iterator access ` . ` has type `T` provided `` has type `U`, and `U`,`` and `T` are related by a row of the following table: | | | | | | ---------- | ------- | ----------------------- | -------------------------------------------- | | U | `` | T | Description | | `Text` | `size` | `Nat` | size (or length) in characters | | `Text` | `chars` | `{ next: () -> Char? }` | character iterator, first to last | | | | | | | `Blob` | `size` | `Nat` | size in bytes | | `Blob` | `vals` | `{ next: () -> Nat8? }` | byte iterator, first to last | | | | | | | `[var? T]` | `size` | `Nat` | number of elements | | `[var? T]` | `get` | `Nat -> T` | indexed read function | | `[var? T]` | `keys` | `{ next: () -> Nat? }` | index iterator, by ascending index | | `[var? T]` | `vals` | `{ next: () -> T? }` | value iterator, by ascending index | | `[var T]` | `put` | `(Nat, T) -> ()` | indexed write function (mutable arrays only) | The projection ` . ` evaluates `` 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. :::note the `chars`, `vals`, `keys` and `vals` members produce stateful **iterator objects** than can be consumed by `for` expressions (see [For](#for)). ::: ### Assignment The assignment ` := ` has type `()` provided: - `` has type `var T`, and - `` has type `T`. The assignment expression ` := ` evaluates `` 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 `()`. ### Unary compound assignment The unary compound assignment `= ` has type `()` provided: - `` has type `var T`, and - ``'s category is a category of `T`. The unary compound assignment `= ` evaluates `` 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 ` v`. ### Binary compound assignment The binary compound assignment ` = ` has type `()` provided: - `` has type `var T`, and - `` has type `T`, and - ``'s category is a category of `T`. For binary operator ``, the compound assignment expression ` = ` evaluates `` 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 v2` and returns the empty tuple `()`. ### Arrays The expression `[ var? ,* ]` has type `[var? T]` provided each expression `` in the sequence `,*` has type T. The array expression `[ var , …​, ]` evaluates the expressions `exp0` …​ `expn` in order, trapping as soon as some expression `` traps. If no evaluation traps and `exp0`, …​, `` evaluate to values `v0`,…​,`vn` then the array expression returns the array value `[var? v0, …​ , vn]` (of size `n+1`). ### Array indexing The array indexing expression ` [ ]` has type `var? T` provided: - `` has (mutable or immutable) array type `[var? T1]`. The expression ` [ ]` 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, - if the indexing occurs as the target of an assignment expression then `v` is the `i`-th mutable location in the array; - otherwise, `v` is `vi`, the value currently stored in the `i`-th location of the array. ### Function calls The function call expression ` ? ` has type `T` provided: - the function `` has function type `? < X0 <: V0, ..., Xn <: Vn > U1-> U2`; and - if `?` is absent but n > 0 then there exists minimal `T0, …​, Tn` (inferred by the compiler) such that: - each type argument satisfies the corresponding type parameter’s bounds: for each `1 <= i <= n`, `Ti <: [T0/X0, …​, Tn/Xn]Vi`; and - the argument `` has type `[T0/X0, …​, Tn/Xn]U1`, and - `T == [T0/X0, …​, Tn/Xn]U2`. The call expression ` ? ` 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, `? func { }` (for some implicit environment), and `r2` is a value `v2`. If `` is present and of the form `shared ? ` then evaluation continues by matching the record value `{caller = p}` against ``, where `p` is the `Principal` invoking the function (typically a user or canister). Matching continues by matching `v1` against ``. If pattern matching succeeds with some bindings, then evaluation returns the result of `` 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`. :::note The exhaustiveness side condition on `shared` function expressions ensures that argument pattern matching cannot fail (see [Functions](#functions)). ::: :::note Calls to local functions with `async` return type and `shared` functions can fail due to a lack of canister resources. Such failures will result in the call immediately throwing an error with `code` `#call_error { err_code = n }`, where `n` is the non-zero `err_code` value returned by the Internet Computer. Earlier versions of Motoko would trap in such situations, making it difficult for the calling canister to mitigate such failures. Now, a caller can handle these errors using enclosing `try ... catch ...` expressions, if desired. ::: ### Functions The function expression `? func < X0 <: T0, …​, Xn <: Tn > (: U2)? =? ` has type `? < X0 <: T0, ..., Xn <: Tn > U1-> U2` if, under the assumption that `X0 <: T0, …​, Xn <: Tn`: - `?` is of the form `shared ? ` if and only if `?` is `shared ?` (the `` modifiers must agree, i.e. are either both absent, both `query`, or both `composite query`); - all the types in `T0, …​, Tn` and `U2` are well-formed and well-constrained; - pattern `` has *context type* `{ caller : Principal }`; - pattern `` has type `U1`; - if the function is `shared` then `` and `` must be exhaustive; - expression `` has type return type `U2` under the assumption that `` has type `U1`. `? func ? (: )? =? ` evaluates to a function value (a.k.a. closure), denoted `? func ? = `, 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 `` function may itself be `shared ` or `shared query ` or `shared composite query `. - A `shared ` function may be invoked from a remote caller. Unless causing a trap, the effects on the callee persist beyond completion of the call. - A `shared query ` function may be also be invoked from a remote caller, but the effects on the callee are transient and discarded once the call has completed with a result (whether a value or error). - A `shared composite query ` function may only be invoked as an ingress message, not from a remote caller. Like a query, the effects on the callee are transient and discarded once the call has completed with a result (whether a value or error). In addition, intermediate state changes made by the call are not observable by any of its own `query` or `composite query` callees. In either case, `` provides access to a context value identifying the *caller* of the shared (query) function. :::note The context type is a record to allow extension with further fields in future releases. ::: Shared functions have different capabilities dependent on their qualification as `shared`, `shared query` or `shared composite query`. A `shared` function may call any `shared` or `shared query` function, but no `shared composite query` function. A `shared query` function may not call any `shared`, `shared query` or `shared composite query` function. A `shared composite query` function may call any `shared query` or `shared composite query` function, but no `shared` function. All varieties of shared functions may call unshared functions. Composite queries, though composable, can only be called externally (from a frontend) and cannot be initiated from an actor. ### Blocks The block expression `{ ;* }` has type `T` provided the last declaration in the sequence `;*` 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](#annotated-pattern)) to satisfy the type checker. The block expression `{ ;* }` evaluates each declaration in `;*` in sequence (program order). The first declaration in `;*` that results in a trap causes the block to result in `trap`, without evaluating subsequent declarations. ### Do The do expression `do ` allows the use of a block as an expression, in positions where the syntax would not directly allow a block. The expression `do ` has type `T` provided `` has type `T`. The `do` expression evaluates by evaluating `` and returning its result. ### Option block The option block `do ? ` introduces scoped handling of null values. The expression `do ? ` has type `?T` provided `` has type `T`. The `do ? ` expression evaluates `` and returns its result as an optional value. Within `` the null break expression ` !` exits the nearest enclosing `do ?` block with value `null` whenever `` has value `null`, or continues evaluation with the contents of ``'s option value. (See [Null break](#null-break).) Option blocks nest with the target of a null break determined by the nearest enclosing option block. ### Null break The null break expression ` !` 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 appears in the body, ``, of an enclosing option block of the form `do ? ` (see [Option block](#do-opt)). - `` has option type `? T`. The expression ` !` evaluates `` 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 ? `; otherwise, `r` is `? v` and execution continues with value `v`. ### Not The not expression `not ` has type `Bool` provided `` has type `Bool`. If `` evaluates to `trap`, the expression returns `trap`. Otherwise, `` evaluates to a Boolean value `v` and the expression returns `not v`, (the Boolean negation of `v`). ### And The and expression ` and ` has type `Bool` provided `` and `` have type `Bool`. The expression ` and ` 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 ``). Otherwise, the expression returns the result of evaluating ``. ### Or The or expression ` or ` has type `Bool` provided `` and `` have type `Bool`. The expression ` and ` 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 ``). Otherwise, the expression returns the result of evaluating ``. ### If The expression `if (else )?` has type `T` provided: - `` has type `Bool` - `` has type `T` - `` is absent and `() <: T`, or - `` is present and has type `T`. The expression evaluates `` 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 ``. Otherwise, `r1` is `false` and the result is `()` (if `` is absent) or the result of `` (if `` is present). ### Switch The switch expression `switch { (case ;)+ }` has type `T` provided: - `exp` has type `U`; and - for each case `case ` in the sequence `(case ;)+` : - pattern `` has type `U`; and, - expression `` has type `T` The expression evaluates `` to a result `r`. If `r` is `trap`, the result is `trap`. Otherwise, `r` is some value `v`. Let `case ;` be the first case in `(case ;)+` such that `` matches `v` for some binding of identifiers to values. Then result of the `switch` is the result of evaluating `` under that binding. If no case has a pattern that matches `v`, the result of the switch is `trap`. ### While The expression `while ` has type `()` provided: - `` has type `Bool`, and - `` has type `()`. The expression evaluates `` 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 `. Otherwise, the result is `()`. ### Loop The expression `loop ` has type `None` provided `` has type `()`. The expression evaluates `` to a result `r1`. If `r1` is `trap`, the result is `trap`. Otherwise, the result is the result of (re-)evaluating `loop `. ### Loop-while The expression `loop while ` has type `()` provided: - `` has type `()`, and - `` has type `Bool`. The expression evaluates `` to a result `r1`. If `r1` is `trap`, the result is `trap`. Otherwise, evaluation continues with ``, 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 while `. Otherwise, `r2` is false and the result is `()`. ### For The iterator expression `for ( in ) ` has type `()` provided: - `` has type `{ next : () → ?T }`, - pattern `` has type `T`, and - expression `` has type `()` (in the environment extended with the bindings of ``). The `for`-expression is syntactic sugar for ``` bnf for ( in ) := { let x = ; label l loop { switch (x.next()) { case (? ) ; case (null) break l; } } } ``` where `x` and `l` are fresh identifiers. In particular, the `for` loop will trap if evaluation of `` traps; as soon as `x.next()` traps, or the value of `x.next()` does not match pattern ``, or when `` traps. :::note Although general purpose, `for` loops are commonly used to consume iterators produced by [Special member access](#special-member-access) to, for example, loop over the indices (`a.keys()`) or values (`a.vals()`) of some array (here `a`). ::: ### Label The label-expression `label (: )? ` has type `T` provided: - `(: )?` is absent and `T` is unit; or `(: )?` is present and `T == `; - `` has type `T` in the static environment extended with `label l : T`. The result of evaluating `label (: )? ` is the result of evaluating ``. ### Labeled loops If `` in `label (: )? ` is a looping construct: - `while (exp2) `, - `loop (while ())?`, or - `for ( in ) ` the body, ``, of the loop is implicitly enclosed in `label (…​)` allowing early continuation of the loop by the evaluation of expression `continue `. `` is fresh identifier that can only be referenced by `continue ` (through its implicit expansion to `break `). ### Break The expression `break ` is equivalent to `break ()`. The expression `break ` has type `None` provided: - The label `` is declared with type `label : T`. - `` has type `T`. The evaluation of `break ` 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 …​` using the value `v` as the result of that labelled expression. ### Continue The expression `continue ` is equivalent to `break `, where `` is implicitly declared around the bodies of ``-labelled looping constructs (see [Labeled loops](#labeled-loops)). ### Return The expression `return` is equivalent to `return ()`. The expression `return ` has type `None` provided: - `` has type `T` and - `T` is the return type of the nearest enclosing function (with no intervening `async` expression), or - `async T` is the type of the nearest enclosing (perhaps implicit) `async` expression (with no intervening function declaration) The `return` expression exits the corresponding dynamic function invocation or completes the corresponding dynamic `async` or `async*` expression with the result of ``. ### Async The async expression `async ` has type `async T` provided: - `` has type `T`; - `T` is shared. Any control-flow label in scope for `async ` is not in scope for ``. However, `` may declare and use its own, local, labels. The implicit return type in `` is `T`. That is, the return expression, ``, (implicit or explicit) to any enclosed `return ?` expression, must have type `T`. Evaluation of `async ` queues a message to evaluate `` 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 ``. :::note Because it involves messaging, evaluating an `async` expression can fail due to a lack of canister resources. Such failures will result in the call immediately throwing an error with `code` `#call_error { err_code = n }`, where `n` is the non-zero `err_code` value returned by the Internet Computer. Earlier version of Motoko would trap in such situations, making it difficult for the producer of the async expression to mitigate such failures. Now, the producer can handle these errors using an enclosing `try ... catch ...` expression, if desired. ::: ### Await The `await` expression `await ` has type `T` provided: - `` has type `async T`, - `T` is shared, - the `await` is explicitly enclosed by an `async`-expression or appears in the body of a `shared` function. Expression `await ` evaluates `` 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 ` 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 ` suspends evaluation and schedules resumption of execution with value `v`. If the future is complete with (thrown) error value `e`, then `await ` 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. :::danger Between suspension and resumption of a computation, the state of the enclosing actor may change due to concurrent processing of other incoming actor messages. It is the programmer’s responsibility to guard against non-synchronized state changes. Using `await` signals that the computation *will* commit its current state and suspend execution. ::: :::note Because it involves additional messaging, an `await` on a completed future can, in rare circumstances, fail due to a lack of canister resources. Such failures will result in the call immediately throwing an error with `code` `#call_error { err_code = n }`, where `n` is the non-zero `err_code` value returned by the Internet Computer The error is produced eagerly, without suspending nor committing state. Earlier versions of Motoko would trap in such situations, making it difficult for the consumer of the `await` to mitigate such failures. Now, the consumer can handle these errors by using an enclosing `try ... catch ...` expression, if desired. ::: ### Async* The async expression `async* ` has type `async* T` provided: - `` has type `T`; - `T` is shared. Any control-flow label in scope for `async* ` is not in scope for ``. However, `` may declare and use its own, local, labels. The implicit return type in `` is `T`. That is, the return expression, ``, (implicit or explicit) to any enclosed `return ?` expression, must have type `T`. Evaluation of `async* ` produces a delayed computation to evaluate ``. It immediately returns a value of type `async* T`. The delayed computation can be executed using `await*`, producing one evaluation of the computation ``. :::danger Note that `async ` has the effect of scheduling a single asynchronous computation of ``, regardless of whether its result, a future, is consumed with an `await`. Moreover, each additional consumption by an `await` just returns the previous result, without repeating the computation. In comparison, `async* `, has *no effect* until its value is consumed by an `await*`. Moreover, each additional consumption by an `await*` will trigger a new evaluation of ``, including repeated effects. Be careful of this distinction, and other differences, when refactoring code. ::: :::note The `async*` and corresponding `await*` constructs are useful for efficiently abstracting asynchronous code into re-useable functions. In comparison, calling a local function that returns a proper `async` type requires committing state and suspending execution with each `await` of its result, which can be undesirable. ::: ### Await* The `await*` expression `await* ` has type `T` provided: - `` has type `async* T`, - `T` is shared, - the `await*` is explicitly enclosed by an `async`-expression or appears in the body of a `shared` function. Expression `await* ` evaluates `` to a result `r`. If `r` is `trap`, evaluation returns `trap`. Otherwise `r` is a delayed computation ``. The evaluation of `await* ` proceeds with the evaluation of ``, executing the delayed computation. :::danger During the evaluation of ``, the state of the enclosing actor may change due to concurrent processing of other incoming actor messages. It is the programmer’s responsibility to guard against non-synchronized state changes. ::: :::note Unlike `await`, which, 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, `await*` does not, in itself, commit any state changes, nor does it suspend computation. Instead, evaluation proceeds immediately according to `` (the value of ``), committing state and suspending execution whenever `` does (but not otherwise). ::: :::note Evaluation of a delayed `async*` block is synchronous while possible, switching to asynchronous when necessary due to a proper `await`. Using `await*` signals that the computation *may* commit state and suspend execution during the evaluation of ``, that is, that evaluation of `` may perform zero or more proper `await`s and may be interleaved with the execution of other, concurrent messages. ::: ### Throw The `throw` expression `throw ` has type `None` provided: - `` has type `Error`, - the `throw` is explicitly enclosed by an `async`-expression or appears in the body of a `shared` function. Expression `throw ` evaluates `` 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 catch ` whose pattern `` 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`, `async*` expression or `shared` function invocation. ### Try The `try` expression `try catch ` has type `T` provided: - `` has type `T`, - `` has type `Error` and `` has type `T` in the context extended with ``, and - the `try` is explicitly enclosed by an `async`-expression or appears in the body of a `shared` function. Expression `try catch ` evaluates `` to a result `r`. If evaluation of `` throws an uncaught error value `e`, the result of the `try` is the result of evaluating `` under the bindings determined by the match of `e` against `pat`. :::note Because the `Error` type is opaque, the pattern match cannot fail (typing ensures that `` is an irrefutable wildcard or identifier pattern). ::: See [Error type](#error-type). ### Assert The assert expression `assert ` has type `()` provided `` has type `Bool`. Expression `assert ` evaluates `` to a result `r`. If `r` is `trap` evaluation returns `trap`. Otherwise `r` is a Boolean value `v`. The result of `assert ` is: - the value `()`, when `v` is `true`; or - `trap`, when `v` is `false`. ### Type annotation The type annotation expression ` : ` has type `T` provided: - `` is `T`, and - `` has type `U` where `U <: T`. Type annotation may be used to aid the type-checker when it cannot otherwise determine the type of `` or when one wants to constrain the inferred type, `U` of `` to a less-informative super-type `T` provided `U <: T`. The result of evaluating ` : ` is the result of evaluating ``. :::note Type annotations have no-runtime cost and cannot be used to perform the (checked or unchecked) `down-casts` available in other object-oriented languages. ::: ### Candid Serialization The *Candid serialization* expression `to_candid ( ,*)` has type `Blob` provided: - `(,*)` has type `(T1,…​,Tn)`, and each `Ti` is *shared*. Expression `to_candid ( ,* )` evaluates the expression sequence `( ,* )` 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 ( ,* )` is some Candid blob `b = encode((T1,...,Tn))(vs)`, encoding `vs`. The Candid *deserialization* expression `from_candid ` has type `?(T1,…​,Tn)` provided: - `?(T1,…​,Tn)` is the expected type from the context; - `` has type `Blob`; and - `?(T1,…​,Tn)` is *shared*. Expression `from_candid ` evaluates `` 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.) :::note Operation `from_candid` returns `null` when the argument is a valid Candid encoding of the wrong type. It traps if the blob is not a valid Candid encoding at all. ::: :::note Operations `to_candid` and `from_candid` are syntactic operators, not first-class functions, and must be fully applied in the syntax. ::: :::danger The Candid encoding of a value as a blob is not unique and the same value may have many different Candid representations as a blob. For this reason, blobs should never be used to, for instance, compute hashes of values or determine equality, whether across compiler versions or even just different programs. ::: ### Declaration The declaration expression `` has type `T` provided the declaration `` has type `T`. Evaluating the expression `` proceeds by evaluating ``, returning the result of `` but discarding the bindings introduced by `` (if any). (The expression `` is actually shorthand for the block expression `{ }`.) ### Ignore The expression `ignore ` has type `()` provided the expression `` has type `Any` . The expression `ignore ` evaluates `` (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 `` declaration would be ill-typed). Then the semantics is equivalent to `let _ = : Any`. ### Debug The debug expression `debug ` has type `()` provided the expression `` has type `()`. When the program is compiled or interpreted with (default) flag `--debug`, evaluating the expression `debug ` proceeds by evaluating ``, returning the result of ``. When the program is compiled or interpreted with flag `--release`, evaluating the expression `debug ` immediately returns the unit value `()`. The code for `` is never executed, nor is its code included in the compiled binary. ### Actor references The actor reference `actor ` has expected type `T` provided: - the expression is used in a context expecting an expression of type `T` (typically as the subject of a type annotation, typed declaration or function argument); and - `T` is an some actor type `actor { …​ }`; and - `` has type `Text`. The argument `` 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. :::note The argument to `actor` should *not* include the `ic:` resource locator used to specify an `import`. For example, use `actor "lg264-qjkae"`, not `actor "ic:lg264-qjkae"`. ::: :::danger Although they do not compromise type safety, actor references can easily introduce latent, dynamic errors. Accordingly, actor references should be used sparingly and only when needed. ::: ### Parentheses The parenthesized expression `( )` has type `T` provided `` has type `T`. The result of evaluating `( )` is the result of evaluating ``. ### Subsumption Whenever `` has type `T` and `T <: U` (`T` subtypes `U`) then by virtue of *implicit subsumption*, `` 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. ## References - *IEEE Standard for Floating-Point Arithmetic*, in IEEE Std 754-2019 (Revision of IEEE 754-2008), vol., no., pp.1-84, 22 July 2019, doi: 10.1109/IEEESTD.2019.8766229.