Crate oxdock_parser

Expand description

Parser and AST definitions for the OxDock DSL.

The full command reference below is generated by docs-gen from the command metadata registry (declare_commands! in oxdock-parser).

The reference’s fenced examples use oxdock … info strings consumed by the docs-conformance harness (not Rust code), which rustdoc legitimately flags : hence the targeted allow below.

The oxdock_parser self-alias lets #[oxdock_type]-generated code inside this crate resolve ::oxdock_parser:: paths exactly like downstream crates do.

§Command Reference

See the changelog for what changed in each release.

Command	Syntax
`WORKDIR`	`WORKDIR <path>`
`WORKSPACE`	`WORKSPACE (SNAPSHOT\|LOCAL\|CACHE\|SYSTEM) [--local]`
`ENV`	`ENV KEY=value`
`INHERIT_ENV`	`INHERIT_ENV [<key>, ...]`
`ECHO`	`ECHO <message>`
`RUN`	`RUN <command...> \| RUN ["exe", "arg", ...]`
`COPY`	`COPY [--from-workspace SNAPSHOT\|LOCAL\|CACHE\|SYSTEM] [--from-host \| --to-host] <from> <to>`
`COPY_GIT`	`COPY_GIT [--include-dirty] <rev> <src> <dst>`
`SYMLINK`	`SYMLINK [--from-workspace SNAPSHOT\|LOCAL\|CACHE\|SYSTEM] <from> <to>`
`MKDIR`	`MKDIR <path>`
`INSTALL`	`INSTALL <source> <dest>`
`LS`	`LS [<path>]`
`CWD`	`CWD`
`READ`	`READ [<path>]`
`READ_LINE`	`READ_LINE $var`
`PROMPT`	`PROMPT $var <message> [<default>]`
`WRITE`	`WRITE <path> [<contents>]`
`APPEND`	`APPEND <path> [<contents>]`
`REMOVE`	`REMOVE [--recursive] <path>`
`EXPAND`	`EXPAND [<path>] [<KEY=val> ...]`
`ASSERT_EQ`	`ASSERT_EQ <actual> <expected> \| ASSERT_EQ --hash <sha256> <actual>`
`ASSERT_CONTAINS`	`ASSERT_CONTAINS <haystack> <needle>`
`HASH_SHA256`	`HASH_SHA256 <path>`
`EXIT`	`EXIT <code>`
`SLEEP`	`SLEEP <duration>`
`LIST_APPEND`	`LIST_APPEND $list <item>`
`WITH_IO`	`WITH_IO [<stream>[=$var], ...] <command> \| WITH_IO [bindings] { <commands> }`
`FOR`	`FOR $item: TYPE IN <expr> { <commands> } \| FOR $key: STRING, $value: TYPE IN <expr> { <commands> }`
`IF`	`IF <expr> { <commands> } [ELSE IF <expr> { <commands> } ...] [ELSE { <commands> }]`
`LET`	`LET $var: TYPE = <expr> \| LET $p: PIPE \| LET $var: TYPE = ASYNC { <commands> } \| LET $var: TYPE = <command> \| LET $var: TYPE = AWAIT $task \| LET $var: TYPE = { <commands> }`
`MUTATION`	`$var = <expr>`
`ASYNC`	`ASYNC <command...> \| ASYNC { <commands> } \| LET $var: HANDLE = ASYNC { <commands> }`
`AWAIT`	`AWAIT $var \| LET $out: STRING = AWAIT $var`
`CANCEL`	`CANCEL $var`
`TIMEOUT`	`TIMEOUT <duration> <command...> \| TIMEOUT <duration> { <commands> } \| TIMEOUT <duration> AWAIT $var`
`REMOTE`	`REMOTE <target> [[$var, ...] [env:NAME, ...]] { <commands> }`
`FUNC`	`FUNC NAME([$param: TYPE, ...]) { <commands> }`
`RETURN`	`RETURN [<expr>]`
`WHILE`	`WHILE <bool-expr> { <commands> }`
`BREAK`	`BREAK`
`CONTINUE`	`CONTINUE`
`IMPORT`	`IMPORT [<module>, ...] \| IMPORT <module>`

§WITH_IO

Reroute standard streams.

Syntax: WITH_IO [<stream>[=$var], ...] <command> | WITH_IO [bindings] { <commands> }

Reroutes the standard streams of the next command or, in block form, of every enclosed command.

Bindings map streams (stdin, stdout, stderr) to a PIPE-typed variable (stdout=$p, stdin=$p), resolved from the variable when the step runs. Both stdout and stderr pipes capture output the same way. Declare the handle first with LET $p: PIPE.

Pipes hold bytes in memory and spill to a temp file above 8 MiB, so a producer can finish before the consumer starts.

If WITH_IO wraps an ASYNC block whose body is a single RUN, guarded or not, the pipe is a zero copy OS kernel pipe instead: pair it with a consumer that runs while the producer is alive, since output past the 64 KiB kernel buffer stalls until drained. That promotion never crosses a function boundary: pipes created, bound, or passed by variable inside FUNC bodies are always script pipes, even when the surrounding task would otherwise promote.

A second producer or consumer on a live handle is an explicit error. A handle bound as output can later feed another command’s stdin, connecting commands without touching the terminal. Binding stdout and stderr to the same live handle fails deterministically. Merge streams in shell via 2>&1 instead.

Nested blocks stack defaults; inline bindings override inherited ones for their command only; closing a block restores previous wiring.

Examples:

Example: with_io block

LET $log: PIPE
WITH_IO [stdout=$log] {
  ECHO first
  ECHO second
}
WITH_IO [stdin=$log] WRITE captured.txt

# The piped bytes landed in the file.
LET $body: STRING = READ captured.txt
ASSERT_CONTAINS $body "first"
ASSERT_CONTAINS $body "second"

Example: variable pipe binding

# Declare the pipe first: `LET $p: PIPE` mints a fresh
# backend without touching a stream. A plain string here
# would be a TypeMismatch.
LET $p: PIPE
WITH_IO [stdout=$p] ECHO hello
WITH_IO [stdin=$p] READ_LINE $line
ASSERT_EQ $line "hello"

§FOR

Iterate over a list or map.

Syntax: FOR $item: TYPE IN <expr> { <commands> } | FOR $key: STRING, $value: TYPE IN <expr> { <commands> }

The loop variable receives each element (lists) or value (maps); with two variables, the first receives the key.

Loop variables are declared with explicit types and scoped per iteration; they do not leak outward. The body may be a braced block or a single-line { ... } command.

GLOB("...") patterns must be quoted (* is not a bare word, so GLOB(*) is a parse error); GLOB returns a root-relative sorted list, empty when nothing matches, and rejects .. escapes.

Examples:

Example: for loop

# Each element binds in turn; the loop body sees every one.
LET $items: LIST<STRING> = ["a", "b"]
FOR $item: STRING IN $items {
  ECHO $item
}
ASSERT_CONTAINS stdout "a"
ASSERT_CONTAINS stdout "b"

# Key and value bind together for maps.
LET $map: MAP<x: INT> = {"x": 1}
FOR $k: STRING, $v: INT IN $map {
  ECHO "{{ $k }}={{ $v }}"
}
ASSERT_CONTAINS stdout "x=1"

Example: expand every match

# Single-line body; $x is a template path, WHO an override.
IMPORT [STD]
WRITE a.txt "hi \{{ env:WHO }}!"
FOR $x: STRING IN GLOB("*.txt") { EXPAND $x WHO=World }

ASSERT_CONTAINS stdout "hi World!"

§IF

Conditional execution.

Syntax: IF <expr> { <commands> } [ELSE IF <expr> { <commands> } ...] [ELSE { <commands> }]

The condition is evaluated as a boolean expression.

Prefix ! negates (IF !false); && binds tighter than ||, and both short-circuit, so IF true || $missing never evaluates the right side. Only Bool values are accepted as conditions.

Examples:

Example: if else

IMPORT [STD]

# True branch runs; the false branch is skipped.
IF true {
  WRITE yes.txt taken
} ELSE {
  WRITE yes.txt skipped
}

# ELSE IF selects the first true branch.
IF false {
  WRITE skipped.txt no
} ELSE IF true {
  WRITE fallback.txt taken
}

# !false evaluates to true, so this branch runs.
IF !false {
  WRITE negated.txt taken
}

LET $yes_body: STRING = READ yes.txt
LET $fallback_body: STRING = READ fallback.txt
LET $negated_body: STRING = READ negated.txt
ASSERT_EQ $yes_body "taken"
ASSERT_EQ $fallback_body "taken"
ASSERT_EQ $negated_body "taken"
LET $t: STRING = PATH_TYPE("skipped.txt")
ASSERT_EQ $t "absent"

Example: logical condition composition

IMPORT [STD]
LET $role: STRING = "admin"
LET $level: INT = 3

# || is true when either side holds; && needs both.
IF $role == "owner" || $level >= 5 {
    WRITE unexpected.txt no
} ELSE {
    WRITE fallback.txt or-false
}

LET $fb: STRING = READ fallback.txt
ASSERT_EQ $fb "or-false"
LET $t1: STRING = PATH_TYPE("unexpected.txt")
ASSERT_EQ $t1 "absent"

IF $role == "admin" || $level >= 5 {
    WRITE chosen.txt or-true
}

LET $ch: STRING = READ chosen.txt
ASSERT_EQ $ch "or-true"

IF $role == "admin" && $level >= 5 {
    WRITE unexpected-too.txt no
} ELSE {
    WRITE and.txt and-false
}

LET $an: STRING = READ and.txt
ASSERT_EQ $an "and-false"
LET $t2: STRING = PATH_TYPE("unexpected-too.txt")
ASSERT_EQ $t2 "absent"

§LET

Bind script-local variables.

Syntax: LET $var: TYPE = <expr> | LET $p: PIPE | LET $var: TYPE = ASYNC { <commands> } | LET $var: TYPE = <command> | LET $var: TYPE = AWAIT $task | LET $var: TYPE = { <commands> }

Declares a script-local variable with an explicit type (STRING, INT, FLOAT, BOOL, PIPE, LIST, MAP, HANDLE, DURATION, PATH). Duplicate LET in the same scope frame is a redeclaration error; mutate with $var = <expr>.

Variables are usable in templates ({{ $var }}), guards, and expressions. With ASYNC, spawns a background task and stores its handle (see ASYNC). The $ sigil on the name is mandatory.

No hoisting: a variable exists only after its LET runs, in execution order. Reading $var before its LET (or after the block that declared it exits) fails with undefined variable $var. Scopes are a stack of frames and resolution walks innermost outward, so nothing pre-declares names. Function bodies read outer variables through the same walk, but their own LETs never leak out (see FUNC).

The right-hand side is always an expression — literals, lists, maps, arithmetic (+ - * / with *// binding tighter, unary -, parentheses), comparisons (< <= > >= binding tighter than == !=), logical && (tighter) and || with short-circuit, ! negation, env:KEY reads, INSPECT($var) snapshots, GLOB("*.md"), INT(x) / FLOAT(x) conversions — never a {{ ... }} template; interpolation happens in string values, not here. The one exception is pipes: LET $p: PIPE with no = and no initializer mints a fresh anonymous backend, lazily materialized at first binding, so two declarations never share a channel.

Numbers are numeric literals: 42 binds INT, 3.14 binds FLOAT. Int x Int stays INT (checked, integer division, so 7 / 2 is 3); any Float operand promotes to FLOAT. Division by zero, overflow, and non-finite results are errors. Both numeric sides compare numerically (1 == 1.0 is true); otherwise ==/!= compare rendered strings and ordering on non-numerics is a Type Error. Constant subtrees fold at parse time and dynamic arithmetic compiles to flat RPN with identical semantics.

Float equality is exact with no epsilon. Floats store decimals in binary, so a value is exact only when its reduced fraction has a power-of-2 denominator: 0.5 (1/2), 0.25 (1/4), 0.75 (3/4) are exact, while 0.1 (1/10), 0.2 (1/5), 0.3 (3/10) repeat forever in binary (like 1/3 in decimal) and truncate, so 0.1 + 0.2 == 0.3 is false (the sum is 0.30000000000000004). Rule of thumb: endings .5, .25, .75, .125, .625, .875 are exact; .1, .2, .3 and similar are approximations. Bound approximations instead of comparing them: IF $sum > 0.299999 && $sum < 0.300001.

Comparisons do not chain: a < b < c is a parse error, not (a < b) < c. Chaining would compare a BOOL against a number (a runtime Type Error in C-style parsing) or evaluate the middle term twice (Python-style chaining), so the grammar accepts exactly one comparison operator per level. Write the conjunction explicitly: $a < $b && $b < $c. The same holds for equality ($a == $b == $c is rejected).

Captured command output is a string, so convert before math: LET $total: INT = $total + INT($size_str) (INT trims ASCII whitespace; FLOAT accepts int strings and rejects non-finite).

Bare words need no quotes: LET $d: STRING = 30s binds the same string as quoted.

When the right-hand side is a synchronous command (LET $out: STRING = ECHO hi), the command runs to completion and its exact stdout bytes are captured into the variable as a string (no newline stripping; commands with no stdout capture as ""; non-UTF8 stdout is an error). Combining capture with an explicit WITH_IO [stdout=$var] is a parse error.

Coming from Bash, the capture line looks familiar but behaves strictly:

	Bash `output=$(...)`	OxDock `LET $out: STRING = ...`
Trailing newlines	Stripped (all of them)	Preserved byte-exact
Variable type	Always an untyped string	Declared: STRING, INT, FLOAT, …
Math on output	Implicit: `$((var + 1))`	Explicit: `INT($out) + 1`
Failing command	Continues with empty output unless `set -e`	Step fails immediately, binds nothing

LET $out: TYPE = AWAIT $var binds the background task’s explicit RETURN value instead (tasks stream their stdout live, so there is no output left to capture); a task that succeeded without RETURN yields INT 0, like a process exit status.

An inline block (LET $var: TYPE = { <commands> }) runs its steps in a fresh scope and binds the nearest RETURN value, like a zero-arg function body: fallthrough without RETURN binds "", and BREAK/CONTINUE escaping the block are errors. The block reads outer variables but its own LETs never leak out. A {k: v} shape still parses as a map literal; anything else in braces is a block.

The split is deliberate: synchronous commands capture stdout because they run inline to completion on the same thread; background tasks never capture stdout because concurrent output has no well-defined value. Task results travel only through RETURN (or INT 0 for void tasks).

LET $e: STRING = env:FOO reads the script environment into a plain string.

Examples:

Example: let

LET $name: STRING = "world"
ECHO "hello, {{ $name }}"
ASSERT_CONTAINS stdout "hello, world"

LET $items: LIST<STRING> = ["a", "b"]
ASSERT_CONTAINS $items "a"
ASSERT_CONTAINS $items "b"

LET $count: INT = 42
ASSERT_EQ $count 42

Example: no hoisting

# Reading before the LET runs is an error, not an empty value.
ECHO $too_early
LET $too_early: STRING = "too late"

Expected error: undefined variable

Example: glob binding

# The RHS is an expression: GLOB(...) runs and binds a list.
IMPORT [STD]
WRITE a.txt "x"
LET $files: LIST<STRING> = GLOB("*.txt")
FOR $f: STRING IN $files { ECHO $f }

ASSERT_CONTAINS stdout "a.txt"

Example: scoped variable reverts

# LET inside a braced block reverts when the block exits.
LET $a: STRING = "outer"

[bool:true] {
    LET $a: STRING = "inner"
    WRITE inner.txt "{{ $a }}"
}

WRITE outer.txt "{{ $a }}"

LET $in_body: STRING = READ inner.txt
ASSERT_EQ $in_body "inner"

LET $out_body: STRING = READ outer.txt
ASSERT_EQ $out_body "outer"

Example: capture command output

# Capture keeps the trailing newline.
LET $out: STRING = ECHO hi
ASSERT_EQ $out "hi\n"

Example: inline block

LET $who: STRING = "ada"

# An inline block binds its RETURN value like a function body.
LET $res: STRING = {
    LET $loud: STRING = "{{ $who }}!"
    RETURN $loud
}
ASSERT_EQ $res "ada!"

# Any declared type works: the block value checks like any RHS.
LET $n: INT = {
    RETURN 40 + 2
}
ASSERT_EQ $n 42

Example: arithmetic over captured output

# Captured output converts explicitly: INT() then arithmetic.
IMPORT [STD]
LET $size_str: STRING = ECHO 41
LET $total: INT = INT($size_str) + 1
ASSERT_EQ $total 42

# FLOAT() promotes instead of truncating.
LET $ratio: FLOAT = 1 + 2.5
ASSERT_EQ $ratio 3.5

# Int x Int stays INT: integer division truncates.
LET $half: INT = 7 / 2
ASSERT_EQ $half 3

Example: float equality is exact

# Binary fractions compare cleanly; decimal fractions may not:
# 0.1 + 0.2 is 0.30000000000000004, so == is false.
IMPORT [STD]
LET $exact: BOOL = 0.5 + 0.25 == 0.75
LET $decimal: BOOL = 0.1 + 0.2 == 0.3
IF $exact {
    WRITE exact.txt yes
}
IF $decimal {
    WRITE unexpected.txt no
}

LET $ok: STRING = READ exact.txt
ASSERT_EQ $ok "yes"

LET $t: STRING = PATH_TYPE("unexpected.txt")
ASSERT_EQ $t "absent"

Example: bound inexact decimals

# Never test inexact decimals for equality; bound them.
LET $sum: FLOAT = 0.1 + 0.2
IF $sum > 0.299999 && $sum < 0.300001 {
    WRITE bounded.txt yes
}

LET $ok: STRING = READ bounded.txt
ASSERT_EQ $ok "yes"

Example: inspect a variable

# INSPECT($var) snapshots a variable into a MAP: declared
# type plus live details (pipe backend stats here), so
# scripts can branch on engine state.
IMPORT [STD]
LET $p: PIPE
WITH_IO [stdout=$p] ECHO hello
LET $info: MAP<ANY> = INSPECT($p)
IF $info.is_os_pipe {
    WRITE unexpected.txt "should be a script pipe"
}

ASSERT_EQ $info.type "PIPE"
LET $t: STRING = PATH_TYPE("unexpected.txt")
ASSERT_EQ $t "absent"

§MUTATION

Mutate a declared variable.

Syntax: $var = <expr>

Reassigns an existing variable, converting the new value to the type declared at LET time. The explicit annotation is what authorizes string-to-number conversion here ($n = "42" binds 42 for an INT); a non-numeric string is an error. Expressions never convert: "100" + 1 is a Type Error, use INT() / FLOAT() to cross that boundary explicitly.

The leading $ distinguishes mutation from KEY=value command assignments. Assigning an undeclared variable or a mismatched type is an error.

Mutation writes through to the scope where the variable was declared, so it survives block exit: LET $x outside a block followed by $x = ... inside still reads back the new value afterwards, for every type. This is the counterpart to LET shadowing, where LET $x inside the block declares a separate inner variable that reverts on exit.

Reassignment rebinds the variable to a new value: values captured earlier keep the old word (see the rebinding example below).

Examples:

Example: mutate

# Mutation writes through: the binding holds the new value.
LET $count: INT = 1
$count = 2
ASSERT_EQ $count 2

Example: rebind keeps earlier captures

# Reassignment rebinds: a map built from `$s` still
# reads the original string after `$s` moves on.
LET $s: STRING = "test"
LET $m: MAP<ANY> = {a: $s}
$s = "changed"
ASSERT_EQ $m.a "test"

# Appending to one list binding never touches its clones.
LET $a: LIST<STRING> = ["1"]
LET $b: LIST<STRING> = $a
LIST_APPEND $a "2"
LET $want: LIST<STRING> = ["1"]
ASSERT_EQ $b $want

Example: convert before math

# Captured output is a string: `"100" + 1` is a Type Error.
# Convert explicitly, then mutate with arithmetic.
IMPORT [STD]
LET $raw: STRING = ECHO 100
LET $n: INT = INT($raw)
$n = $n + 1

# The declared type also converts plain strings on assignment.
$n = "42"
ASSERT_EQ $n 42

# Same crossing for decimals via FLOAT().
LET $frac_str: STRING = ECHO 2.5
LET $f: FLOAT = FLOAT($frac_str) + 0.25
ASSERT_EQ $f 2.75

§ASYNC

Run steps in a background thread.

Syntax: ASYNC <command...> | ASYNC { <commands> } | LET $var: HANDLE = ASYNC { <commands> }

Runs a command or block of commands in a background thread with subshell isolation.

Mutations (ENV, WORKDIR) stay within the block. With LET, stores a task handle for AWAIT. Task output streams live to the parent stdout; a task publishes a value with an explicit RETURN, which LET $out: TYPE = AWAIT $task binds.

WITH_IO must wrap ASYNC from the outside (LET $p: PIPE first, then WITH_IO [stdout=$p] ASYNC ...) so pipe endpoints allocate on the main thread before the worker spawns. Placing WITH_IO directly inside ASYNC is rejected at parse time.

Examples:

Example: async

# Inline and block forms both run in the background; AWAIT joins them.
ASYNC ECHO "warming-up"
LET $a: HANDLE = ASYNC ECHO "first"
LET $b: HANDLE = ASYNC {
    ECHO "second"
}
AWAIT $a
AWAIT $b
ASSERT_CONTAINS stdout "first"
ASSERT_CONTAINS stdout "second"

Example: async task handle

LET $task: HANDLE = ASYNC {
    ECHO "built"
}
AWAIT $task
ASSERT_CONTAINS stdout "built"

§AWAIT

Join a background task.

Syntax: AWAIT $var | LET $out: STRING = AWAIT $var

Blocks until the named task completes. Propagates errors if the task failed.

Task output streams live during the run; joining binds nothing by itself. LET $out: TYPE = AWAIT $var binds the task’s explicit RETURN value instead, or INT 0 when the task succeeded without one (add RETURN <expr> to the task body to yield a value).

Examples:

Example: await

LET $task: HANDLE = ASYNC ECHO "done"
AWAIT $task
ASSERT_CONTAINS stdout "done"

Example: await capture

LET $task: HANDLE = ASYNC {
    ECHO "logged"
    RETURN "returned"
}

# AWAIT binds the RETURN value, not the streamed output.
LET $out: STRING = AWAIT $task
ASSERT_EQ $out "returned"

§CANCEL

Synchronously cancel a background task.

Syntax: CANCEL $var

Kills the named background task spawned via LET $var: HANDLE = ASYNC ….

Blocking: returns only after the task thread has been joined and its OS process reaped, so no residual filesystem or stream mutation follows. A later AWAIT $var reports cancellation. Only named tasks can be cancelled.

Examples:

Example: cancel

LET $task: HANDLE = ASYNC SLEEP 30s
CANCEL $task

Example: await after cancel reports cancellation

# A cancelled task stays cancelled: joining it reports.
LET $task: HANDLE = ASYNC SLEEP 30s
CANCEL $task
AWAIT $task

Expected error: was cancelled

§TIMEOUT

Enforce an execution deadline.

Syntax: TIMEOUT <duration> <command...> | TIMEOUT <duration> { <commands> } | TIMEOUT <duration> AWAIT $var

Aborts the wrapped step or block with a deadline error if it exceeds the duration (e.g. 500ms, 10s, 2m; a bare number means seconds).

A blocking foreground process is killed.

ASYNC composes in either nesting order with order-dependent deadline semantics: LET $task: HANDLE = ASYNC TIMEOUT 30s RUN "build" enforces the deadline inside the background thread (a later AWAIT $task surfaces the TIMEOUT error), while TIMEOUT 30s AWAIT $task preempts a hung task from the awaiting side.

Examples:

Example: timeout

TIMEOUT 30s WRITE heartbeat.txt alive
LET $beat: STRING = READ heartbeat.txt
ASSERT_EQ $beat "alive"

Example: timeout block

TIMEOUT 30s {
    WRITE a.txt one
    WRITE b.txt two
}
LET $a: STRING = READ a.txt
LET $b: STRING = READ b.txt
ASSERT_EQ $a "one"
ASSERT_EQ $b "two"

Example: deadline aborts the step

# 50ms expires long before the sleep does: the step dies
# with a deadline error instead of running out the clock.
TIMEOUT 50ms SLEEP 30s

Expected error: TIMEOUT after

Example: timeout variable duration

# Durations resolve at runtime, so variables work too.
LET $budget: DURATION = "30s"
TIMEOUT $budget WRITE heartbeat.txt alive

LET $beat: STRING = READ heartbeat.txt
ASSERT_EQ $beat "alive"

Example: timeout await

# AWAIT form bounds a task join instead of a step.
LET $quick: HANDLE = ASYNC {
    ECHO hi
}
TIMEOUT 30s AWAIT $quick

§REMOTE

Run a sealed block on a remote target.

Syntax: REMOTE <target> [[$var, ...] [env:NAME, ...]] { <commands> }

Runs the braced block on the named remote target, which the host binds at startup (--remote). The block is sealed: only header-listed $var and env:NAME entries cross, the guest starts empty, and results return through declared transfers or WITH_IO pipes. The target is a static literal, never a variable. Unknown targets fail before execution starts. Bodies check twice: the host static pass validates the body before anything ships, and the guest re-validates on arrival through the same entry point, so a body type error fails locally, never mid-run on the remote. A failing guest fails the host step: EXIT in the body exits the guest, and the host relays the code to its own process exit status (see EXIT).

Examples:

Example: sealed header values cross, outer scope does not

# Only header-listed names arrive: `$version` is visible
# on the guest, `$secret` was never sent.
LET $version: STRING = "1.2.3"
LET $secret: STRING = "host-only"
REMOTE prod [$version] {
    WRITE version.txt "{{ $version }}"
    COPY --to-host ./version.txt back.txt
}

# The pushed file proves the guest saw the injected value.
LET $back: STRING = READ back.txt
ASSERT_EQ $back "1.2.3"

Example: background tasks stream through shared pipes

# Two background REMOTEs share one capture pipe while a
# WITH_IO block holds the write end open.
IMPORT [STD]
LET $cap: PIPE
WITH_IO [stdout=$cap] {
    LET $a: HANDLE = ASYNC REMOTE prod {
        ECHO "from-a"
    }
    LET $b: HANDLE = ASYNC REMOTE prod {
        ECHO "from-b"
    }
    AWAIT $a
    AWAIT $b
}

# EOF ends the drain: no sentinel line, no baked-in count.
LET $n: INT = 0
WHILE !EOF($cap) {
    WITH_IO [stdin=$cap] READ_LINE $line
    $n = $n + 1
}
ASSERT_EQ $n 2

Example: declared files cross both directions

# Fetches ride in, pushes ride back. Anything undeclared
# never leaves its side.
WRITE send.txt "payload"
REMOTE prod {
    COPY --from-host ./send.txt got.txt
    LET $v: STRING = READ got.txt
    ASSERT_EQ $v "payload"
    WRITE back.txt "returned"
    COPY --to-host ./back.txt back.txt
}

# The push landed on the host; guest staging is gone.
LET $b: STRING = READ back.txt
ASSERT_EQ $b "returned"

Example: guest workspace selection stays on the guest

# WORKSPACE switches inside the block resolve against the
# guest staging dir, which serves as both the SNAPSHOT
# root and the LOCAL build context. The host selection
# restores when the block exits.
REMOTE prod {
    WORKSPACE SNAPSHOT
    WRITE out.txt "from-snapshot"
    COPY --to-host ./out.txt snap.txt
}

LET $s: STRING = READ snap.txt
ASSERT_EQ $s "from-snapshot"

Example: guest cache persists across execs

# WORKSPACE CACHE addresses guest-local persistent
# storage: the second block reads what the first wrote,
# while the guest staging starts empty every time.
REMOTE prod {
    WORKSPACE CACHE
    WRITE marker.txt "run-marker"
}
REMOTE prod {
    WORKSPACE CACHE
    LET $m: STRING = READ marker.txt
    ASSERT_EQ $m "run-marker"
}

Example: pushes outside staging fail closed

# WORKSPACE SYSTEM exposes the whole guest machine, but
# transfers stay staging scoped: a push source outside
# staging fails loudly instead of crossing.
REMOTE prod {
    WORKSPACE SYSTEM
    COPY --to-host /no/such/file.txt got.txt
}

Expected error: escapes staging

Example: guest exit fails the step, host survives

# EXIT in the body exits the guest with code 3. The
# host is unaffected: it keeps executing after the
# guest is already dead, and the failure surfaces as
# a host step error carrying the same code. The CLI
# then exits with it, so the guest code reaches the OS.
LET $t: HANDLE = ASYNC REMOTE prod {
    EXIT 3
}
WRITE host-alive.txt "still here"
AWAIT $t

Expected error: REMOTE 'prod' exited with code 3

Example: remote block without a runner

# Without a bound session, the block bails instead of
# executing anywhere unexpected.
REMOTE prod {
    ECHO "do something on remote"
}

Expected error: has no registered session

§FUNC

Define a user function.

Syntax: FUNC NAME([$param: TYPE, ...]) { <commands> }

Defines a user function with UPPERCASE name and explicitly typed parameters.

Params bind by position, converting each argument to its declared parameter type before the body runs. Bodies run in a fresh variable scope; LETs inside do not leak. A nested FUNC definition is scoped to its block and reverts on exit. Names share one namespace with native and host-registered functions, which a FUNC may never shadow.

Functions resolve like variables: a name is visible from its definition line, so recursion works but mutual recursion does not (the second name does not exist while the first body lowers). Calls name their module (STD::GLOB(...)) unless imported; see IMPORT.

Invoke any function with one syntax: NAME(...) as a statement (discarding the value) or LET $var: TYPE = NAME(...) to capture the RETURN value (fallthrough without RETURN captures as “”).

Examples:

Example: func def call

FUNC GREET($name: STRING) {
  RETURN $name
}

LET $res: STRING = GREET("ada")
ASSERT_EQ $res "ada"

# Statement form: parens stay, the value drops.
GREET("bex")

Example: call with pipes

# A pipe handle travels into a function as a typed argument
# and is usable as a binding target in both directions.
# `LET $p: PIPE` mints the handle; `$p` passes it on.
FUNC DRAIN($q: PIPE) {
  WITH_IO [stdin=$q] READ_LINE $line
  RETURN $line
}

LET $p: PIPE
WITH_IO [stdout=$p] ECHO "payload"

LET $got: STRING = DRAIN($p)
ASSERT_EQ $got "payload"

§RETURN

Return a value from a function, task, or inline block.

Syntax: RETURN [<expr>]

Ends the nearest enclosing boundary with a value: a function call, an ASYNC task (bound by LET $o = AWAIT $t), or an inline LET block. Bare RETURN with no expression yields "".

Falling off the end without RETURN yields “”. RETURN with no enclosing boundary (including at top level) is an error; use EXIT or ECHO there.

Examples:

Example: return

FUNC PICK($flag: BOOL) {
  IF $flag {
    RETURN "yes"
  }
  RETURN "no"
}

LET $res: STRING = PICK(true)
ASSERT_EQ $res "yes"

# Fallthrough without RETURN yields its own value.
LET $no: STRING = PICK(false)
ASSERT_EQ $no "no"

§WHILE

Loop while a condition holds.

Syntax: WHILE <bool-expr> { <commands> }

Re-evaluates a Bool condition each iteration (same is_truthy rule as IF; non-Bool is a type error).

Each iteration runs in a fresh scope; mutate outer state with $var = … so the next check observes it. BREAK exits the loop; CONTINUE skips to the next check.

Examples:

Example: while loop

# The condition re-evaluates every iteration: three passes, then stop.
LET $n: INT = 0
WHILE $n < 3 {
  WRITE tick.txt "{{ $n }}"
  $n = $n + 1
}

ASSERT_EQ $n 3
LET $tick: STRING = READ tick.txt
ASSERT_EQ $tick "2"

§BREAK

Exit the innermost loop.

Syntax: BREAK

Exits the innermost enclosing FOR or WHILE loop.

BREAK outside a loop, or across a FUNC or ASYNC boundary, is an error.

Examples:

Example: break

# BREAK leaves after the first pass: only "a" is written.
FOR $x: STRING IN ["a", "b"] {
  WRITE picked.txt "{{ $x }}"
  BREAK
}

LET $body: STRING = READ picked.txt
ASSERT_EQ $body "a"

§CONTINUE

Skip to the next loop iteration.

Syntax: CONTINUE

Skips the rest of the innermost enclosing FOR or WHILE body and starts the next iteration.

CONTINUE outside a loop, or across a FUNC or ASYNC boundary, is an error.

Examples:

Example: continue

# CONTINUE skips the write on "a": only "b" lands.
FOR $x: STRING IN ["a", "b"] {
  IF $x == "a" {
    CONTINUE
  }
  WRITE picked.txt "{{ $x }}"
}

LET $body: STRING = READ picked.txt
ASSERT_EQ $body "b"

§IMPORT

Bring module functions into bare-call scope.

Syntax: IMPORT [<module>, ...] | IMPORT <module>

Every function call names its module (STD::GLOB(...), MOCK::READ_CSV(...)) unless the module is imported: IMPORT [STD] lets the rest of the scope call GLOB(...) bare. Calls resolve at parse time against SCRIPT definitions first, then imported modules; unknown modules, unknown functions, and unimported bare calls are parse errors, never runtime surprises.

IMPORT is a lowering directive, not a step: it applies from its line to the enclosing block exit, then reverts, exactly like LET scoping but with no runtime footprint. Guards do not apply to it. Two imported modules exporting one name is an ambiguity error: qualify the call instead.

EXPORT is reserved for future script-module support and cannot be used yet.

Examples:

Example: import

# Calls name their module (STD::GLOB); IMPORT [STD] drops the prefix.
WRITE a.txt "hi \{{ env:WHO }}!"
IMPORT [STD]
FOR $x: STRING IN GLOB("*.txt") { EXPAND $x WHO=World }
ASSERT_CONTAINS stdout "hi World!"

§WORKDIR

Change the working directory.

Syntax: WORKDIR <path>

Sets the current working directory.

Relative paths resolve against the current directory; / resets to the workspace root. Paths cannot escape the workspace.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	yes	Directory to change to

Examples:

Example: change working directory

# Later relative paths resolve under the new directory.
WORKDIR project/src
WRITE generated.txt generated-under-workdir

LET $body: STRING = READ generated.txt
ASSERT_EQ $body "generated-under-workdir"

Example: workdir in a scoped block

# The block reverts to the starting directory on exit.
LET $outside: STRING = CWD
MKDIR project

[bool:true] {
    WORKDIR project
    WRITE inner.txt inner
}

LET $back: STRING = CWD
ASSERT_EQ $back $outside
LET $body: STRING = READ project/inner.txt
ASSERT_EQ $body "inner"

§WORKSPACE

Switch workspace roots.

Syntax: WORKSPACE (SNAPSHOT|LOCAL|CACHE|SYSTEM) [--local]

Switches the workspace root. The selection reverts at scope exit like WORKDIR.

SNAPSHOT: the materialized build snapshot (the default).
LOCAL: the local workspace directory.
CACHE: a persistent per-project directory shared across runs, never evicted. It lives under the OS user cache (OXDOCK_CACHE_DIR pins an exact directory); WORKSPACE CACHE --local keeps it in <project>/.cache/workspace instead.
SYSTEM: full filesystem access. Scripts using it are not hermetic.

Arguments:

Name	Type	Required	Description
`target`	`SNAPSHOT\|LOCAL\|CACHE\|SYSTEM`	yes	Target root

Flags:

Flag	Type	Description
`--local`	`BOOL`	Use the project-local cache directory instead of the OS user cache (CACHE only)

Examples:

Example: switch roots

IMPORT [STD]
WORKSPACE LOCAL

LET $t: STRING = PATH_TYPE(".")
ASSERT_EQ $t "dir"

Example: workspace cache in a scoped block

[bool:true] {
    WORKSPACE CACHE
    WRITE cached.txt cached-content
}

COPY --from-workspace CACHE cached.txt restored.txt
LET $body: STRING = READ restored.txt
ASSERT_EQ $body "cached-content"

§ENV

Set an environment variable.

Syntax: ENV KEY=value

Inserts or updates an env var.

The value uses the unified string-value rules shared by every command: "..." or '...' quotes keep exact bytes (spaces, tabs), a lone $var evaluates that variable, {{ ... }} placeholders interpolate, unquoted words join with single spaces, and the first = splits key from value (KEY=a=b stores a=b).

A $var inside larger text stays literal — write {{ $var }} to interpolate there.

Arguments:

Name	Type	Required	Description
`assignment`	`STRING`	yes	KEY=value pair; the value resolves as STRING

Examples:

Example: set env

ENV APP_MODE=production
LET $mode: STRING = env:APP_MODE
ASSERT_EQ $mode "production"

Example: quoted value with spaces

# Quotes keep the space: SET_FORTH stores `outer scope`.
ENV SET_FORTH="outer scope"
WRITE out.txt "{{ env:SET_FORTH }}"

LET $body: STRING = READ out.txt
ASSERT_EQ $body "outer scope"

Example: variable value

# A lone $var evaluates, like ECHO $var.
LET $who: STRING = "Alice"
ENV GREETING=$who
WRITE out.txt "{{ env:GREETING }}"

LET $body: STRING = READ out.txt
ASSERT_EQ $body "Alice"

Example: all value forms agree

# A bare variable, a quoted literal, and a template all
# store plain strings through the same value rules.
LET $x: STRING = "Ada"
ENV A=$x
ENV B="hello world"
ENV C="{{ $x }} concatenated"
WRITE check.txt "{{ env:A }}|{{ env:B }}|{{ env:C }}"

LET $body: STRING = READ check.txt
ASSERT_EQ $body "Ada|hello world|Ada concatenated"

Example: scoped env reverts

# ENV inside a braced block reverts when the block exits
ENV MODE=production

[bool:true] {
    ENV MODE=staging
    WRITE inner.txt "{{ env:MODE }}"
}

WRITE outer.txt "{{ env:MODE }}"

LET $inner_body: STRING = READ inner.txt
ASSERT_EQ $inner_body "staging"

LET $outer_body: STRING = READ outer.txt
ASSERT_EQ $outer_body "production"

Example: shell reads env per platform

# A shell command reads its own environment, with
# per-platform spelling: quoted "$VAR" passes the parser
# through untouched on Unix ...
ENV PROXY_PORT=23791

[family:unix] LET $o: STRING = RUN echo serving on "$PROXY_PORT"

# ... while cmd expands %VAR% on Windows.
[family:windows] LET $o: STRING = RUN echo serving on %PROXY_PORT%

ASSERT_CONTAINS $o "23791"

§INHERIT_ENV

Inherit env vars from host.

Syntax: INHERIT_ENV [<key>, ...]

Declares which host environment variables to inherit into the script.

Must appear before any other commands and at most once. Without this directive, the script starts with an empty environment.

Arguments:

Name	Type	Required	Description
`keys`	`STRING...`	no	Host variables to inherit

Examples:

Example: inherit env

INHERIT_ENV [PATH, HOME]
LET $path: STRING = env:PATH
ASSERT_CONTAINS $path ":"

§ECHO

Print to stdout.

Syntax: ECHO <message>

Outputs message to stdout.

Arguments:

Name	Type	Required	Description
`message`	`STRING...`	yes	Text

Output: Stdout

Examples:

Example: echo

ECHO build-complete
ASSERT_CONTAINS stdout "build-complete"

Example: variables

# {{ }} interpolates inside text; a lone $var evaluates on its own.
LET $x: STRING = "World"
ECHO "braced:{{ $x }}"
ECHO $x
ASSERT_EQ stdout "braced:World\nWorld\n"

Example: interpolation

# `{{ env:KEY }}` reads the script environment; a bare name
# resolves a DSL variable instead. Unknown keys expand to
# empty with no host fallback.
ENV USER=OxDock
LET $WHO: STRING = "Ada"
ECHO "Hello {{ env:USER }}! Hi {{ WHO }}!{{ env:OXDOCK_DOC_NO_SUCH_KEY }}"
ASSERT_CONTAINS stdout "Hello OxDock! Hi Ada!"

§RUN

Execute shell command or direct executable.

Syntax: RUN <command...> | RUN ["exe", "arg", ...]

Shell form (RUN <command...>) runs the joined command string in the system shell ($SHELL -c / COMSPEC /C).

Exec form (RUN ["exe", "arg", ...]) spawns the executable directly with no shell, so there is no shell expansion, globbing, redirection, or pipes; use it for portable commands.

Guards and wrappers (ASYNC, TIMEOUT, WITH_IO, LET) apply to both forms.

Arguments:

Name	Type	Required	Description
`command`	`STRING...`	yes	Command

Examples:

Example: run

RUN echo hello

# Captured runs prove the output, not just the exit status.
LET $o: STRING = RUN echo hello
ASSERT_CONTAINS $o "hello"

Example: run exec form

# No shell: `>` stays a literal argument, so no file is created.
IMPORT [STD]
RUN ["cargo", "--version", ">", "x.txt"]
ASSERT_CONTAINS stdout "cargo"

LET $t: STRING = PATH_TYPE("x.txt")
ASSERT_EQ $t "absent"

§COPY

Copy file into workspace.

Syntax: COPY [--from-workspace SNAPSHOT|LOCAL|CACHE|SYSTEM] [--from-host | --to-host] <from> <to>

Copies from host (the source is never moved or modified). Docker destination semantics: a file copied onto a directory (an existing one, or a trailing-slash spell like out/) is duplicated inside it under its own basename; a directory source duplicates its contents into the destination; any other destination path is created holding the copied bytes.

Arguments:

Name	Type	Required	Description
`from`	`PATH`	yes	Source
`to`	`PATH`	yes	Dest

Flags:

Flag	Type	Description
`--from-workspace`	`STRING`	Copy from the given workspace root instead of the build context
`--from-host`	`BOOL`	Fetch from the host workspace into the guest (REMOTE bodies only)
`--to-host`	`BOOL`	Push from the guest workspace back to the host (REMOTE bodies only)

Examples:

Example: copy

# Copy to a new name, then read back.
WRITE src.txt content
COPY src.txt dst.txt

LET $body: STRING = READ dst.txt
ASSERT_EQ $body "content"

Example: copy from workspace

# Same name, different contents per root: only LOCAL has ws-content.
WRITE shared.txt from-snapshot
WORKSPACE LOCAL
WRITE shared.txt ws-content

WORKSPACE SNAPSHOT
COPY --from-workspace LOCAL shared.txt ws-copy.txt

LET $body: STRING = READ ws-copy.txt
ASSERT_EQ $body "ws-content"

§COPY_GIT

Copy from git revision.

Syntax: COPY_GIT [--include-dirty] <rev> <src> <dst>

Checkout and copy.

Arguments:

Name	Type	Required	Description
`rev`	`STRING`	yes	Rev
`src`	`PATH`	yes	Src
`dst`	`PATH`	yes	Dst

Flags:

Flag	Type	Description
`--include-dirty`	`BOOL`	Include dirty

Examples:

Example: git copy missing source errors

COPY_GIT HEAD src.txt dst.txt

Expected error: COPY source missing

§SYMLINK

Create symlink.

Syntax: SYMLINK [--from-workspace SNAPSHOT|LOCAL|CACHE|SYSTEM] <from> <to>

Creates symlink. A directory destination (existing, or a trailing-slash spell) receives the link under the source basename.

Arguments:

Name	Type	Required	Description
`from`	`PATH`	yes	Target
`to`	`PATH`	yes	Link

Flags:

Flag	Type	Description
`--from-workspace`	`STRING`	Symlink from the given workspace root instead of the build context

Examples:

Example: symlink

# A symlink reads like its target.
WRITE original.txt content
SYMLINK original.txt link.txt

LET $body: STRING = READ link.txt
ASSERT_EQ $body "content"

Example: symlink from workspace

# Same name, different contents per root: only LOCAL has ws-content.
WRITE shared.txt from-snapshot
WORKSPACE LOCAL
WRITE shared.txt ws-content

WORKSPACE SNAPSHOT
SYMLINK --from-workspace LOCAL shared.txt ws-link.txt

LET $body: STRING = READ ws-link.txt
ASSERT_EQ $body "ws-content"

§MKDIR

Create directory.

Syntax: MKDIR <path>

Creates dir with parents.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	yes	Dir path

Examples:

Example: mkdir

IMPORT [STD]
MKDIR deeply/nested/tree

LET $t: STRING = PATH_TYPE("deeply/nested/tree")
ASSERT_EQ $t "dir"

§INSTALL

Atomically install a verified binary as executable.

Syntax: INSTALL <source> <dest>

Stages the source as a temp file in the dest dir, sets executable mode, then renames into place.

Arguments:

Name	Type	Required	Description
`from`	`PATH`	yes	Source file
`to`	`PATH`	yes	Dest file

Examples:

Example: install

# Place a verified binary with executable mode.
IMPORT [STD]
WRITE src.bin payload
INSTALL src.bin dst-bin/tool

LET $t: STRING = PATH_TYPE("dst-bin/tool")
ASSERT_EQ $t "file"

§LS

List directory.

Syntax: LS [<path>]

Lists entries.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	no	Dir

Output: Stdout

Examples:

Example: ls

MKDIR inventory
WRITE inventory/a.txt a
LS inventory
ASSERT_CONTAINS stdout "a.txt"

§CWD

Print working directory.

Syntax: CWD

Outputs cwd.

Output: Stdout

Examples:

Example: cwd

CWD

# CWD tracks WORKDIR: the listing names the new directory.
MKDIR sub
WORKDIR sub
LET $c: STRING = CWD
ASSERT_CONTAINS $c "sub"

§READ

Read file to stdout.

Syntax: READ [<path>]

Outputs file contents.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	no	File

Output: Stdout

Examples:

Example: read

WRITE note.txt "hello"
READ note.txt

LET $body: STRING = READ note.txt
ASSERT_EQ $body "hello"

§READ_LINE

Read one line from stdin into a variable.

Syntax: READ_LINE $var

Reads bytes until newline without waiting for EOF, leaving the pipe open.

Trailing newline is stripped (shell-read parity). On premature EOF assigns accumulated bytes and returns.

Arguments:

Name	Type	Required	Description
`var`	`STRING`	yes	Target variable (`$name`); the line binds as STRING

Examples:

Example: read line

# The trailing newline is stripped: the variable holds exactly `first`.
LET $lines: PIPE
WITH_IO [stdout=$lines] ECHO "first"
WITH_IO [stdin=$lines] READ_LINE $reply
ASSERT_EQ $reply "first"

§PROMPT

Prompt on the terminal into a variable.

Syntax: PROMPT $var <message> [<default>]

Prints {message} [{default}]: (or {message}: with no default) to stderr and reads one line from the terminal.

Empty input yields the default when one is given, else an empty string. EOF aborts loudly. Non-TTY stdin never reads: a default binds with a stderr note, while no default bails.

Arguments:

Name	Type	Required	Description
`var`	`STRING`	yes	Target variable (`$name`); the answer binds as STRING
`message`	`STRING`	yes	Prompt message
`default`	`STRING`	no	Default on empty input

Examples:

Example: prompt needs a terminal

# Headless runs have no terminal: without a default the
# prompt fails instead of hanging or reading piped stdin.
PROMPT $dir "Install destination?"

Expected error: non-TTY

§WRITE

Write to file.

Syntax: WRITE <path> [<contents>]

Writes contents.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	yes	File
`contents`	`STRING...`	no	Content

Examples:

Example: write

WRITE output.txt hello-world
LET $body: STRING = READ output.txt
ASSERT_EQ $body "hello-world"

§APPEND

Append to file.

Syntax: APPEND <path> [<contents>]

Appends contents.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	yes	File
`contents`	`STRING...`	no	Content

Examples:

Example: append

WRITE log.txt line1
APPEND log.txt line2

# APPEND concatenates with no separator.
LET $all: STRING = READ log.txt
ASSERT_EQ $all "line1line2"

§REMOVE

Remove a file, symlink, or directory.

Syntax: REMOVE [--recursive] <path>

Removes a file, symlink (the link itself), or empty dir. With –recursive removes a directory tree.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	yes	Path to remove

Flags:

Flag	Type	Description
`--recursive`	`BOOL`	Remove a directory tree

Examples:

Example: remove

# WRITE then REMOVE leaves nothing behind.
IMPORT [STD]
WRITE scratch.txt content

# Assert original file is written
LET $o: STRING = PATH_TYPE("scratch.txt")
ASSERT_EQ $o "file"

REMOVE scratch.txt

# Assert file has been removed
LET $t: STRING = PATH_TYPE("scratch.txt")
ASSERT_EQ $t "absent"

§EXPAND

Expand a template file (or stdin) to stdout.

Syntax: EXPAND [<path>] [<KEY=val> ...]

A template is any text file — or piped stdin when no path is given — containing {{ ... }} placeholders. EXPAND replaces each placeholder and prints the result to stdout.

Placeholders: {{ NAME }} reads a KEY=val override passed on this command; {{ env:NAME }} reads an override, falling back to the environment; {{ $var }} reads a script variable (dotted paths allowed). A missing key is an error, never a silent empty.

Substitution runs in a single pass. EXPAND is not recursive and does not expand nested placeholders: a value that itself contains {{ ... }} is inserted verbatim and never expanded again.

A bare $var argument is a template path; KEY=val arguments are overrides whose values follow the unified string-value rules (same as ENV: quotes keep exact bytes, a lone $var evaluates, {{ ... }} interpolates).

NOTE: WRITE interpolates {{ ... }} while writing, so escape it (\{{ ... }}) when writing a template file for a later EXPAND.

With no path, the template arrives on stdin through a pipe. When piping from a shell, single-quote the template (echo '{{ $x }}'): double quotes let the shell swallow $x, so oxdock receives an empty {{ }} placeholder and errors.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	no	Template file to expand; omit to expand stdin
`overrides`	`STRING...`	no	Template overrides shadowing that key (unified string values)

Output: Stdout

Examples:

Example: expand

# Placeholders read overrides first, then the environment.
ENV NAME="Alice"
WRITE template.md "Hello {{ env:NAME }}!"
EXPAND template.md

ASSERT_CONTAINS stdout "Hello Alice!"

Example: override with spaces

# WRITE would interpolate {{ }} right away, so escape it.
# The file must literally contain {{ env:NAME }} for EXPAND.
WRITE template.md "Hello \{{ env:NAME }}!"
EXPAND template.md NAME="Alice Smith"

ASSERT_CONTAINS stdout "Hello Alice Smith!"

Example: variable override

# Same escaping: keep the placeholder literal until EXPAND.
# A lone $who evaluates, like ECHO $who.
LET $who: STRING = "Bob"
WRITE template.md "Hi \{{ env:WHO }}!"
EXPAND template.md WHO=$who

ASSERT_CONTAINS stdout "Hi Bob!"

Example: override forms agree

# A bare variable and a template-with-tail expand identically.
LET $x: STRING = "Ada"
WRITE template.md "Hi \{{ env:NAME }} and \{{ env:NAME2 }}!"
EXPAND template.md NAME=$x NAME2="{{ $x }} concatenated"

ASSERT_CONTAINS stdout "Hi Ada and Ada concatenated!"

Example: expand stdin

# No path: the template arrives on stdin through a pipe.
LET $tpl: PIPE
WITH_IO [stdout=$tpl] ECHO "Hello \{{ env:NAME }}!"
WITH_IO [stdin=$tpl] EXPAND NAME=Alice

ASSERT_CONTAINS stdout "Hello Alice!"

Example: override does not leak

# KEY=val overrides shadow env for that EXPAND only.
# They never update the environment itself.
ENV NAME="Alice"
WRITE template.md "Hi \{{ env:NAME }}!"

EXPAND template.md NAME="Bob"
ASSERT_CONTAINS stdout "Hi Bob!"

EXPAND template.md
ASSERT_CONTAINS stdout "Hi Alice!"

§ASSERT_EQ

Assert strict equality.

Syntax: ASSERT_EQ <actual> <expected> | ASSERT_EQ --hash <sha256> <actual>

Compares two evaluated values with typed equality (no coercion: INT(42) never equals STRING("42")), aborting the pipeline with a step-numbered error showing expected vs actual otherwise.

Both sides are values: $var, literals, templates, and calls evaluate in memory and never touch disk. Read files explicitly first (LET $text: STRING = READ "out.txt", then ASSERT_EQ $text ...). Bare stdout / stderr observe stream buffers; a $var holding a PIPE observes its backend bytes. --hash compares the SHA-256 of a string, pipe, or captured-stdout actual instead of the raw bytes (stderr is unsupported).

Arguments:

Name	Type	Required	Description
`actual`	`<any>`	yes	Value, stdout, stderr, or a $var holding a PIPE
`expected`	`<any>...`	no	Expected (required unless –hash)

Flags:

Flag	Type	Description
`--hash`	`STRING`	SHA-256

Examples:

Example: assert eq

LET $status: INT = 200
ASSERT_EQ $status 200

Example: assert eq file

WRITE payload.bin stable-content
LET $body: STRING = READ payload.bin
ASSERT_EQ $body "stable-content"

Example: assert eq hash

# --hash compares the SHA-256 digest instead of raw bytes.
WRITE payload.bin stable-content
LET $body: STRING = READ payload.bin
ASSERT_EQ --hash 08135c1b6349b0e4f894c36221952f0de00e6b4d82f80895abf359755e77103c $body

§ASSERT_CONTAINS

Assert containment.

Syntax: ASSERT_CONTAINS <haystack> <needle>

Checks containment and aborts the pipeline with a step-numbered error otherwise: substring for strings, element match for lists, key presence for maps, substring over stream and pipe buffers.

Like ASSERT_EQ, both sides are values read without implicit I/O; read files explicitly first (LET $text: STRING = READ "cfg.txt"). Bare stdout / stderr observe stream buffers; a $var holding a PIPE observes its backend bytes.

Arguments:

Name	Type	Required	Description
`haystack`	`<any>`	yes	Value, stdout, stderr, or a $var holding a PIPE
`needle`	`<any>...`	yes	Substring, element, or key

Examples:

Example: assert contains

ECHO build-complete
ASSERT_CONTAINS stdout "build-complete"

§HASH_SHA256

Print SHA-256.

Syntax: HASH_SHA256 <path>

Computes digest.

Arguments:

Name	Type	Required	Description
`path`	`PATH`	yes	File

Output: Stdout

Examples:

Example: hash

WRITE payload.txt hello
HASH_SHA256 payload.txt

LET $digest: STRING = HASH_SHA256 payload.txt
ASSERT_EQ $digest "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824\n"

§EXIT

Exit pipeline.

Syntax: EXIT <code>

Stops the pipeline immediately with an EXIT requested with code <code> error; steps after it never run, at any nesting depth.

Enclosing blocks still unwind their LET/ENV/WORKDIR/WORKSPACE state, anonymous background tasks are killed synchronously, and files written before the EXIT persist.

The code reaches the OS: the CLI exits with <code> clamped to 0..=255, and a guest EXIT relays through REMOTE the same way.

Arguments:

Name	Type	Required	Description
`code`	`INT`	yes	Code

Examples:

Example: exit

EXIT 0

Expected error: EXIT requested with code 0

§SLEEP

Pause execution for a duration.

Syntax: SLEEP <duration>

Parks the step for the duration (e.g. 500ms, 10s, 2m).

Cooperative: checks for cancellation so an enclosing TIMEOUT or task teardown interrupts the sleep. Cross-platform alternative to shell sleep for testing time boundaries.

Arguments:

Name	Type	Required	Description
`duration`	`DURATION`	yes	How long to sleep

Examples:

Example: sleep

SLEEP 100ms

Example: sleep variable duration

# Durations resolve at runtime, so variables work too:
# quoted or bare, both bind the same string.
LET $pause: STRING = "100ms"
SLEEP $pause

LET $bare: STRING = 100ms
SLEEP $bare

§LIST_APPEND

Append an item to a LIST variable in place.

Syntax: LIST_APPEND $list <item>

Appends the item to the LIST variable in place.

When the binding holds the only reference the push runs in amortized constant time. Aliased buffers detach first, so other holders keep their contents.

Arguments:

Name	Type	Required	Description
`list`	`LIST`	yes	Target LIST variable (`$name`)
`item`	`<any>`	yes	Item to append (any value)

Examples:

Example: list append

# Appends accumulate in order.
LET $items: LIST<STRING> = []
LIST_APPEND $items "first"
LIST_APPEND $items "second"

LET $want: LIST<STRING> = ["first", "second"]
ASSERT_EQ $items $want

§Value types

§Value type: INT

64-bit signed integer, e.g. an exit code.

§Value type: FLOAT

64-bit float, e.g. a ratio.

§Value type: STRING

Arbitrary text. Quotes keep exact bytes, lone $var evaluates, {{ ... }} interpolates.

§Value type: BOOL

Boolean true or false.

§Value type: LIST

Ordered list of values. Shared heap: cloning bumps a refcount.

§Value type: MAP

String-keyed map of values. Shared heap: cloning bumps a refcount.

§Value type: PATH

Workspace path, resolved against cwd and guarded against escape.

§Value type: DURATION

Positive time span: 500ms, 10s, 2m, 1h; bare number means seconds.

§Value type: PIPE

Anonymous pipe handle. The backend materializes lazily on first binding (never eagerly at declaration), so the choice always has full usage context. Cloning shares the backend (explicit-sharing fan-out); equality is handle identity, never byte comparison.

§Value type: HANDLE

Background ASYNC task handle for AWAIT/CANCEL.

§Value type: SEMAPHORE

Counting semaphore for admission control. Cloning shares the backend (explicit-sharing fan-out); equality is handle identity, never the count.

§Value type: PERMIT

Opaque admission permit minted by SEMAPHORE_TRY_ACQUIRE. Cloning shares the release obligation (first drops release nothing, the last releases once); equality is handle identity.

§Functions

Callable as MODULE::NAME(...) in expressions (or bare NAME(...) with the module imported via IMPORT). Introspectable from scripts with FUNCTIONS() and DESCRIBE(name).

§STD::BASE64_DECODE

Decode standard base64 to a STRING.

Fails naming the input on invalid alphabet characters or non-UTF-8 payloads instead of rendering a silent empty. Pairs with BASE64_ENCODE for the round trip.

# Decode standard base64 back to text.
IMPORT [STD]
LET $decoded: STRING = BASE64_DECODE("aGVsbG8=")
ASSERT_EQ $decoded "hello"

Signature: STD::BASE64_DECODE($text: STRING) -> STRING

Contexts: AST, RPN

Parameters:

$text (STRING): Base64 text to decode.

Returns: STRING

§STD::BASE64_ENCODE

Encode a STRING as standard base64.

Padded RFC 4648 alphabet, so encoded output pastes into any standard decoder. Pairs with BASE64_DECODE for the round trip.

# Encode text to standard base64.
IMPORT [STD]
LET $encoded: STRING = BASE64_ENCODE("hello")
ASSERT_EQ $encoded "aGVsbG8="

Signature: STD::BASE64_ENCODE($text: STRING) -> STRING

Contexts: AST, RPN

Parameters:

$text (STRING): Text to encode.

Returns: STRING

§STD::DESCRIBE

Describe one function by qualified name.

Signature: STD::DESCRIBE($name: STRING) -> MAP<name: STRING, module: STRING, kind: STRING, params: LIST<MAP<ANY>>, returns: STRING, rpn: BOOL, summary: STRING>

Contexts: AST only

Parameters:

$name (STRING): Qualified function name (MODULE::NAME).

Returns: MAP<name: STRING, module: STRING, kind: STRING, params: LIST<MAP<ANY>>, returns: STRING, rpn: BOOL, summary: STRING>

name (STRING): Qualified function name.
module (STRING): Owning module.
kind (STRING): Origin label (host or script).
params (LIST<MAP<ANY>>): Parameter entries (empty for parameterless functions).
returns (STRING): Structural return shape (empty when untagged).
rpn (BOOL): True when callable in RPN position.
summary (STRING): One-line description.

§STD::EOF

True when a pipe sits at end of stream: closed with nothing buffered, so the next READ_LINE would bind "" via EOF rather than a line. Live writers, pinned keepers, and buffered bytes all answer false. Never blocks: a reader already blocked stays blocked, so branch on EOF before reading, not after. OS pairs and unbound handles answer best-effort (kernel bytes are invisible there; see INSPECT). Non-pipe arguments bail at the boundary: the parameter declares PIPE, so the extractor and the static pass reject them before the body runs.

# Capture two lines, then drain to end of stream with no sentinel line.
IMPORT [STD]
LET $cap: PIPE
WITH_IO [stdout=$cap] {
    ECHO "one"
    ECHO "two"
}

# The loop exits on close, and the count proves both lines drained.
LET $n: INT = 0
WHILE !EOF($cap) {
    WITH_IO [stdin=$cap] READ_LINE $line
    $n = $n + 1
}
ASSERT_EQ $n 2

Signature: STD::EOF($pipe: PIPE) -> BOOL

Contexts: AST only

Parameters:

$pipe (PIPE): Pipe handle to query for end of stream.

Returns: BOOL

§STD::FLOAT

Convert a value to FLOAT.

Parses f64 (accepts int strings), bails on non-finite or non-numeric.

Signature: STD::FLOAT($val: ANY) -> FLOAT

Contexts: AST, RPN

Parameters:

$val (ANY): Value to convert to FLOAT.

Returns: FLOAT

§STD::FUNCTIONS

List all visible function names.

Sorted LIST of qualified MODULE::NAME entries: DSL-defined plus native plus host-registered names.

Signature: STD::FUNCTIONS() -> LIST<STRING>

Contexts: AST only

Returns: LIST<STRING>

§STD::GLOB

List workspace paths matching a glob pattern.

Sorted, root-relative LIST; empty on no match or .. escape.

Signature: STD::GLOB($pattern: STRING) -> LIST<STRING>

Contexts: AST, RPN

Parameters:

$pattern (STRING): Glob pattern matched against workspace paths.

Returns: LIST<STRING>

§STD::HAS_KEY

Report whether a map holds a key.

Pure MAP probe so scripts can branch on optional fields without tripping the strict missing-key error.

Signature: STD::HAS_KEY($map: MAP<ANY>, $key: STRING) -> BOOL

Contexts: AST, RPN

Parameters:

$map (MAP<ANY>): Map to probe.
$key (STRING): Key to look up.

Returns: BOOL

§STD::INT

Convert a value to INT.

Trims ASCII whitespace and parses i64. Passes Int through; Float only when integral and finite.

Signature: STD::INT($val: ANY) -> INT

Contexts: AST, RPN

Parameters:

$val (ANY): Value to convert to INT.

Returns: INT

§STD::IS_TERMINAL

Report whether a standard stream is a terminal.

IS_TERMINAL("stdin"), IS_TERMINAL("stdout"), or IS_TERMINAL("stderr") answers for the step’s stream as currently bound, so scripts can adapt prompts, colors, and progress output. Anything diverted from the terminal reports false without touching host handles: WITH_IO pipe bindings (script backends and OS pairs), LET-capture sinks, staged runner sinks, and any materialized stdin stream (only a directly inherited fd falls back to the process check). A transparent root tee still answers the session question via the process check. The name matches exactly (no case folding): anything else bails. AST-only: reads the step context like the other introspection functions.

Signature: STD::IS_TERMINAL($stream_name: STRING = "stdin" | "stdout" | "stderr") -> BOOL

Contexts: AST only

Parameters:

$stream_name (STRING = "stdin" | "stdout" | "stderr"): Stream name: stdin, stdout, or stderr (exact match).

Returns: BOOL

§STD::LOAD_JSON

Load and parse a JSON file.

Reads a workspace file and parses JSON into a DSL value. Returns ANY by design: a top-level array or scalar parses to LIST or a scalar word. LET coercion still checks the actual value at assignment.

Signature: STD::LOAD_JSON($path: STRING) -> ANY

Contexts: AST, RPN

Parameters:

$path (STRING): Workspace file path to load and parse as JSON.

Returns: ANY

§STD::LOAD_TOML

Load and parse a TOML file.

Reads a workspace file and parses TOML into a DSL value.

Signature: STD::LOAD_TOML($path: STRING) -> MAP<ANY>

Contexts: AST, RPN

Parameters:

$path (STRING): Workspace file path to load and parse as TOML.

Returns: MAP<ANY>

§STD::MAP_SET

Insert one key into a map.

Fails on duplicates so two entries sharing a key fail the run instead of silently shadowing each other.

Signature: STD::MAP_SET($map: MAP<ANY>, $key: STRING, $value: ANY) -> MAP<ANY>

Contexts: AST, RPN

Parameters:

$map (MAP<ANY>): Map to insert into.
$key (STRING): Key to insert; duplicates fail.
$value (ANY): Value to store.

Returns: MAP<ANY>

§STD::MERGE_MAPS

Merge a LIST of MAPs in order under one duplicate policy.

fail_on_duplicate fails naming the repeated key, so two files claiming one placeholder fail the run instead of shadowing each other. overwrite lets later files win, for environment overlays. Non MAP elements fail naming their position.

Signature: STD::MERGE_MAPS($maps: LIST<MAP<ANY>>, $policy: STRING = "fail_on_duplicate" | "overwrite") -> MAP<ANY>

Contexts: AST, RPN

Parameters:

$maps (LIST<MAP<ANY>>): LIST of MAPs to merge in order.
$policy (STRING = "fail_on_duplicate" | "overwrite"): Duplicate policy.

Returns: MAP<ANY>

§STD::PARSE_JSON

Parse JSON text already held in memory.

Uses the same conversion as file loading, so fetch bodies, file contents, and captured text share one JSON value shape. Returns ANY by design, matching LOAD_JSON: a top-level array or scalar parses to LIST or a scalar word. LET coercion still checks the actual value at assignment.

# Parse in-memory JSON text with the same conversion as file loading.
IMPORT [STD]
LET $body: STRING = "{\"a\": 1}"
LET $doc: ANY = PARSE_JSON($body)
ASSERT_EQ $doc.a 1

# Top-level arrays parse to LIST, which is why the return is ANY.
LET $items: LIST<ANY> = PARSE_JSON("[1, 2]")
ASSERT_EQ $items.0 1
ASSERT_EQ $items.1 2

Signature: STD::PARSE_JSON($text: STRING) -> ANY

Contexts: AST, RPN

Parameters:

$text (STRING): JSON text already held in memory.

Returns: ANY

§STD::PARSE_TOML

Parse TOML text already held in memory.

Uses the same conversion as file loading, so fetch bodies, file contents, and captured text share one JSON/TOML shape.

Signature: STD::PARSE_TOML($text: STRING) -> MAP<ANY>

Contexts: AST, RPN

Parameters:

$text (STRING): TOML text already held in memory.

Returns: MAP<ANY>

§STD::PATH_TYPE

Describe a filesystem entry.

Reports file, dir, symlink (no-follow), or absent. AST-only by design; there is no RPN arm for filesystem IO.

Signature: STD::PATH_TYPE($path: STRING) -> STRING

Contexts: AST only

Parameters:

$path (STRING): Workspace path of the entry to describe.

Returns: STRING

§STD::PATH_WRITABLE

Report whether an ordinary file can be created at a path.

Walks up to the nearest existing ancestor, requires it be a directory, and probes writability by creating and deleting a probe file, so retry loops never litter. The empty string is false. AST-only by design, like PATH_TYPE: there is no RPN arm for filesystem IO.

# An absent nested path is writable when its ancestor is.
IMPORT [STD]
LET $fresh: BOOL = PATH_WRITABLE("probe-check/nested/file.txt")
ASSERT_EQ $fresh true

# The empty string never aliases the working directory.
LET $empty: BOOL = PATH_WRITABLE("")
ASSERT_EQ $empty false

Signature: STD::PATH_WRITABLE($path: STRING) -> BOOL

Contexts: AST only

Parameters:

$path (STRING): Workspace path to probe for file creation.

Returns: BOOL

§STD::RAND

Draw a random FLOAT uniformly from [0, 1), optionally seeded. Impure by design: unseeded calls return different values, so this runs on the AST script path only, never as a {{ }} placeholder call. A seed draws the same value on every run, for deterministic fixtures. Scale and shift the draw for wider ranges. Hand-built (not #[oxdock_func]): the macro marks every param required, and only hand-built entries can leave a trailing options MAP omittable, so bare RAND() fills {}.

# Scale a unit draw into a backoff delay between 1 and 11 seconds.
IMPORT [STD]
LET $draw: FLOAT = RAND()
LET $delay: FLOAT = 1.0 + $draw * 10.0
IF $delay < 1.0 {
    EXIT 1
}
IF $delay >= 11.0 {
    EXIT 1
}
ECHO "retrying in {{ $delay }}s"

# A seed draws the same value on every run.
LET $one: FLOAT = RAND({seed: 7})
LET $two: FLOAT = RAND({seed: 7})
ASSERT_EQ $one $two

Signature: STD::RAND($options?: MAP<seed?: INT>) -> FLOAT

Contexts: AST only

Parameters:

$options? (MAP<seed?: INT>): Draw settings: seed. Omittable: a missing options MAP fills {}.
- seed (INT, optional)

Returns: FLOAT

§STD::SEMAPHORE_AVAILABLE

Read free permits under the lock, with no mutation.

Observability only (audit lines, healthchecks: active = max - free). Exact at read time and stale the instant the caller acts on it, so it must never drive admission: that is SEMAPHORE_TRY_ACQUIRE’s job.

# Hold one permit on a cap of two.
IMPORT [STD]
LET $sem: SEMAPHORE = SEMAPHORE_NEW(2)
LET $acq: MAP<held: BOOL, permit?: PERMIT> = SEMAPHORE_TRY_ACQUIRE($sem)
ASSERT_EQ $acq.held true

# One held permit leaves exactly one free.
LET $free: INT = SEMAPHORE_AVAILABLE($sem)
ASSERT_EQ $free 1

Signature: STD::SEMAPHORE_AVAILABLE($sem: SEMAPHORE) -> INT

Contexts: AST, RPN

Parameters:

$sem (SEMAPHORE): Semaphore handle from SEMAPHORE_NEW.

Returns: INT

§STD::SEMAPHORE_NEW

Create a counting semaphore admitting at most max concurrent holders.

Non-positive maxima bail. The word names a shared backend: every clone observes the same count, and admission runs through SEMAPHORE_TRY_ACQUIRE, never through the SEMAPHORE_AVAILABLE readout.

# Mint a semaphore admitting at most two holders.
IMPORT [STD]
LET $sem: SEMAPHORE = SEMAPHORE_NEW(2)

# A fresh semaphore reports its full cap as available.
LET $free: INT = SEMAPHORE_AVAILABLE($sem)
ASSERT_EQ $free 2

Signature: STD::SEMAPHORE_NEW($max: INT) -> SEMAPHORE

Contexts: AST only

Parameters:

$max (INT): Maximum concurrent holders; must be positive.

Returns: SEMAPHORE

§STD::SEMAPHORE_TRY_ACQUIRE

Attempt one non-blocking acquire, always answering a MAP.

held is true with the permit under the permit key, or false with no permit key: branch on $m.held directly. The DSL has no null, so the absent key is the miss shape. Do not read $m.permit unless held: missing-key access bails strictly. Never waits, so no wait can wedge.

# First acquire holds with a permit to bind.
IMPORT [STD]
LET $sem: SEMAPHORE = SEMAPHORE_NEW(1)
LET $first: MAP<held: BOOL, permit?: PERMIT> = SEMAPHORE_TRY_ACQUIRE($sem)
ASSERT_EQ $first.held true
LET $permit: PERMIT = $first.permit

# A capped semaphore answers held false with no permit key.
LET $second: MAP<held: BOOL, permit?: PERMIT> = SEMAPHORE_TRY_ACQUIRE($sem)
ASSERT_EQ $second.held false
LET $has_permit: BOOL = HAS_KEY($second, "permit")
ASSERT_EQ $has_permit false

Signature: STD::SEMAPHORE_TRY_ACQUIRE($sem: SEMAPHORE) -> MAP<held: BOOL, permit?: PERMIT>

Contexts: AST only

Parameters:

$sem (SEMAPHORE): Semaphore handle from SEMAPHORE_NEW.

Returns: MAP<held: BOOL, permit?: PERMIT>

held (BOOL): true with the permit under permit, false with no permit key.
permit (PERMIT, optional): Permit handle; read only when held.

§STD::TO_JSON

Encode a script value as JSON with one trailing newline.

Maps stay sorted; only template-safe shapes (STRING, INT, FLOAT, BOOL, LIST, MAP) survive, anything else fails here instead of rendering as a silent empty.

Signature: STD::TO_JSON($value: ANY) -> STRING

Contexts: AST, RPN

Parameters:

$value (ANY): Value to encode as JSON.

Returns: STRING

§STD::TYPES

List all known type names.

Sorted LIST of startup plus host-registered type descriptors. Reads the run’s name directory, so it runs on the AST path like the other introspection functions.

Signature: STD::TYPES() -> LIST<STRING>

Contexts: AST only

Returns: LIST<STRING>

§STD::TYPE_DESCRIBE

Describe one type by name.

Returns a MAP with name, summary, and docs. Errors on unknown type. Reads the run’s name directory, so it runs on the AST path.

Signature: STD::TYPE_DESCRIBE($name: STRING) -> MAP<name: STRING, summary: STRING, docs: STRING>

Contexts: AST only

Parameters:

$name (STRING): Type name to describe.

Returns: MAP<name: STRING, summary: STRING, docs: STRING>

name (STRING): Queried type name.
summary (STRING): One-line description.
docs (STRING): Full documentation text.

§STD::TYPE_OF

Name the word a value holds, for data-driven branching.

Returns the registered type word (STRING, INT, FLOAT, BOOL, LIST, MAP, plus handle words like PIPE): the same name the value prints in arity and coercion errors, so scripts can branch on config shapes (a path string or a path list) without failing.

Signature: STD::TYPE_OF($value: ANY) -> STRING

Contexts: AST, RPN

Parameters:

$value (ANY): Value whose word to name.

Returns: STRING

§Contexts

Every function lists the contexts it runs in. AST is always available. RPN additionally requires a pure function or an explicit rpn opt in.

§Context: AST

The parsed tree of a script, walked one step at a time. Statements, declarations, scopes, pipes, and IO live here. Every step knows its line number, so failures name it. Every function runs in this context.

§Context: RPN

Arithmetic and comparison expressions compiled to a flat stack program of values with no statements, scopes, pipes, or step numbers. Pure functions run here with no flag. Stateful functions run here only when they opt in with #[oxdock_func(rpn)], which is reserved for read only queries that stay meaningful inside math (GLOB, LOAD_TOML, LOAD_JSON do this). A call that fails inside math reports the bare error with no step number.

Re-exports§

pub use command::ArgSpec;
pub use command::ArgType;
pub use command::CommandMeta;
pub use command::CommandSpec;
pub use command::Example;
pub use command::FlagSpec;
pub use command::FlagValueType;
pub use command::IoDirection;
pub use command::Stream;
pub use commands::all_metadata;
pub use commands::all_structural_metadata;
pub use commands::lower_command;
pub use error::ParseError;
pub use error::ParseErrorKind;
pub use error::ParseResult;
pub use error::SpanContext;
pub use literal::escape_dsl_string;
pub use literal::render_dsl_literal;
pub use literal::render_quoted;
pub use markdown::BlockMetadata;
pub use markdown::FencedBlock;
pub use markdown::expect_error_from_info;
pub use markdown::extract_fenced_blocks;
pub use parser::parse_expression_str;
pub use parser::parse_guard_expr_str;
pub use parser::parse_script;
pub use parser::parse_script_with_modules;
pub use parser::parse_script_with_preseed;
pub use strip_flags::strip_flags;
pub use tag::ANY_TAG;
pub use tag::Field;
pub use tag::LIST_TAG;
pub use tag::MAP_TAG;
pub use tag::MAX_GENERIC_DEPTH;
pub use tag::Spelled;
pub use tag::SpelledField;
pub use tag::TypeTag;
pub use tag::canonicalize_spelling;
pub use tag::check_value;
pub use tag::check_value_at;
pub use tag::intern_composed;
pub use tag::lookup_composed;
pub use tag::parse_spelling;
pub use tag::render_structural;
pub use ast::*;
pub use constants::*;

Modules§

ast
command
commands: Single-site command registry for all OxDock commands.
constants: Language-level constants: the module separator, system module names, and reserved keywords.
error: Typed parse errors for the OxDock DSL (issue #143).
literal: Render runtime values back to DSL source literals.
markdown
parser
strip_flags
tag: Static type tags for function metadata and variable bindings.
test_lower_mock: Shared mock lowering for parser tests. Centralizes AST lowering so unit tests, integration tests, and macro_input tests all exercise the same command set against the same grammar.
value: Value-word core: every DSL value is a fixed-size word (a TypeDescriptor vtable pointer plus a 64-bit ValuePayload) interpreted through that vtable.

Constants§

LANGUAGE_SPEC