Stdlib reference (mere)

202 builtins that are always available via initial_env. Check a name's type with mere -te NAME.

Legend:

• ⚡ = may raise Eval_error
• ★ = polymorphic (builtin-level polymorphism, not let-poly)
• 🌐 = works in all 4 backends (interp + C + LLVM + Wasm) — added incrementally through Phases 22-31

Sugar / prelude added in Phase 36 (2026-06-22)

Syntactic sugar (13): lexer / parser-level changes only; preserves 4-backend compatibility:

• a..b — range literal (desugars to range a b; inclusive on both ends)
• (+ N) / (* N) etc. — operator section (11 operators; - is excluded)
• h :: t — cons (sugar for Cons (h, t); right-associative)
• f <| x — reverse pipe (f x; RHS accepts fn / let)
• f @@ x — OCaml-style alias for <|
• \x -> body / \a b c -> body — lambda shorthand (no type annotations)
• "hello {expr}" — string interpolation (desugars to ++ (expr) ++; \{ escapes a literal brace)
• let x = e? in body — Option early-return
• let x = e?! in body — Result early-return
• [expr | x <- xs, cond, y <- ys, ...] — list comprehension (multi-generator + filter in any order)
• if let pat = e then ... else ... — conditional destructure
• for x in xs do body — sugar for list_iter
• while cond do body — desugars to a recursive helper (codegen supported inside fn bodies only)

Prelude additions (16 of 34 entries added in Phase 36):

• range / list_filter / list_take / list_drop / list_find / list_append
• list_concat / list_flat_map / list_zip / list_for_all / list_any
• list_member / list_sum / list_product / list_max / list_min

I/O (12)

The FFI byte arena's `bytes` bridge (v0.1.282). tcp_read and friends write into an integer-addressed arena, and mem_to_str cannot bring binary back out — it stops at the first zero byte, which every binary protocol has. Declare these as extern fn alongside the rest of the mem_* family:

extern fn mem_to_bytes: int -> int -> bytes;          // arena ptr, len -> bytes
extern fn mem_copy_bytes: int -> int -> bytes -> int; // arena ptr, offset, bytes -> written

Native (C) and a Wasm component both provide them; scripts/socket_parity.sh requires the two backends to agree. In a plain Wasm build they become an env host import like any other extern, so a host that does not provide them fails at instantiation with a missing-import error rather than a wrong answer.

file_exists "/etc/hosts"            // → true
env_var "PATH"                      // → Some "..."
env_var "BOGUS"                     // → None
read_lines "data.txt"               // → ["line1", "line2", ...]
args ()                             // → ["foo", "bar"] (mere prog foo bar)
run "clang -O2 main.c -o app"       // → 0 on success, nonzero exit code otherwise

Sockets are extern fn declarations rather than builtins — the C backend defines them when a program declares them (native_ffi_names in codegen_c.ml), which is why they take flat-arena offsets rather than bytes. They are native-only in practice.

What `tcp_read` returns (v0.1.226, mraft dogfood). A count when it read something, and 0 at end of stream — a peer that closed cleanly, which is information rather than a failure. A negative result says which failure, because with a timeout set these are opposite events for the caller:

Before v0.1.226 every failure was -1, and a program that needed the difference had to time the call and ask whether it had failed slowly enough to have been a timeout — inferring a cause from a duration. Every existing < 0 check is unaffected. scripts/tcp_read_codes.sh produces all three rather than describing them.

On Wasm the whole family works — scripts/socket_parity.sh runs the same round trip natively and under wasmtime -S inherit-network=y and compares — with two differences:

• A failed read returns `0`, the same value C uses for a clean end of stream.

Telling them apart means decoding WASI's stream-error variant rather than its is-error bit.

• `tcp_set_timeout` is refused at codegen (v0.1.227). It used to compile to a

no-op that returned success, so a program that set a deadline blocked forever on the next read. A bounded wait needs the native backend.

Positioned file I/O (file_openrw through file_close) works on all four backends: interp and C natively, Wasm over host imports since v0.1.153 (bytes cross in the mere_bytes layout rather than one call per byte), LLVM since v0.1.163. It is the group a paged store or a write-ahead log needs, and it was documented only in the changelog until v0.1.222 — which is how the mraft dogfood came to write its log through the Vec-taking call for a whole slice before noticing.

★ Codegen status (v0.1.246 for the first two): print_no_nl and print_err lower on interp + C + LLVM; both were refused by LLVM until it grew a write(fd, ...) for its own panic diagnostic, at which point they were three lines each. On Wasm print_err is refused: it used to write to the same host sink as print, so a diagnostic landed in the program's own output and nothing said so, and the JS host ABI has no second sink to give it. print / print_int / print_bool / read_file / write_file work in all 3 backends (Wasm goes through host imports; scripts/run_wasm.js provides puts / read_file / write_file). print_int / print_bool were the exception until v0.1.190 — this line claimed them for years while only the interpreter had them; C emitted a call to an undefined symbol and LLVM / Wasm refused outright. They now lower on all four (C through printf, LLVM and Wasm through the str_of_int they already had), locked by test/parity/print_int_bool.mere. read_lines / env_var are interpreter-only (codegen would need 'a list / 'a option construction + systematic outside-world access; not yet covered by Phases 22-31). args works on all four backends: C and LLVM read the argc/argv their main was handed, Wasm folds the host's arg_count / arg_get (v0.1.159 for Wasm, v0.1.169 for LLVM). The native-CLI / dogfood builtins run / print_err / file_exists / file_mtime / file_size / tty_raw / tty_restore / read_key / random_int also work on the C native backend (added for the mk / mrog / mwasm dogfoods, v0.1.13-v0.1.21).

let _ = print "Hello";
let _ = print_no_nl "Name: ";
let name = read_line () in print ("Hi, " ++ name);

// File round-trip
let _ = write_file "/tmp/out.txt" "hello lang";
let content = read_file "/tmp/out.txt" in print content;

Value conversion (3)

Why the bits come out in two halves. A double's pattern read as one signed int64 does not fit the interpreter's native int — which is OCaml's, and 63-bit — for a large share of ordinary values: -1.5, 1e308, inf and nan all exceed it. A single 64-bit accessor would therefore answer differently on the interpreter than on every compiled backend, for a literal as plain as 1e308. Each 32-bit half is always below 2^32, so there is nothing left to diverge about. Pinned by test/parity/float_bits.mere on all four backends.

These are the primitive the rest is built from: contrib/proto/wire.mere writes a protobuf double as put_double and a float as put_float on top of them, and neither the caller nor the generated codec learns about the split.

str_of_int 42        // "42"
int_of_str "  -7  "  // -7
bool_of_str "true"   // true

String operations (22)

type 'a list = Nil | Cons of 'a * 'a list;
str_split "a,b,c" ","                          // ["a", "b", "c"]
str_join "-" ["alpha", "beta", "gamma"]        // "alpha-beta-gamma"
str_index_of "hello world" "world"             // 6
str_index_of "hello" "xyz"                     // -1

★ Codegen status: str_index_of / str_split / str_join / str_count / str_compare / str_trim / str_starts_with / str_ends_with / str_contains / str_replace / str_repeat / str_rev all work across all 4 backends (Phase 19.1.1 added str_index_of; Phase 22 added str_split / str_join; Phase 26.5 added all Wasm str ops; Phase 31.0 added str_compare; Phase 36 added str_trim / starts_with / ends_with / contains / replace / repeat / rev). not / abs / min / max / clamp / chr / ord / to_upper / to_lower / even / odd / gcd / bool_of_str also reached the 3 backends in Phase 36. The fn (_: unit) -> body wildcard parameter was also parser-fixed in Phase 36.

str_replace "foo bar foo" "foo" "X"           // "X bar X"
substring "hello world" 6 11                  // "world"
char_at "abcdef" 2                            // "c"
"world" |> str_contains "hello world"         // true (pipe + curry)
str_unescape "a\\nb"                          // a + newline + b (3 chars)

Numeric operations (23)

★ A transcendental is not correctly rounded by anybody (v0.1.248). exp and log reach C through libm, LLVM through @llvm.exp.f64, and Wasm through the host's Math.exp — and measured, exp -10 is 4.5399929762484854e-05 on three of those and 4.539992976248485e-05 through JavaScript. That is not a bug in any of them. test/parity/exp_log.mere therefore prints exact values only at the points that are exact in binary floating point (exp 0, log 1) and asserts everything else as an identity within a tolerance — which still fails an exp that returns its argument or a log wired to log10, and does not report the C library's build options as a difference.

★ Integer `/` and `%` by zero raise (v0.1.247): division by zero and modulo by zero, catchable with try_or, on the interpreter and the C, LLVM and Wasm backends. It cost a branch per division to make that true, and it was worth it because the alternative was not one behaviour but four: the interpreter raised, the C backend emitted a bare a / b — undefined behaviour in C, which an arm64 build answers with 0 and an x86-64 build answers with SIGFPE — LLVM emitted sdiv, which is undefined in IR and licenses the optimizer to assume it cannot happen, and Wasm trapped with no message at all. INT_MIN / -1 is the other undefined case and wraps now, which is what the interpreter already did.

The `-rv` backend is the exception, and it is measured rather than assumed: under QEMU's virt board, 17 / 0 is -1 and 17 % 0 is 17 there — the RISC-V specification's non-trapping answer. That backend targets bare metal, where there is no stream to write a diagnostic to and no process to exit: the platform's answer is the answer. Float division is IEEE on every backend and keeps giving inf / nan.

★ On the width these are actually computed at (v0.1.245): a builtin can be present on every backend, answer every small question correctly, and still be implemented at a narrower width than the language's int. gcd was a static int __lang_gcd(int, int) in the generated C — gcd 3037000493 3037000493 came back as 1257966803 — and int_of_str on LLVM parsed with strtoll and then truncated the result to i32, so the largest int read back as -1. Both were invisible to every existing test and to host-matrix.md, because the arguments used to probe a builtin were all one or two digits.

test/parity/int_width.mere is the gate for this: every deterministic int builtin, with arguments above 2^31, held to one answer on all four backends. It found the second bug while being written for the first. Values there stay inside ±(2^62 − 1) so that the interpreter's 63-bit int is not itself the difference — and note that an intermediate counts: sum_range used to form a product twice the size of its own answer, which made it portable over only half the range its result could hold.

Float arithmetic (4)

Note (v0.1.44): the infix operators + - * /, all comparisons, and unary - are numeric-overloaded and work directly on floats, on every backend — prefer them. The f_ functions below remain as ordinary function values (useful for passing to higher-order functions). The overload resolves to float only when an operand is concretely float; annotate fn params (fn (x: float) -> ...) in float-heavy code.

★ Codegen status: the 11 entries added in Phase 19.7 are interpreter-only. Codegen support requires libm linking or per-backend wiring of built-in math functions, planned for a follow-up slice (19.7.1).

f_add 1.5 2.5                    // 4.0
f_div 10.0 4.0                   // 2.5
3.14 |> f_mul 2.0                // 6.28

clamp 0 100 150                  // 100
pow 2 10                         // 1024
gcd 12 18                        // 6
sum_range 1 100                  // 5050
fst (divmod 100 7) + snd (divmod 100 7)   // 14 + 2

Control / error (3)

let safe = fn s -> try_or (fn () -> int_of_str s) (- 1);
safe "42"      // 42
safe "abc"     // -1

if x < 0 then fail "negative" else x

fail is polymorphic, so type inference works at branch merges (if c then fail msg else int_val → int).

★ What an uncaught failure does (v0.1.246): the program writes one line to stderr and exits 1, on every backend. The line is the message raised, tagged fail: when it came from the fail builtin — the tag belongs to the builtin, so a backend's own failures (int_of_str on junk, an out-of-range index) are not tagged, which is what the interpreter has always done. The interpreter additionally prefixes the source file it is running; a compiled binary has none.

None of that was true before. The same program exited 1 on two backends and 134 (SIGABRT) on two others, wrote its diagnostic to stderr on two and stdout on two, tagged the message on three and not on the fourth, and int_of_str on junk named the offending input on two backends and not on the other two. It went unnoticed because the parity harness compared stdout and nothing else, so no parity test used `fail` — none could have passed. test/parity/fail/*.mere is the gate now: exit status, the output written before the failure, and the message, on all four.

Two limitations remain, and both are pinned rather than described:

• Wasm has one output sink. The JS host ABI provides env.puts and nothing else,

so the diagnostic lands in stdout there. The harness knows this and would break if it changed. Under --component the same backend writes through WASI.

• `fail` on Wasm does not unwind. It sets a flag that callers check on the way

out, so statements after it in the same body still run: inside a try_or thunk, work that follows the failure happens. test/parity/failure_caught.mere holds the other three to one answer and declares Wasm's exact output in a .wasm.expected file next to it, so the day that backend learns to unwind, the declaration breaks and says so.

try_or catches all of these on all four backends, including the ones raised inside the backend rather than by fail. What it hands back is the default — not the message: the language can observe that something failed, not why.

Polymorphic helpers (8 ★)

show 42                          // "42"
show (Some 5)                    // "Some 5"
show [1, 2, 3]                   // "[1, 2, 3]"   (Cons/Nil chains shown as [..])
show [Some 1, None, Some 3]      // "[Some 1, None, Some 3]"

fst (pair "hi" 42)               // "hi"
let always_7 = const 7 in always_7 "anything"   // 7
let sub = fn a -> fn b -> a - b in (flip sub) 3 10   // 7 (= sub 10 3)

JSON, derive-style (5 ★)

Structural JSON, compile-time-specialized per type (no trait machinery), like show. to_json works on all four backends — on LLVM it shares the emitter with show, since the two differ only in literals (v0.1.184). of_json and its siblings are interp / C / Wasm: decoding needs a JSON parser in the target language, and LLVM has no hand-written one.

Decoding inside a polymorphic function

of_json reads the target type off the call node, which is fine at a use site with an annotation and impossible inside a generic helper: there the node's type is a variable, and the interpreter has no runtime types to resolve it with. So a generic "decode it back" had to name the record type, and every record needed its own copy.

A witness supplies the type instead. The interpreter reads it off the value's runtime shape — a record carries its type's name — and the compiled backends read it off the witness's static type, which is the same variable the result unifies with:

let with_field = fn (rec_) -> fn (name: str) -> fn (v: str) ->
  ... of_json_opt_like rec_ (rebuilt_json) ...

The witness is a value the caller already has whenever this comes up: replacing one field of a record means holding the record. contrib/schema is this, and examples/claims generates its whole form from it.

A polymorphic record still needs the annotation — a value carries its type's name but not its type arguments, so a witness cannot describe Box[int].

The of_json result type comes from the use site — annotate the expression: (of_json s : T). A JSON object maps to a record's fields (by name), an array to a list or tuple, null/value to option (None / Some), and a string / {"Ctor": payload} to a variant. to_json uses the same mapping in reverse, so (of_json (to_json x) : T) == x.

type User = { id: int, name: str, bio: str option };
to_json (User { id = 1, name = "ada", bio = None })
                                 // {"id":1,"name":"ada","bio":null}
let u = (of_json body : User);   // fails fast if body is malformed
match (of_json_opt body : User option) with
| Some u -> u.name               // decoded
| None   -> "bad request"        // malformed / missing field — no crash

Comparison, derive-style (v0.1.11)

== / != (structural equality) and < <= > >= (structural ordering) are compile-time-specialized per operand type — the same no-trait mechanism as show / to_json. Both work on interp / C / Wasm.

• Scalars: int / float / bool / str compare directly (str

lexicographically).

• Compound: tuples and records compare field-by-field in declared

order; lists compare element-wise (a shorter prefix is smaller); variants order by declaration order (the constructor listed first is smallest), then by payload. All backends agree byte-for-byte, so a value sorts the same under the interpreter, a native binary, and Wasm.

(1, 2) < (1, 3)                        // true  (tuple, lexicographic)
[1,2] < [1,2,3]                        // true  (prefix is smaller)
type C = Red | Green | Blue; Red < Blue // true  (declaration order)
list_sort_by (fn (a: float) -> fn (b: float) -> a < b) [3.1, 1.2]  // [1.2, 3.1]

Honest edges. float uses a total order where NaN sorts as least. Comparing two functions is defined but meaningless (they order as equal). The bare default list_sort still bakes in an int comparison — its comparator's type variables default to int, the same rule that keeps fn a -> fn b -> a < b monomorphic — so sorting a non-int list needs list_sort_by with an annotated comparator (as above). A fully-polymorphic list_sort over any orderable element would need ad-hoc-polymorphism resolution (deferred).

Loop helper (1 ★)

Capability (2 + 2 builtin record types)

Used by the effect system (see effects.mere). The Logger and Metrics cap types are pre-registered as builtins. Users can also override with their own type Logger = ....

type Logger  = { info: str -> unit, warn: str -> unit, error: str -> unit };
type Metrics = { inc: str -> unit, record: str -> int -> unit };

let lg = mk_logger "app" in
{ lg.info "started";
  lg.warn "slow query";
  lg.error "abort" }

let m = mk_metrics () in
{ m.inc "users";
  m.record "latency_ms" 23 }

For a complete cap-passing example see examples/effects.mere.

Raw memory, CSRs, traps and tasks (14, RV32I bare-metal only)

A Raw is a window onto physical memory — the one capability that is not a record of functions, because its operations lower to load and store instructions. It is the escape hatch a device driver needs, and it is a value rather than an ambient builtin so that "this function cannot touch raw memory" is something you read off a signature.

Raw is opaque: nothing constructs one, and there is no function that mints one. The only source is the argument mere -rv --bare hands to the program's top-level main, and raw_window can only narrow it. Offsets are relative to the window, so a driver holding a UART window cannot express an address outside it; every access bounds-checks the offset, and widening faults.

let putc = fn (uart: Raw) -> fn (c: int) -> raw_poke8 uart 0 c;

let main = fn (mach: Raw) ->
  let uart = raw_window mach 0x10000000 256 in    // the UART, and nothing else
  putc uart 65;

A context switch needs no new mechanism: the trampoline saves the interrupted register set to the area trap_save hands back and restores from it before mret, so a handler swaps tasks by copying through it and returning the incoming task's PC. Switch every register, gp included, and give each task a heap arena of its own (carve it from machine_scratch — heap up from the bottom, stack down from the top). Sharing one heap looks workable until a region R { } in one task rolls the bump pointer back and frees what another task allocated meanwhile; the rule that survives is that contexts share gp only if they genuinely share a heap, and a context that uses regions must not. See examples/riscv_bare_sched.mere.

Device MMIO sits above any RAM (the UART data register is at 0x10000000, the address QEMU's virt machine uses), so a device address does not move when --ram does. On every other backend these refuse: there is no honest physical address in a hosted process. See examples/riscv_bare_uart.mere.

System / constants (4)

let start = time () in
{ run_heavy_computation ();
  print ("elapsed: " ++ str_of_float (f_sub (time ()) start) ++ " sec") }

if config_invalid then exit 1 else continue ()

iter_n 3 (fn () -> print "===")   // prints === three times

All builtins (alphabetical, 129)

abs args assert atan2 bit_and bit_not bit_or bit_shl bit_shr bit_xor
bool_of_str ceil char_at chr clamp const
cos cube decr divmod e env_var even exit exp f_abs f_add
f_div f_ge f_gt f_le f_lt f_max f_min f_mul f_neg f_pow
f_sub fail file_exists flip float_of_int float_of_str floor
fst gcd id incr int_max int_min int_of_float int_of_str
is_alpha is_digit is_space iter_n lcm log max min mk_logger
mk_metrics not odd ord pair pi pow print print_bool
print_err print_int print_no_nl random_float random_int
closure_code closure_env csr_read csr_write machine_scratch
raw_base raw_len raw_peek32 raw_peek8 raw_poke32 raw_poke8 raw_window trap_save
stdin_byte
read_file read_file_bytes read_line read_lines round show sign sin snd sqrt
square str_compare str_contains str_count str_ends_with
str_index_of str_join str_len str_of_float str_of_int
str_repeat str_replace str_rev str_split str_starts_with
set_trap_handler str_trim str_unescape substring sum_range swap tan time
to_lower to_upper try_or write_file write_file_bytes

Q-010 collection builtins (vec_* / owned_vec_* / strbuf_* / map_* / len) are registered builtins outside this table; see language-reference / tutorial. Phase 19.2 added `map_iter : Map[R, K, V] -> (K -> V -> unit) -> unit` (works in all 4 backends).

See also

• Operators (+ * == ++ |> << >> etc.) are language syntax, not builtins; see language-reference.md.
• Idioms: patterns.md.
• Real-world example: contrib/json/json.mere combines many stdlib functions in a 140-line JSON parser (promoted from examples/ to contrib/ in Phase 40).