# Language reference > For the complete documentation index, see [llms.txt](/llms.txt) This reference page 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. This page 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. In this documentation, the term canister is used to refer to an Internet Computer smart contract. ## Basic language syntax This section describes the basic language conventions of 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? await* break case catch class composite continue debug debug_show do else false flexible finally for from_candid func if ignore import implicit in include label let loop mixin module not null object or persistent private public query return shared stable switch system throw to_candid true transient try type var weak 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, adheres to 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 operations | | ------------ | ---------- | ------------------------------- | | A | Arithmetic | Arithmetic operations | | B | Bitwise | Bitwise and wrapping operations | | O | Ordered | Comparison | | T | Text | Concatenation | Some types have several categories. For example, type [`Int`](https://mops.one/core/docs/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. Compiled programs must obey the following additional restrictions: - 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. - 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. These restrictions are not imposed on interpreted programs. The last two restrictions are designed to forbid programmatic actor class recursion, pending compiler support. Note that the parameters of an actor class must have [shared type](#shareability). 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 "ic:" Import external actor by "canister:" Import external actor by "blob:file:" Import literal `Blob` value from ``` An import introduces a resource referring to a local source module, module from a package of modules, a canister imported as an actor, or a literal [`Blob`](#type-blob) value. 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

? (: )? ;* mixin

Mixin ``` A library `` is a sequence of imports `;*` followed by: - A named or anonymous module declaration, or - A named actor class declaration. - An anonymous mixin 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 ? ? (: )? mixin

Mixin include Mixin inlusion ::= Object body { ;* } Field declarations ::= Class body = ? Object body, optionally binding to 'this' instance Object body ::= persistent? actor module object ::= Parenthetical expression ( ? with ;* ) Parenthetical combination/extension ``` 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 transient (equivalent to 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** behavior of actor fields: - A stability qualifier should appear on `let` and `var` declarations that are actor fields. Within a `persistent` actor or actor class, an absent stability qualifier defaults to `stable`. Within a non-`persistent` actor or actor class, an absent stability qualifier defaults to `flexible` (or `transient`). The keywords `transient` and `flexible` are interchangeable. - `` 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 any of the following: - A variable pattern ``. - An annotated simple pattern ` : `. - 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) await? Await future (only in async) without state commit when completed 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) try finally Guard with cleanup try catch

finally Catch an error (only in async) and cleanup 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 Type field ``` ## Type syntax Type expressions are used to specify the types of arguments, constraints 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 Type item Simple item : Named item implicit : Implicit argument ::= (actor | module | object) ::= Shared function type qualifier shared ? ::= Paths Type identifier . Projection ``` An absent `?` abbreviates `object`. Type items of the form ` (implicit : )` and ` : (implicit : ( : ))` are used to indicate implicit and re-named implicit parameters. The second form is used to override the parameter named `` as implicit parameter named ``. These special type items are only meaningful in parameter positions of function types and have no significance elsewhere. ### 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`](https://mops.one/core/docs/Bool) | L | Boolean values `true` and `false` and logical operators | | [`Char`](https://mops.one/core/docs/Char) | O | Unicode characters | | [`Text`](https://mops.one/core/docs/Text) | T, O | Unicode strings of characters with concatenation `_ # _` and iteration | | [`Float`](https://mops.one/core/docs/Float) | A, O | 64-bit floating point values | | [`Int`](https://mops.one/core/docs/Int) | A, O | Signed integer values with arithmetic (unbounded) | | [`Int8`](https://mops.one/core/docs/Int8) | A, O | Signed 8-bit integer values with checked arithmetic | | [`Int16`](https://mops.one/core/docs/Int16) | A, O | Signed 16-bit integer values with checked arithmetic | | [`Int32`](https://mops.one/core/docs/Int32) | A, O | Signed 32-bit integer values with checked arithmetic | | [`Int64`](https://mops.one/core/docs/Int64) | A, O | Signed 64-bit integer values with checked arithmetic | | [`Nat`](https://mops.one/core/docs/Nat) | A, O | Non-negative integer values with arithmetic (unbounded) | | [`Nat8`](https://mops.one/core/docs/Nat8) | A, O | Non-negative 8-bit integer values with checked arithmetic | | [`Nat16`](https://mops.one/core/docs/Nat16) | A, O | Non-negative 16-bit integer values with checked arithmetic | | [`Nat32`](https://mops.one/core/docs/Nat32) | A, O | Non-negative 32-bit integer values with checked arithmetic | | [`Nat64`](https://mops.one/core/docs/Nat64) | A, O | Non-negative 64-bit integer values with checked arithmetic | | [`Blob`](https://mops.one/core/docs/Blob) | O | Binary blobs with iterators | | [`Principal`](https://mops.one/core/docs/Principal) | O | Principals | | [`Error`](https://mops.one/core/docs/Error) | | (Opaque) error values | | [`Region`](https://mops.one/core/docs/Region) | | (Opaque) stable memory region objects | Although many of these types have linguistic support for literals and operators, each primitive type also has an eponymous library in the core package providing related [functions and values](https://mops.one/core/docs/index). For example, the [`Text`](https://mops.one/core/docs/Text) library provides common functions on `Text` values. ### Type [`Bool`](https://mops.one/core/docs/Bool) The type [`Bool`](https://mops.one/core/docs/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. Core package function `Char.toNat32(c)` converts a `Char` value, `c` to its [`Nat32`](https://mops.one/core/docs/Nat32) code point. Function `Char.fromNat32(n)` converts a [`Nat32`](https://mops.one/core/docs/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`](https://mops.one/core/docs/Text) value. ### Type [`Text`](https://mops.one/core/docs/Text) The type [`Text`](https://mops.one/core/docs/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`](https://mops.one/core/docs/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 the [`Float`](https://mops.one/core/docs/Float) core package. ### Types [`Int`](https://mops.one/core/docs/Int) and [`Nat`](https://mops.one/core/docs/Nat) The types [`Int`](https://mops.one/core/docs/Int) and [`Nat`](https://mops.one/core/docs/Nat) are signed integral and natural numbers of categories A (Arithmetic) and O (Ordered). Both [`Int`](https://mops.one/core/docs/Int) and [`Nat`](https://mops.one/core/docs/Nat) are arbitrary precision, with only subtraction `-` on [`Nat`](https://mops.one/core/docs/Nat) trapping on underflow. The subtype relation `Nat <: Int` holds, so every expression of type [`Nat`](https://mops.one/core/docs/Nat) is also an expression of type [`Int`](https://mops.one/core/docs/Int) but not vice versa. In particular, every value of type [`Nat`](https://mops.one/core/docs/Nat) is also a value of type [`Int`](https://mops.one/core/docs/Int), without change of representation. ### Bounded integers [`Int8`](https://mops.one/core/docs/Int8), [`Int16`](https://mops.one/core/docs/Int16), [`Int32`](https://mops.one/core/docs/Int32) and [`Int64`](https://mops.one/core/docs/Int64) The types [`Int8`](https://mops.one/core/docs/Int8), [`Int16`](https://mops.one/core/docs/Int16), [`Int32`](https://mops.one/core/docs/Int32) and [`Int64`](https://mops.one/core/docs/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 core package provides conversion functions: - Conversion to [`Int`](https://mops.one/core/docs/Int). - Checked and wrapping conversions from [`Int`](https://mops.one/core/docs/Int). - Wrapping conversion to the bounded natural type of the same size. ### Bounded naturals [`Nat8`](https://mops.one/core/docs/Nat8), [`Nat16`](https://mops.one/core/docs/Nat16), [`Nat32`](https://mops.one/core/docs/Nat32) and [`Nat64`](https://mops.one/core/docs/Nat64) The types [`Nat8`](https://mops.one/core/docs/Nat8), [`Nat16`](https://mops.one/core/docs/Nat16), [`Nat32`](https://mops.one/core/docs/Nat32) and [`Nat64`](https://mops.one/core/docs/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 core package provides conversion functions: - Conversion to [`Nat`](https://mops.one/core/docs/Nat). - Checked and wrapping conversions from [`Nat`](https://mops.one/core/docs/Nat). - Wrapping conversion to the bounded, signed integer type of the same size. ### Type [`Blob`](https://mops.one/core/docs/Blob) The type [`Blob`](https://mops.one/core/docs/Blob) of category O (Ordered) represents binary blobs or sequences of bytes. Function `b.size()` returns the number of characters in [`Blob`](https://mops.one/core/docs/Blob) value `b`. Operations on blob values include sequential iteration over bytes via function `b.values()` as in `for (v : Nat8 in b.values()) { … v … }`. ### Type [`Principal`](https://mops.one/core/docs/Principal) The type [`Principal`](https://mops.one/core/docs/Principal) of category O (Ordered) represents opaque principals such as canisters and users that can be used to identify callers of shared functions and used for simple authentication. Although opaque, principals may be converted to binary [`Blob`](https://mops.one/core/docs/Blob) values for more efficient hashing and other applications. ### Error type Assuming core package import: ```motoko no-repl import E "mo:core/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; // Response unknown due to missed deadline. #system_unknown; // 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`](https://mops.one/core/docs/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`](https://mops.one/core/docs/Text) message. This prevents programmatic forgery of system errors. ::: :::note On ICP, 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`](https://mops.one/core/docs/Error) with code `#call_error { err_code = n }`, where `n` is the non-zero `err_code` value returned by ICP. Like other errors, call errors can be caught and handled using `try ... catch ...` expressions, if desired. ::: ### Type `Region` The type `Region` represents opaque stable memory regions. Region objects are dynamically allocated and independently growable. They represent isolated partitions of IC stable memory. The region type is stable but not shared and its objects, which are stateful, may be stored in stable variables and data structures. Objects of type `Region` are created and updated using the functions provided by base libary `Region`. See [stable regions](./icp-features/stable-memory) and library [Region](https://mops.one/core/docs/Region) for more information. ### Constructed types `

?` is the application of a type identifier or path, either built-in (i.e. [`Int`](https://mops.one/core/docs/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 for 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 ``. ### Weak reference types `weak ` specifies the type of weak references to values of 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 arity is the number of arguments or results a function returns. The optional `` qualifier specifies whether the function value is shared, which further constrains the form of ``, `` and `` (see [sharability](#shareability) 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 supertype of all types. All values have type `Any`. ### None type Type `None` is the bottom type, the 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 and 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 `