Built-in Functions

Relux provides built-in functions (BIFs) that are always available without imports. BIFs are divided into two categories based on their purity — whether they require a shell context to operate.

Purity

• Pure BIFs do not interact with any shell. They can be called from pure functions, condition markers, overlay expressions, and regular shell blocks.
• Impure BIFs require a shell context (they send input or match output). They can only be called inside shell blocks and regular (non-pure) functions.

“Pure” here means shell-independent, not side-effect-free — a pure BIF may still touch the outside world (which reads the filesystem, timestamp reads the system clock) and need not be deterministic (uuid, rand). What it may not do is require a shell. sleep, log, and annotate do require one and are impure, despite doing nothing shell-specific.

Shell-independent also does not mean infallible. A pure fn body may contain a pure match (<expr> = <pattern> / <expr> ? <pattern>), and a non-matching pure match is an assertion failure: a pure fn that runs one can fail the test through whichever runtime site called it (a let, an overlay value, or a shell-block call). The one exception is a marker condition, where a pure-eval failure makes the condition falsy rather than failing the test.

Pure BIFs

String

Generators

System

A naive “bind port 0, read the number, close” probe returns a port from the OS ephemeral range — the same range the kernel uses for the source ports of outbound connections. Between picking the port and your service binding it, any client connection (a database bootstrap, a migration, a health check) can be assigned that number, and a closed client keeps the port in TIME_WAIT for 60 seconds. The result is a rare, unreproducible Address already in use at service start.

available_port therefore allocates strictly outside the ephemeral range. At first use relux reads the OS ephemeral interval (/proc/sys/net/ipv4/ip_local_port_range on Linux, net.inet.ip.portrange on macOS) and the privileged boundary, and allocates from the window between them, starting at a random offset. Every candidate is verified by binding it (ports in TIME_WAIT fail this probe and are skipped). A handed-out port is owned by the running test — across all its effects and functions — and is returned to the pool only after the test’s cleanup has completed, so within one relux run, no two concurrent tests can ever receive the same port.

The window can be narrowed with the manifest’s [available_ports] section (see the configuration chapter). On exhaustion of the window the call returns -1, like other BIF failures.

One residual caveat: this bookkeeping is per relux process, not a machine-wide reservation, so relux cannot stop an unrelated process on the machine — including another concurrent relux run invocation — from binding the chosen port before your service does. The allocation window makes that unlikely (the kernel never assigns those ports on its own), but it is not a guarantee.

Hashing

Time

timestamp always renders the current instant in UTC – there is no local-timezone mode. It deviates from chrono’s strftime in two ways: fractional-second specifiers accept any width, not just chrono’s fixed 3/6/9 (%1f..%9f, %.1f..%.9f, and widths above 9 right-pad with zeros), and an unknown specifier is emitted verbatim instead of being blanked out. Like uuid and rand, timestamp is non-deterministic across calls – it reads the system clock – but it is still a pure BIF because it never touches a shell.

timestamp("%Y-%m-%dT%H:%M:%SZ")  -> 2026-07-28T15:30:45Z
timestamp("%Y%m%d-%H%M%S")       -> 20260728-153045
timestamp("%s")                  -> 1753716645
timestamp("%H%M%S-%6f")          -> 153045-123456

Impure BIFs

Shell matching

Control characters

Timing

Logging