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 declared in this crate.

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.

§Command Reference

Command	Syntax
`WORKDIR`	`WORKDIR <path>`
`WORKSPACE`	`WORKSPACE SNAPSHOT\|LOCAL`
`ENV`	`ENV KEY=value`
`INHERIT_ENV`	`INHERIT_ENV <key>...`
`ECHO`	`ECHO <message>`
`RUN`	`RUN <command...> \| RUN ["exe", "arg", ...]`
`COPY`	`COPY [--from-current-workspace] <from> <to>`
`COPY_GIT`	`COPY_GIT [--include-dirty] <rev> <src> <dst>`
`SYMLINK`	`SYMLINK <from> <to>`
`MKDIR`	`MKDIR <path>`
`LS`	`LS [<path>]`
`CWD`	`CWD`
`READ`	`READ [<path>]`
`READ_LINE`	`READ_LINE $var`
`WRITE`	`WRITE <path> [<contents>]`
`APPEND`	`APPEND <path> [<contents>]`
`EXPAND`	`EXPAND [<path>] [<KEY=val> ...]`
`ASSERT_EQ`	`ASSERT_EQ [--hash <sha256>] <actual> <expected>`
`ASSERT_CONTAINS`	`ASSERT_CONTAINS <haystack> <needle>`
`HASH_SHA256`	`HASH_SHA256 <path>`
`EXIT`	`EXIT <code>`
`SLEEP`	`SLEEP <duration>`
`WITH_IO`	`WITH_IO [<stream>[=pipe:<name>\|=$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 $var: TYPE = ASYNC { <commands> } \| LET $var: TYPE = <command> \| LET $var: TYPE = AWAIT $task`
`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`
`FUNC`	`FUNC NAME($param: TYPE, ...) { <commands> }`
`CALL`	`CALL NAME(<expr>, ...) \| LET $var: TYPE = CALL NAME(<expr>, ...)`
`RETURN`	`RETURN <expr>`
`WHILE`	`WHILE <bool-expr> { <commands> }`
`BREAK`	`BREAK`
`CONTINUE`	`CONTINUE`

§WITH_IO

Reroute standard streams.

Syntax: WITH_IO [<stream>[=pipe:<name>|=$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 named script pipes (stdout=pipe:name, stderr=pipe:name) or to a PIPE-typed variable (stdin=$p, resolved against the live pipe registry when the step runs). Both stdout and stderr pipes capture output the same way.

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 CALL 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 name is an explicit error. A name bound as output can later feed another command’s stdin, connecting commands without touching the terminal. Binding stdout and stderr to the same live pipe name 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

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

Example: variable pipe binding

# Declare the pipe first with the explicit handle operator
# (like `env:KEY`): `pipe:log` names a pipe without touching
# a stream. A plain string here would be a TypeMismatch.
# `$p` (not `pipe:$p`) is the variable form; literals stay
# `pipe:name`.
LET $p: PIPE = pipe:log
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

LET $items: LIST = ["a", "b"]
FOR $item: STRING IN $items {
  ECHO $item
}

LET $map: MAP = {"x": 1}
FOR $k: STRING, $v: INT IN $map {
  ECHO "$k=$v"
}

Example: expand every match

# single-line body; $x is a template path, WHO an override
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

IF true {
  WRITE yes.txt taken
} ELSE {
  WRITE yes.txt skipped
}

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

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
}
IF $role == "admin" || $level >= 5 {
    WRITE chosen.txt or-true
}
IF $role == "admin" && $level >= 5 {
    WRITE unexpected-too.txt no
} ELSE {
    WRITE and.txt and-false
}
LET $fb: STRING = READ fallback.txt
LET $ch: STRING = READ chosen.txt
LET $an: STRING = READ and.txt
ASSERT_EQ $fb "or-false"
ASSERT_EQ $ch "or-true"
ASSERT_EQ $an "and-false"
LET $t1: STRING = PATH_TYPE("unexpected.txt")
LET $t2: STRING = PATH_TYPE("unexpected-too.txt")
ASSERT_EQ $t1 "absent"
ASSERT_EQ $t2 "absent"

§LET

Bind script-local variables.

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

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.

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, pipe:NAME handles, INSPECT($var) snapshots, GLOB("*.md"), INT(x) / FLOAT(x) conversions — never a {{ ... }} template; interpolation happens in string values, not here.

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=pipe:...] 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: STRING = AWAIT $var captures a background task’s stdout the same way; bare AWAIT $var forwards it to the parent stdout instead.

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

Examples:

Example: let

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

LET $items: LIST = ["a", "b"]
LET $count: INT = 42

Example: glob binding

# the RHS is an expression: GLOB(...) runs and binds a list
WRITE a.txt "x"
LET $files: LIST = 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
LET $out_body: STRING = READ outer.txt
ASSERT_EQ $in_body "inner"
ASSERT_EQ $out_body "outer"

Example: capture command output

LET $out: STRING = ECHO hi
ASSERT_EQ $out "hi\n"

Example: arithmetic over captured output

LET $size_str: STRING = ECHO 41
LET $total: INT = INT($size_str) + 1
LET $ratio: FLOAT = 1 + 2.5
# Int x Int stays INT: integer division truncates.
LET $half: INT = 7 / 2
ASSERT_EQ $total 42
ASSERT_EQ $ratio 3.5
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.
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.
LET $p: PIPE = pipe:log
WITH_IO [stdout=$p] ECHO hello
LET $info: MAP = INSPECT($p)
IF $info.is_os_pipe {
    WRITE unexpected.txt "should be a script pipe"
}
ASSERT_EQ $info.type "PIPE"

§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.

Examples:

Example: mutate

LET $count: INT = 1
$count = 2
ASSERT_EQ $count 2

Example: convert before math

# Captured output is a string: `"100" + 1` is a Type Error.
# Convert explicitly, then mutate with arithmetic.
LET $raw: STRING = ECHO 100
LET $n: INT = INT($raw)
$n = $n + 1
# The declared type also converts plain strings on assignment.
$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 $n 42
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.

Examples:

Example: async

ASYNC ECHO "first"

ASYNC {
    ECHO "first"
    ECHO "second"
}

Example: async task handle

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

§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.

Bare AWAIT $var forwards the task’s stdout to the parent stdout; LET $out: STRING = AWAIT $var captures it into $out instead (same UTF-8 and spilling rules as LET $var: STRING = <command>).

Examples:

Example: await

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

Example: await capture

LET $task: HANDLE = ASYNC ECHO "done"
LET $out: STRING = AWAIT $task
ASSERT_EQ $out "done\n"

§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

§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.

Examples:

Example: timeout

TIMEOUT 30s WRITE heartbeat.txt alive

Example: timeout block

TIMEOUT 30s {
    WRITE a.txt one
    WRITE b.txt two
}

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"

§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 host-registered functions.

Examples:

Example: func def call

FUNC GREET($name: STRING) {
  RETURN $name
}
LET $res: STRING = CALL GREET("ada")
ASSERT_EQ $res "ada"

§CALL

Invoke a user or host function.

Syntax: CALL NAME(<expr>, ...) | LET $var: TYPE = CALL NAME(<expr>, ...)

Invokes a FUNC-defined or host-registered function by UPPERCASE name.

Bare CALL discards the return value and keeps stdout side effects. LET $var: TYPE = CALL captures the RETURN value (fallthrough without RETURN captures as “”), coerced to the declared type; stdout inside the callee stays observable via ASSERT_CONTAINS stdout and pipes.

Combining LET-capture with WITH_IO [stdout=pipe:…] is a parse error.

Examples:

Example: call

FUNC SHOUT($name: STRING) {
  ECHO "{{ $name }}"
  RETURN $name
}
CALL SHOUT("ada")
ASSERT_CONTAINS stdout "ada"

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.
# `pipe:ch` constructs the handle; `$p` passes it on.
FUNC DRAIN($q: PIPE) {
  WITH_IO [stdin=$q] READ_LINE $line
  RETURN $line
}
LET $p: PIPE = pipe:ch
WITH_IO [stdout=$p] ECHO "payload"
LET $got: STRING = CALL DRAIN($p)
ASSERT_EQ $got "payload"

§RETURN

Return a value from a function.

Syntax: RETURN <expr>

Ends the nearest enclosing function call with a value.

Falling off the end without RETURN yields “”. RETURN outside a function (including at top level or across an ASYNC boundary) is an error.

Examples:

Example: return

FUNC PICK($flag: BOOL) {
  IF $flag {
    RETURN "yes"
  }
  RETURN "no"
}
LET $res: STRING = CALL PICK(true)
ASSERT_EQ $res "yes"

§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

LET $done: BOOL = false
WHILE !$done {
  WRITE tick.txt "once"
  $done = true
}
LET $tick: STRING = READ tick.txt
ASSERT_EQ $tick "once"

§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

FOR $x: STRING IN ["a", "b"] {
  BREAK
}

§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

FOR $x: STRING IN ["a", "b"] {
  CONTINUE
}

§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

WORKDIR project/src
WRITE generated.txt generated-under-workdir
LET $body: STRING = READ generated.txt
ASSERT_EQ $body "generated-under-workdir"

§WORKSPACE

Switch workspace roots.

Syntax: WORKSPACE SNAPSHOT|LOCAL

SNAPSHOT or LOCAL root.

Arguments:

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

Examples:

Example: switch roots

WORKSPACE LOCAL

§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

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
LET $outer_body: STRING = READ outer.txt
ASSERT_EQ $inner_body "staging"
ASSERT_EQ $outer_body "production"

§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]

§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

Example: variables

# a lone $x evaluates; {{ }} interpolates inside text
LET $x: STRING = "World"
ECHO {{ $x }}
ECHO $x
ASSERT_CONTAINS stdout "World"

§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

Example: run exec form

RUN ["cargo", "--version"]

§COPY

Copy file into workspace.

Syntax: COPY [--from-current-workspace] <from> <to>

Copies from host.

Arguments:

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

Flags:

Flag	Type	Description
`--from-current-workspace`	`BOOL`	Copy from workspace instead of build context

Examples:

Example: copy

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

Example: copy from workspace

WRITE ws-src.txt ws-content
COPY --from-current-workspace ws-src.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

COPY_GIT HEAD src.txt dst.txt

§SYMLINK

Create symlink.

Syntax: SYMLINK <from> <to>

Creates symlink.

Arguments:

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

Examples:

Example: symlink

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

§MKDIR

Create directory.

Syntax: MKDIR <path>

Creates dir with parents.

Arguments:

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

Examples:

Example: mkdir

MKDIR deeply/nested/tree

§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

§CWD

Print working directory.

Syntax: CWD

Outputs cwd.

Output: Stdout

Examples:

Example: cwd

CWD

§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

§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

WITH_IO [stdout=pipe:lines] ECHO "first"
WITH_IO [stdin=pipe:lines] READ_LINE $reply

§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

§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
LET $all: STRING = READ log.txt
ASSERT_EQ $all "line1line2"

§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

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
WITH_IO [stdout=pipe:tpl] ECHO "Hello \{{ env:NAME }}!"
WITH_IO [stdin=pipe: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 [--hash <sha256>] <actual> <expected>

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; pipe:NAME observes a pipe buffer. --hash compares the SHA-256 of the actual’s string bytes instead of the bytes themselves.

Arguments:

Name	Type	Required	Description
`actual`	`ANY`	yes	Value, stdout, stderr, or pipe:NAME
`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; pipe:NAME observes a pipe buffer.

Arguments:

Name	Type	Required	Description
`haystack`	`ANY`	yes	Value, stdout, stderr, or pipe:NAME
`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

§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.

Arguments:

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

Examples:

Example: exit

EXIT 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

§Value types

§Value type: STRING

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

§Value type: INT

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

§Value type: FLOAT

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

§Value type: BOOL

Boolean true or false.

§Value type: PIPE

Named script pipe. Validity is checked against the pipe registry at coercion time.

§Value type: LIST

Ordered list of values.

§Value type: MAP

String-keyed map of values.

§Value type: HANDLE

Background ASYNC task handle for AWAIT/CANCEL.

§Value type: DURATION

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

§Value type: PATH

Workspace path, resolved against cwd and guarded against escape.

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 markdown::BlockMetadata;
pub use markdown::FencedBlock;
pub use markdown::extract_fenced_blocks;
pub use parser::parse_guard_expr_str;
pub use parser::parse_script;
pub use strip_flags::strip_flags;
pub use ast::*;

Modules§

ast
command
commands: Single-site command registry for all OxDock commands.
markdown
parser
strip_flags
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.

Constants§

LANGUAGE_SPEC