Morloc Manual

The morloc-manager utility streamlines the management of Morloc environments. The binaries can be downloaded directly from GitHub (here) or you can follow the script below can be followed to install the latest binary:

On macOS you may need to clear the quarantine attribute:

morloc-manager relies on containers, so you will also need a container engine. Two are supported: Podman and Docker. I recommend Podman for rootless local work. If you have both engines installed, you will need to tell morloc-manager which you are using with the command:

The morloc-manager utility usage information can be accessed with the -h option:

To get started with Morloc, we will only need subcommands from the Development section of the usage statement above.

An environment is a named, self-contained Morloc installation: a container image, a data directory for modules and binaries, and optionally a custom Dockerfile layer with extra dependencies.

We can create a new environment and name it base with the command below:

By default, the new subcommand pulls the latest Morloc release. There are many additional options, but this default environment will be sufficient for running nearly everything in the Morloc docs.

We can check that the new environment is available with ls. You might see something like this (your environments will differ from mine):

Next we should activate the new environment we just created:

everthing is set up correctly with info:

You can get details on a particular environment as well:

You can run commands inside the environment:

This confirms that that the morloc compiler is installed and shows its version.

Alternatively you can create an interactive session inside the Morloc container:

You are now inside a shell in the container. You can check that the Morloc compiler installed in the container is indeed the latest version:

The current working directory from your system is mounted. All changes you make in this directory will persist. The Morloc module directory for this environment from your home system is mounted as well, so any Morloc modules you install will persist. That beind the case, let’s install the Morloc standard library:

The Morloc stdlib module is a re-exporter of all the Morloc individual standard library modules. So installing it is a shortcut for explicit installation.

You are now ready to run almost any code in the docs.

This C++ definition for unit conversions is fine, but it would be helpful to be able to do conversions natively in any language without needing to define new helpers or make foreign calls to the C++ functions. In Morloc we can write code that is language independent, like so:

If you get the error that the root is not installed, you can install all the Morloc standard library modules with:

The root module is a language independent Morloc module that defines the typeclasses for arithmetic among other things. Since our new module is fully language-agnostic, we cannot directly compile it, but we can typecheck it:

Now to actually compile this program into something we can execute, we need to import a module that contains sourced implementations. Let’s define a main.loc module that imports the types module.

The .units specifies the relative path to a local Morloc module. The module, root-cpp, stores C++ implementations of root terms, here we just need the arithmetic operator definitions.

If we instead wanted to build in Python, we could substitute the root-cpp import for root-py. Alternatively, we could import both root-cpp and root-py and let the compiler decide which implementations to use.

Anonymous functions are written with a backslash, one or more parameters, and →. They capture free variables from the enclosing scope, so a lambda can refer to bindings defined outside it:

Here bias is captured from the outer parameter list. Lambdas must take at least one argument: the zero-argument form \ → 5 is a parse error. To wrap a value as a "function with no arguments", use the effect system (see the section on effects and delayed evaluation) rather than a lambda.

Importing builtin functions can be problematic. This is why we sourced the map and sum functions from Python under the Python names morloc_map and morloc_sum.

If we directly sourced the builtins, as below:

The functions map and sum would be treated by the code Morloc generates as functions that are exported from the foo module. The generated Python code will access these functions under the foo namespace as foo.map and foo.sum. But map and sum are Python builtins, not direct exports, so they must be re-exported at the top of the source file:

For third-party modules, any term that is passed to Morloc will need to be locally defined (def bar(…​)) or specifically imported (from somemodule import bar).

The Eq and Ord typeclasses in root provide the standard comparison operators. They work over any type with the appropriate instance — integers, reals, strings, and tuples and lists of comparable values.

The root module defines logical conjunction (&&), disjunction (||), negation (not), exclusive-or (xor), and not-and (nand):

&& and || are short-circuiting and right-associative. && binds tighter than ||, matching the convention of most languages:

The root module provides several functions in the Foldable family that return Bool:

any returns True if the predicate holds for at least one element. all returns True only if the predicate holds for every element. elem checks membership using ==.

Booleans drive Morloc’s guard syntax. A guard alternative starts with ? and selects the first branch whose condition evaluates to True; the : line is the fallthrough:

See the Guards section for a full description of guard syntax.

The Int type is Morloc’s universal integer. The on-wire representation is variable-width: values up to 64 bits fit in 16 bytes inline, and larger values spill to a pointer to an array of 64-bit limbs. The in-language range of Int, however, is determined by the host language’s native integer type:

A morloc program that needs a value above 32 bits in C or R should declare the field as `Int64` (or `UInt64`), which maps to `int64_t` in C and to R’s numeric (with 53-bit integer precision via double).

Integer literals are Int by default:

Python natively supports arbitrary-precision integers. Morloc’s Int type takes full advantage of this. For example, computing large factorials:

This produces a 525-bit integer — far beyond what any fixed-width type can hold. The value is stored as a multi-limb big integer and printed correctly.

When a big integer is passed to a language whose concrete type cannot represent it, Morloc produces a clear error at the language boundary. The error states the value’s size, the target type’s bit width, and its representable range.

For example, passing a large factorial from Python to C++:

Small values pass through without issue:

But large values produce a descriptive error:

The same applies to R, which is limited to 32-bit integers and 53-bit integer precision via doubles:

Note the use of idpy in the example above. This forces the factorial computation to run entirely in Python, where int is arbitrary precision. Without this, the compiler will collapse the implementation of fact to pure C++, which would be much faster, but would not show the cross-language behavior.

Integer literals are bounds-checked at compile time against the type they’re written into. A literal that overflows its target type is rejected with a sourced error pointing at the literal:

The error caret points at the literal itself, not the binding name — so when the same literal is referenced from multiple sites, the diagnostic stays on the offending source.

For code where values are known to be bounded, use fixed-width types. These map directly to the target language’s native types:

Fixed-width types use direct binary serialization with no overhead — the serialized format is identical to the in-memory representation. This is the right choice for numerical code and interop with C libraries that require specific widths.

Morloc supports unary minus (-) on any numeric type. The same glyph plays two roles — the binary subtraction operator and the unary negation operator — and the rule for distinguishing them is whitespace-sensitive.

Real literals are written with a decimal point or scientific notation:

A literal without a decimal point and without an exponent is parsed as an Int, not a Real. Use 1.0 or 1e0 if you want a floating-point literal of value 1.

Morloc’s Real type reflects IEEE 754 in full: the value space includes the finite reals representable in the target precision plus three classes of non-finite values that are reserved bit patterns in the standard:

These are produced by ordinary IEEE 754 arithmetic — e.g. dividing by zero, overflowing the finite range, or evaluating an indeterminate form like Inf - Inf or 0 * Inf. They are not error states; they are values that propagate through subsequent computation according to spec-mandated rules.

Real literals are bounds-checked at compile time against the type they’re written into. A literal whose magnitude exceeds the target precision’s representable range is rejected with a sourced error pointing at the literal.

For Real and Float64 (max ≈ 1.8e308):

The check is per-target-precision, so a literal that fits Float64 but overflows Float32 (max ≈ 3.4e38) is rejected when typed as Float32:

Negative-magnitude literals are checked symmetrically:

The non-finite literal forms Inf, -Inf, and NaN bypass the bounds check by construction — they are explicit non-finite values, not finite literals that happened to overflow.

The JSON wire format is RFC 8259-compliant: standard JSON has no syntax for non-finite numeric literals, and the spec’s recommended workaround is strings. Morloc emits non-finite Real values as quoted lowercase strings:

This means a Real-typed field can appear either as a JSON number or as a JSON string in output. Consumers should accept both shapes.

The JSON decoder is liberal: it accepts every common spelling case-insensitively, with optional sign, plus the bareword null decoded as NaN for backward compatibility with payloads written by older Morloc runtimes:

For example, calling a pure-morloc identity from the command line:

Internal cross-language boundaries (Morloc-to-pool calls) use a binary format that preserves IEEE 754 bytes verbatim, so non-finite values round-trip without information loss. Only the JSON boundary — typically the program’s final output — uses the string form.

Float32 halves memory usage relative to Float64 and is the right choice for large numerical arrays (tensors, image buffers, GPU input) where the extra precision is not needed. The tradeoffs to keep in mind:

For most application code, Real (mapped to double / numeric / host-language float) is the right default. Reach for Float32 deliberately when memory or interop with single-precision hardware demands it.

Negation works on Real, Float32, and Float64 the same way it does on integers, via the Negatable typeclass. See the integers chapter for the full unary-minus rules. The IEEE 754-relevant differences for Real:

A particularly thorny issue in multi-lingual string support involves NUL character. In C strings, NUL characters (0 in ascii) terminate strings and thus they are generally illegal. Common C functions like strlen and strdup would fail if any NUL exists in a string. R, which is built on C, makes within-string NUL characters strictly illegal. On the other hand, Python and C++ (through the standard template string type) support NUL in strings. While these languages support NUL’s, problems can still arise in the common case where these string objects are converted to C-strings — e.g., through direct access in C++ with the .c_str() method or through C ABI in Python.

NUL’s are not common in strings. The main use case is to store binary data. This is not the recommended use of the Str type, though. It would generally be better to use [Uint8] to store bytes (or even better, Vector n Uint8, as will be introduced later). However, the Morloc philosophy is to support what is idiomatic in a language. The Str type is meant to represent the default string type in all languages (like the Int type). So the Morloc Int fully suports NUL’s in strings. They may be present in string literals through the \0 character, the Morloc evaluator preserves NULs end-to-end, and JSON represents them with the standard \u0000 escape.

All languages have an allow_string_null in their lang.yaml spec that specifies whether NUL’s are allowed. When a Str vale with a NUL character is sent to a NUL-intolerant language, the Morloc runtime rejects the call with a clear error message:

A Str literal that is destined to live in source of a NUL-intolerant language (typically an R-sourced function whose argument is a literal NUL string) is rejected at compile time, since the pool would otherwise fail to parse the generated source. The error names the offending pool language.

Checking all strings for NUL characters, however, is expensive. You can opt out when safe in two ways:

Both are unsafe: a NUL passing into R will still crash inside the R runtime, just with R’s own error rather than the morloc-level diagnostic. There is no way for user-written R code to do anything useful with a NUL string.

Tuples may be used to store a fixed number of terms of different type.

Tuple types and tuple values are both represented as comma-delimited values within parentheses. The parenthesized type representation is syntactic sugar for a fixed-size tuple type such as Tuple3 or Tuple8; the parser generates the appropriate TupleN form from the number of fields, so there is no fixed upper bound on tuple arity. Generally, if you have more than a few members in a tuple, it is better to define a record type with named values.

Lists are homogeneous, variable-length sequences of values. The base list type is List a, which can be written as [a]:

The default List type maps to each language’s natural ordered container (list in Python, std::vector in C++, list/vector in R).

While all list types share the same representation on the wire — zero or more elements in contiguous memory — there are several data structures that for accessing this data that have different performance tradeoffs. Deques can efficiently add elements to the beginning or end of the list. For an introduction in how to specialize types, see the section on type hierarchies.

A more rigorous and high-performance alternative to the List type is the Vector type, the 1D tensor, that is described in the Tensors chapter.

Tuples may be used to store a fixed number of terms of different type.

Tuple types and tuple values are both represented as comma-delimited values within parentheses. The parenthesized type representation is syntactic sugar for a fixed-size tuple type such as Tuple3 or Tuple8; the parser generates the appropriate TupleN form from the number of fields, so there is no fixed upper bound on tuple arity. Generally, if you have more than a few members in a tuple, it is better to define a record type with named values.

Field values in a record literal are bound to declared fields by name, not by position. The order in which fields appear in the literal is irrelevant. The two literals below denote the same value:

A literal must mention every declared field exactly once. Missing a declared field, naming a field that does not exist on the record, or repeating a field name is a compile-time error.

The "foo.R" file contains the function:

No special code is needed for person, it is just a builtin R list. Similarly for Python:

C++ requires a definition of a person_t struct:

Records may be initialized and functions called on them:

foo, above, initializes a Person record and then increments its age 3 time in different languages.

The two forms differ in how they treat repeated names. let is non-recursive sequential: each binding is in scope for everything that follows, and a later binding can shadow an earlier one of the same name. where is order-invariant: every binding sees every other, so a name can only be bound once in a single clause and cannot collide with a function parameter.

This code is legal:

Whereas similar patterns in a where clause are rejected at compile time:

Morloc supports recursive function definitions. A function may refer to itself in its body, and the compiler will generate the appropriate code in the target language.

The classic factorial function can be written using guards and self-reference:

Functions may also be mutually recursive. The following pair of functions determines (rather inefficiently) whether a number is even or odd:

A morloc type is recursive when its definition refers to itself. To terminate, the recursion must be guarded — every cycle through the definition must pass under an ?T (optional, with Null as the base case) or [T] (list, with [] as the base case). Bare self-reference like type X = X is rejected at compile time, as are cycles spanning multiple type definitions.

The examples below assume one stdlib import for working with optional values:

isNull tests whether an optional value is absent; require asserts it is present and strips the ?.

Morloc is a functional language. A function maps a value in one domain to a value in another, and the mapping is the function’s whole meaning. That works neatly for arithmetic, for string manipulation, for transforming records. It runs into trouble the moment we try to talk about anything that touches the world.

Consider readFile:

This looks like a function from a filename to a string. Indeed it is a function at any given instant on a given machine: the filename names a particular file, and the file has particular contents. But files change. If we read the same file twice in the same program, we may get two different answers. So it matters when we call the function and we may want to call it a several different points in time.

The same problem shows up for "values" that are not really values. What is the type of the current time? What is the type of a coin toss?

We could try to make them into honest functions by handing them an explicit world or an explicit random seed — time :: TemporalState → Time, coinToss :: RNG -> (Bool, RNG) — and thread the state through every call that needs it. This can work, but it pulls extra plumbing into every signature.

Morloc takes a different route: it gives the effect a name at the type level. <Rand> Bool is not a Bool; it is a suspended computation that, when run, performs the Rand effect and yields a Bool. Where the original problem was "this looks like a value but doesn’t act like one", the solution is to give it a type that says so.

Effect labels are names that the compiler propagates and checks for coverage. What an effect means — what Error represents, what IO permits at runtime, what Rand looks like operationally — is the business of the library that defines the effect, not the compiler. The compiler’s job is to keep the labels honest; libraries build behaviour on top.

The whole type-checking story for effects is four rules.

A few illustrations:

There is one more guarantee the user sees but does not write down: an exported <E> T is forced automatically at the boundary. The compiled program’s user receives a T. Effects do not escape the binary.

Combinators that thread effects need to be able to talk about sets of unknown effects. For that, an effect row may include a single lowercase variable that represents a set of zero or more unknown effects:

The function mapE, below, carries the all the effects of the mapping function to the final value:

Effect variables and constants may be mixed, but there may be no more than one effect variable associated with a given term.

In the following code, the signature states the requirement that function f produce a random effect, but allows other effects to be produced as well.