Skip to main content

Crate oxdock_parser

Crate oxdock_parser 

Source
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

CommandSyntax
WORKDIRWORKDIR <path>
WORKSPACEWORKSPACE SNAPSHOT|LOCAL
ENVENV KEY=value
INHERIT_ENVINHERIT_ENV <key>...
ECHOECHO <message>
RUNRUN <command...> | RUN ["exe", "arg", ...]
COPYCOPY [--from-current-workspace] <from> <to>
COPY_GITCOPY_GIT [--include-dirty] <rev> <src> <dst>
SYMLINKSYMLINK <from> <to>
MKDIRMKDIR <path>
LSLS [<path>]
CWDCWD
READREAD [<path>]
READ_LINEREAD_LINE $var
WRITEWRITE <path> [<contents>]
APPENDAPPEND <path> [<contents>]
EXPANDEXPAND [<path>] [<KEY=val> ...]
ASSERT_FILEASSERT_FILE [--hash <sha256>] <path> [<expected>]
ASSERT_DIRASSERT_DIR <path>
ASSERT_ABSENTASSERT_ABSENT <path>
ASSERT_STDOUTASSERT_STDOUT <substring>
HASH_SHA256HASH_SHA256 <path>
EXITEXIT <code>
SLEEPSLEEP <duration>
WITH_IOWITH_IO [bindings] <command> | WITH_IO [bindings] { <commands> }
FORFOR $item IN <expr> { <commands> } | FOR $key, $value IN <expr> { <commands> }
IFIF <expr> { <commands> } [ELSE IF <expr> { <commands> }] [ELSE { <commands> }]
LETLET $var = <expr> | LET $var = ASYNC { <commands> } | LET $var = <command> | LET $var = AWAIT $task
ASYNCASYNC <command...> | ASYNC { <commands> } | LET $var = ASYNC { <commands> }
AWAITAWAIT $var | LET $out = AWAIT $var
CANCELCANCEL $var
TIMEOUTTIMEOUT <duration> <command...> | TIMEOUT <duration> { <commands> } | TIMEOUT <duration> AWAIT $var

§WITH_IO

Reroute standard streams.

Syntax: WITH_IO [bindings] <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). 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. 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

§FOR

Iterate over a list or map.

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

The loop variable receives each element (lists) or value (maps); with two variables, the first receives the key. Loop variables are scoped to the loop body and 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 = ["a", "b"]
FOR $item IN $items {
  ECHO $item
}

LET $map = {"x": 1}
FOR $k, $v 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 IN GLOB("*.txt") { EXPAND $x WHO=World }
ASSERT_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); only Bool values are accepted as conditions.

Examples:

Example: if else

IF true {
  ECHO yes
} ELSE {
  ECHO no
}

IF false {
  ECHO skipped
} ELSE IF true {
  ECHO fallback
}

IF !false {
  ECHO inverted
}

§LET

Bind script-local variables.

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

Assigns a value to a script-local variable. 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, comparisons, GLOB("*.md") — never a {{ ... }} template; interpolation happens in string values, not here. Bare words need no quotes: LET $d = 30s binds the same string as LET $d = "30s". When the right-hand side is a synchronous command (LET $out = 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. LET $out = AWAIT $task captures a background task’s stdout the same way; bare AWAIT $task forwards it to the parent stdout instead.

Examples:

Example: let

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

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

Example: glob binding

# the RHS is an expression: GLOB(...) runs and binds a list
WRITE a.txt "x"
LET $files = GLOB("*.txt")
FOR $f IN $files { ECHO $f }
ASSERT_STDOUT "a.txt"

Example: scoped variable reverts

# LET inside a braced block reverts when the block exits
LET $a = "outer"
[bool:true] {
    LET $a = "inner"
    WRITE inner.txt "{{ $a }}"
}
WRITE outer.txt "{{ $a }}"
ASSERT_FILE inner.txt "inner"
ASSERT_FILE outer.txt "outer"

Example: capture command output

LET $out = ECHO hi
WRITE captured.txt "{{ $out }}"
ASSERT_FILE captured.txt "hi\n"

§ASYNC

Run steps in a background thread.

Syntax: ASYNC <command...> | ASYNC { <commands> } | LET $var = 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 = ASYNC {
    ECHO "built"
}
AWAIT $task

§AWAIT

Join a background task.

Syntax: AWAIT $var | LET $out = 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 = AWAIT $var captures it into $out instead (same UTF-8 and spilling rules as LET $var = <command>).

Examples:

Example: await

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

Example: await capture

LET $task = ASYNC ECHO "done"
LET $out = AWAIT $task
WRITE captured.txt "{{ $out }}"
ASSERT_FILE captured.txt "done\n"

§CANCEL

Synchronously cancel a background task.

Syntax: CANCEL $var

Kills the named background task spawned via LET $var = 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 = 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 = "30s"
TIMEOUT $budget WRITE heartbeat.txt alive
ASSERT_FILE heartbeat.txt alive

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

NameTypeRequiredDescription
pathpathyesDirectory to change to

Examples:

Example: change working directory

WORKDIR project/src
WRITE generated.txt generated-under-workdir
ASSERT_FILE generated.txt generated-under-workdir

§WORKSPACE

Switch workspace roots.

Syntax: WORKSPACE SNAPSHOT|LOCAL

SNAPSHOT or LOCAL root.

Arguments:

NameTypeRequiredDescription
targetSNAPSHOT|LOCALyesTarget 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:

NameTypeRequiredDescription
assignmentKEY=valueyesKEY=value pair

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 }}"
ASSERT_FILE out.txt "outer scope"

Example: variable value

# a lone $var evaluates, like ECHO $var
LET $who = "Alice"
ENV GREETING=$who
WRITE out.txt "{{ env:GREETING }}"
ASSERT_FILE out.txt "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 = "Ada"
ENV A=$x
ENV B="hello world"
ENV C="{{ $x }} concatenated"
WRITE check.txt "{{ env:A }}|{{ env:B }}|{{ env:C }}"
ASSERT_FILE check.txt "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 }}"
ASSERT_FILE inner.txt "staging"
ASSERT_FILE outer.txt "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:

NameTypeRequiredDescription
keysstring...noHost variables to inherit

Examples:

Example: inherit env

INHERIT_ENV [PATH, HOME]

§ECHO

Print to stdout.

Syntax: ECHO <message>

Outputs message to stdout.

Arguments:

NameTypeRequiredDescription
messagestring...yesText

Output: Stdout

Examples:

Example: echo

ECHO build-complete

Example: variables

# a lone $x evaluates; {{ }} interpolates inside text
LET $x = "World"
ECHO {{ $x }}
ECHO $x
ASSERT_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:

NameTypeRequiredDescription
commandstring...yesCommand

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:

NameTypeRequiredDescription
frompathyesSource
topathyesDest

Flags:

FlagTypeDescription
--from-current-workspaceFlagCopy from workspace instead of build context

Examples:

Example: copy

WRITE src.txt content
COPY src.txt dst.txt
ASSERT_FILE dst.txt content

Example: copy from workspace

WRITE ws-src.txt ws-content
COPY --from-current-workspace ws-src.txt ws-copy.txt
ASSERT_FILE ws-copy.txt ws-content

§COPY_GIT

Copy from git revision.

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

Checkout and copy.

Arguments:

NameTypeRequiredDescription
revstringyesRev
srcpathyesSrc
dstpathyesDst

Flags:

FlagTypeDescription
--include-dirtyFlagInclude dirty

Examples:

Example: git copy

COPY_GIT HEAD src.txt dst.txt

Create symlink.

Syntax: SYMLINK <from> <to>

Creates symlink.

Arguments:

NameTypeRequiredDescription
frompathyesTarget
topathyesLink

Examples:

Example: symlink

WRITE original.txt content
SYMLINK original.txt link.txt
ASSERT_FILE link.txt content

§MKDIR

Create directory.

Syntax: MKDIR <path>

Creates dir with parents.

Arguments:

NameTypeRequiredDescription
pathpathyesDir path

Examples:

Example: mkdir

MKDIR deeply/nested/tree

§LS

List directory.

Syntax: LS [<path>]

Lists entries.

Arguments:

NameTypeRequiredDescription
pathpathnoDir

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:

NameTypeRequiredDescription
pathpathnoFile

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:

NameTypeRequiredDescription
var$varyesVariable to store the line

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:

NameTypeRequiredDescription
pathpathyesFile
contentsstring...noContent

Examples:

Example: write

WRITE output.txt hello-world

§APPEND

Append to file.

Syntax: APPEND <path> [<contents>]

Appends contents.

Arguments:

NameTypeRequiredDescription
pathpathyesFile
contentsstring...noContent

Examples:

Example: append

WRITE log.txt line1
APPEND log.txt line2
ASSERT_FILE log.txt 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:

NameTypeRequiredDescription
pathpathnoTemplate file to expand; omit to expand stdin
overridesKEY=value...noTemplate 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_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_STDOUT "Hello Alice Smith!"

Example: variable override

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

Example: override forms agree

# a bare variable and a template-with-tail expand identically
LET $x = "Ada"
WRITE template.md "Hi \{{ env:NAME }} and \{{ env:NAME2 }}!"
EXPAND template.md NAME=$x NAME2="{{ $x }} concatenated"
ASSERT_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_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_STDOUT "Hi Bob!"
EXPAND template.md
ASSERT_STDOUT "Hi Alice!"

§ASSERT_FILE

Assert file exists.

Syntax: ASSERT_FILE [--hash <sha256>] <path> [<expected>]

Checks the path is a file, then optionally compares its bytes (or --hash SHA-256 digest) against the expectation. Any mismatch aborts the pipeline with a step-numbered error showing expected vs actual.

Arguments:

NameTypeRequiredDescription
pathpathyesFile
expectedstring...noExpected

Flags:

FlagTypeDescription
--hashStringSHA-256

Examples:

Example: assert file

WRITE payload.bin stable-content
ASSERT_FILE payload.bin stable-content

Example: assert file hash

# --hash compares the SHA-256 digest instead of raw bytes
WRITE payload.bin stable-content
ASSERT_FILE --hash 08135c1b6349b0e4f894c36221952f0de00e6b4d82f80895abf359755e77103c payload.bin

§ASSERT_DIR

Assert dir exists.

Syntax: ASSERT_DIR <path>

Checks the path is a directory, aborting the pipeline with a step-numbered error otherwise.

Arguments:

NameTypeRequiredDescription
pathpathyesDir

Examples:

Example: assert dir

MKDIR dist/assets
ASSERT_DIR dist/assets

§ASSERT_ABSENT

Assert path absent.

Syntax: ASSERT_ABSENT <path>

Checks nothing exists at the path, aborting the pipeline with a step-numbered error if it does.

Arguments:

NameTypeRequiredDescription
pathpathyesPath

Examples:

Example: assert absent

ASSERT_ABSENT missing.txt

§ASSERT_STDOUT

Assert stdout contains.

Syntax: ASSERT_STDOUT <substring>

Checks the preceding step’s stdout contains the substring, aborting the pipeline with a step-numbered error otherwise.

Arguments:

NameTypeRequiredDescription
substringstring...yesSubstring

Examples:

Example: assert stdout

ECHO build-complete
ASSERT_STDOUT build-complete

§HASH_SHA256

Print SHA-256.

Syntax: HASH_SHA256 <path>

Computes digest.

Arguments:

NameTypeRequiredDescription
pathpathyesFile

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:

NameTypeRequiredDescription
codeintyesCode

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:

NameTypeRequiredDescription
durationdurationyesHow 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 = "100ms"
SLEEP $pause
LET $bare = 100ms
SLEEP $bare

§Value types

§Value type: string

Arbitrary text under the unified string-value rules: quotes keep exact bytes, a lone $var evaluates, and {{ ... }} placeholders interpolate.

§Value type: path

Workspace path, resolved against the current working directory and guarded against escaping the workspace.

§Value type: int

Integer, e.g. an exit code.

§Value type: duration

Positive time span: a number with an ms, s, m, or h suffix — a bare number means seconds — e.g. 500ms, 10s, 2m.

§Value type: $var

Script variable reference. The $ sigil is mandatory.

§Value type: KEY=value

KEY=value assignment splitting on the first = (KEY=a=b stores a=b). Values follow the unified string-value rules.

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