Motoko Base Library

Certain containers that satisfy a monadic structure (such as List, Array, Option, and Result) provide the following primitives for easier composition:

• make: The monadic unit (also known as return).
• flatten: The monadic join (also known as concat).
• chain: The monadic bind.

When working with or extending the library, follow these naming conventions to maintain consistency with the Motoko Style Guide:

• Types and Classes: Use UpperCamelCase for type names, class names, and type parameters.
• Values and Fields: Use lowerCamelCase for value parameters, field names, and variant cases.
• Mutability: Use a Var prefix to distinguish mutable versions from immutable versions of a similar type or class (e.g., Map vs MapVar).
• Abstraction: Name classes after their conceptual function (e.g., OrderedMap) rather than their implementation, unless distinguishing between multiple implementations (e.g., OrderedMap vs HashMap).
• Transparency: Non-encapsulated types (transparent types) can be named after their structure (e.g., Tree).

Functions and methods follow these semantic naming patterns:

• General: Use lowerCamelCase.
• Accessors: Name them as nouns describing the value they return. Avoid redundant get prefixes (e.g., use size instead of getSize), unless the function is a generic getter for a container.
• Mutators: Use imperative verbs to describe the operation or side effect (e.g., put, delete).
• Predicates: For functions returning Bool, use is or has prefixes (e.g., isEmpty).
• Consistency: Analogous functions should share the same name across different modules and classes to ensure a predictable API.

The repository uses two primary branches to support different versions of the moc compiler:

• master branch: Intended for the newest released version of moc. Public CI runs on this branch.
• next-moc branch: Intended for the in-development version of moc. This branch is used by the motoko repository's CI.

Branches are kept in sync via circular merges: next-moc is updated automatically from master via GitHub workflows, while master is updated manually during moc releases.

You can run tests using npm test. The test runner will automatically download the moc and wasmtime versions specified in the mops.toml file under the [toolchain] section.

Test Modes and Filters

• Standard tests: npm test
• WASI mode: npm test -- --mode wasi
• Specific files: Use a filter to run specific test files (e.g., npm test list runs List.test.mo and AssocList.test.mo).
• Watch mode: npm test -- --watch
• Watch mode with filter: npm test <filter> -- --watch (e.g., npm test array -- --watch).

Using Makefile

If you use the Makefile instead of npm, the runner detects the moc compiler from your system path or dfx installation. This requires Wasmtime and Vessel to be installed on your system.

To generate the reference manual documentation, run the provided shell script. The output will be located in the _out/ directory. You can view the HTML version of the documentation by opening _out/html/index.html in any web browser.

./make_docs.sh

Depending on your toolchain, use one of the following methods to include the base library in your project:

DFINITY SDK

If you are installing Motoko through the DFINITY SDK releases, the base library is already included automatically.

Mops Package Manager

Run the following command to add the package:

mops add base

Vessel Package Manager

Add an entry to your package-set.dhall. The package name for imports is base (e.g., import "mo:base/Nat").

Note that the version can be a git branch or tag (e.g., version = "moc-0.8.4").

{
  name = "base",
  repo = "https://github.com/caffeinelabs/motoko-base",
  version = "master",
  dependencies = [] : List Text
}

To use modules from the Motoko base library, use the import keyword followed by a local module name and the mo: prefix with the base/ path.

Note that the base library is evolving; the number of modules and their APIs may change, potentially introducing breaking changes that require program updates.

import Debug "mo:base/Debug";

Debug.print("hello world");

In addition to the base library, you can import local Motoko files using relative paths. For example, if types.mo is in the same directory as your current file, use ./types.

import Types "./types";