Writing incomplete code

Overview

In the midst of writing a program, you may want to run an incomplete version or a version where one or more execution paths are either missing or simply invalid.

To accommodate these situations, Motoko provides the xxx, nyi and unreachable functions from the base Prelude library, explained below. Each is a simple wrapper around a more general trap mechanism.

Short-term holes

Assuming that one has imported the prelude as follows:

import P "mo:base/Prelude";

You can fill any missing expression with the following:

P.xxx()

The expression xxx() has type None, which is a subtype of every other type. This means the expression can plug any short-term gap in your code. xxx() will trap when executed.

Long-term holes

By convention, longer-term holes can be considered "not yet implemented" (nyi) features, and marked as such with a similar function from the Prelude module:

P.nyi()

Like xxx(), nyi() has type None, thus any other type, and will trap on execution.

Unreachable code

Sometimes you will be required to provide code that they know will never be executed, due to the preceding program logic.

To document unreachable code, you can use the unreachable function from the prelude:

P.unreachable()

Like unreachable() has type None and thus any other type, and will trap on (unexpected!) execution.