Lexical

Comments, identifiers, keywords, string forms, numbers, unit literals, operators, sigils, directives, and attributes.

Comments

// runs to the end of the line. Full-line and trailing forms both work:

let retries = 3 // trailing
// full-line
print $"{retries}"

A // needs a space before it or must start the line. Inside a word it is just text, so http://a in a command line stays one word.

On a command line, an unquoted // standing alone as an argument starts a comment. Quote it ("//") to pass the two characters to a command.

// inside any kind of string is just text. Inside an interpolation hole it is a parse error; write the comment outside the string:

print $"{1 // 2}" // a comment cannot live inside a hole

/// lines are doc comments. A doc comment attaches to the declaration directly below it. A blank line in between detaches it, but an attribute line ([<...>]) in between does not. The text shows on hover and in completion. On an Args.load field, the first line is also the field’s --help text.

Identifiers

An identifier starts with a letter or _ and continues with letters, digits, _, or '.

Binding names start lowercase. Uppercase names are for types, modules, and constructors:

let Foo = 1 // binding names start lowercase
print $"{Foo}"

Keywords

A keyword can’t be used as a name — let let = 1 is refused with 'let' is a keyword.

After within comes the kind of scope: cd, env, lock, proc, serve, tmp. Data is read with from (json, jsonl, table, toml, xml, yaml) and written with to (json, jsonl, yaml). These words are special only in those positions; anywhere else they are ordinary names.

pure and readonly each start their own indented block. Code in a pure block may have no effects at all; code in a readonly block may read (files, the environment, the clock, HTTP GETs) but change nothing. pure also marks a function: let pure f x = …. Neither goes after within.

The reserved words are deliberate. Two of them, rec and mutable, are reserved with no meaning, so writing them out of F# habit gives an error instead of quietly binding a name:

let rec f x = x // 'rec' is reserved; weir has no let rec
print "y"

Four more are reserved only so that the error can help. weir has no such constructs, but if you type one out of habit from another language, the error tells you what to write instead: while points at retry/poll and seq iteration, return at a function’s last expression, try at | complete and the within scopes, and def at let:

while true do print "x" // 'while' is not a weir word — the error points at retry/poll

Strings

Strings come in five literal forms, each written on one line. For text that spans several lines, use a text block (below).

Ordinary — "..." with escapes \", \\, \n, \t:

print "a\tb"

A line break inside an ordinary string is a parse error:

let s = "a
b" // strings close before end of line
print s

Verbatim — @"...". Backslashes are literal, and "" stands for one quote character:

print @"C:\temp\x"

Triple-quoted — """...""". No escapes at all; a bare " is fine inside. The string closes at the first """.

Interpolated — $"...". A {expr} is a hole; {{ and }} are literal braces:

let n = 2
print $"n={n} with {{literal braces}}"

Raw interpolated — $"""...""". No escapes, but holes work, so one string can contain a backslash, a bare quote and a hole.

There is no $@"...":

print $@"x" // no verbatim-interpolated form; use $"""...""" instead

Text blocks — for text that spans several lines. A line ending in <<< starts one: the indented lines below it are the text, and its value is a seq<string> with one element per line.

• Everything inside is literal, including $, { and quotes.
• Indentation is kept relative to the first line. Blank lines inside the block are kept; blank lines at the end are dropped.
• Indentation is spaces only, inside blocks too: a tab in a line’s leading whitespace is an error. A tab is content only after the line’s first non-whitespace character.
• $<<< puts values into the text with the same {expr} holes as $"…" strings; {{ and }} are literal braces, and $ stays as is.
• $$<<< uses $name and ${expr} instead and leaves braces and quotes alone, which suits JSON or config templates. $$ is a literal $, and a $ that does not start a name stays as is, so $1 survives. Values are inserted exactly as they are, so a value containing " or a newline can break the output; build the text with to json when values aren’t trusted.
• The marker goes at the end of a line (let x = <<<) or alone on the line below. A marker with no indented block under it is an error.
• To pipe the whole block, put a |> line after it, at or left of the marker’s column (|> Seq.length). A |> indented deeper than the text is just text.

let n = 2
let block = $<<<
    n={n} with {{literal braces}}
    $HOME stays a byte

block |> Seq.iter print

Numbers

Integer literals are plain digits. A minus sign glued to the number or name after it, with a space (or nothing, or another operator) before it, makes that value negative — -5, 2 * -3, and f -1 passes −1 to f:

print $"{-5} {2 * -3}"

Spaced the same on both sides, it subtracts: x-1 and x - 1 both mean x minus 1. (So x -1 is not subtraction — it passes −1 to x.)

Float literals have a decimal point (1.5). Nothing converts implicitly: mixing int and float is a type error that suggests Float.ofInt:

print $"{3 / 2.0}" // no implicit widening; use Float.ofInt 3

A float is always finite. An operation whose result would be NaN or Infinity raises an error:

print $"{1.0 / 0.0}" // float division by zero raises

Integer overflow raises rather than wrapping.

Duration literals

Each literal has a single unit: 500ms, 30s, 2m, 1h.

print $"{90s + 45s}"

Compound literals do not exist — 1m30s is a parse error:

let d = 1m30s // one unit per literal; write 90s, or add 1m + 30s
print $"{d}"

show renders the compound form (90500ms shows as 1m30.5s), and Duration.parse reads that form back.

Size literals

Only binary units have literals: 10MiB, 4KiB, 1GiB.

print $"{1KiB + 512B}"

The SI suffixes are not literals:

let s = 10MB // binary units only in literals; Size.parse reads SI text
print $"{s}"

Size.parse accepts SI suffixes in text it reads, as powers of ten.

Operators

Every infix operator, from lowest precedence to highest. All are left-associative:

A minus sign directly before a value negates it, even after another operator (2 * -3).

% is integer remainder. How it handles signs (truncated, unlike Python’s floored %) and why floats are refused are covered in Types.

The one precedence rule that tends to surprise: |> and >> share the loosest level, so xs |> f >> g is (xs |> f) >> g. The error message says so:

[1; 2] |> Seq.map show >> Seq.length // '>>' and '|>' share precedence; write xs |> (f >> g)

= is not equality. It binds a value in let and record fields, and using it as a comparison is a check error that suggests ==:

if 1 = 1 then print "eq" // use '==' for equality

| is not in the table because it is the command pipe, not an operator. Which one you use depends on the right-hand side: git log | grep x feeds a program, git log |> Seq.head applies a function, and using the wrong one is an error that names the right one.

Sigils

These are all of weir’s sigils:

weir has no ! for negation; use the word not:

if !true then print "x" // '!' is not negation — write 'not true'

Directives

A # line is an instruction to the tooling, not part of the language. Some directives are read when a script is checked; others run immediately, either from the REPL’s init file (read once at startup) or typed at the REPL prompt. Each directive belongs to exactly one of these three contexts:

The REPL manual covers the prompt set and the init file. Signatures and schemas cover the check-time ones.

Attributes

[<...>] attributes are read at check time and have no effect at runtime. The set is fixed.

For command-line flags (Args.load):

• [<Short "c">] — pin a one-character short flag ("h" is reserved for --help)
• [<NoShort>] — suppress the derived short
• [<Default lit>] — a literal default: string, int, float, bool, duration, or size

For data read and written with the adapters (Adapters):

• [<Wire "key">] — the JSON/YAML key for a field, when that key is not a legal weir identifier
• how a time, duration or size is encoded: [<Iso8601>], [<EpochMs>] or [<EpochSec>] on an Instant; [<Millis>] or [<Seconds>] on a Duration; [<ByteCount>] on a Size
• [<Tag "field">] on a union, naming the field that says which case it is, and [<Other>] on the case that takes any unknown value
• [<Attr>] and [<Elem "Name">] for XML attributes and repeated child elements

And [<Positional>], in signature files only, where a foreign CLI’s operands need describing.

A typo is a check error with a did-you-mean:

type Cli = {
    [<Shrot "c">]
    clean: bool
}
let c = Args.load Cli // unknown attribute 'Shrot'. Did you mean 'Short'?
print $"{c.clean}"

The other literals

true and false are keywords. () is the unit literal, the value an effect returns.

There is no char type; a single character is just a one-character string:

let c = 'a' // no char type; "a" is a one-character string

Duration and Size have literals; Instant deliberately does not. You get a point in time from Instant.now (), Instant.parse or Instant.parseWith.

Statement layout

A statement starts at column 0; the full layout and block rules are Statements.

In command argv

None of the above applies inside a command’s argv. 30s, 10MiB, a glued //, and a {brace} are all ordinary words there; it is up to the program to interpret its arguments.

Statements

The statement rule

There are two kinds of statement:

• a command line streams its output as the program produces it;
• every other statement must have type unit — bind its value (let x = …) or print it (expr |> print).

A value that is computed and then ignored is a check error, not silent output:

ls |> Seq.length // computes an int and discards it — bind it, or pipe it to print

Layout

A statement starts at column 0. Indented lines continue it, and the next line at column 0 ends it. Indentation is spaces only — a tab in a line’s leading whitespace is an error, inside text and yaml blocks too. Blank lines and comment lines are ignored for layout, so you can put gaps inside a block.

An indented let ends at the next line with the same indentation. An open bracket keeps the statement going, but the closing bracket must not be at column 0 while the statement is unfinished:

let xs = [
    1
    2
    ]

print $"{xs |> Seq.length}"

One layout form is triggered by how a line ends. A line ending in the yaml marker or a heredoc marker (<<</$<<</$$<<<) opens a block: the indented lines below are that literal’s content, not weir statements, and the first less-indented line ends it. The heredoc forms are covered in Lexical, the yaml template in the guide and Adapters. A marker with no indented block below it is an error that names the marker.

let motd = $<<<
    one line, {1 + 1} holes, $literal bytes

motd |> Seq.iter print

Blocks

Lines at the same indentation inside a block run in order. Each one except the last must be unit, and the last expression is the block’s value. A check before the result, such as if … then fail …, works as you would expect:

type Target = { Name: string }

let target =
    let stack = "web"
    if stack == "" then fail "usage"
    { Name = stack }

print target.Name

Sequencing with ;

; puts several statements on one line. After an if or match, everything following the ; still belongs to the body, as if it were an indented block. Both statements below are in the then-branch, so nothing prints:

if 1 > 2 then print "a" ; print "b"
print "after"

To run something after an if, put it on its own line (or wrap the if in parentheses). In a command line, ; is a literal argument; it does not chain commands, so put one command per line.

match arms and a trailing |>

What a |> on its own line after a match arm does depends on its column. Lined up with the arm’s |, it ends the match and pipes the whole match — no parentheses needed:

match 5 with
| 5 -> 50
| _ -> 0
|> print

That prints 50: the whole match is piped to print, not just the last arm’s 0. Put the |> at or under the start of the arm’s body and it continues that arm instead, whether inline or on its own line:

match 5 with
| n -> n
       |> print

Any column in between — left of the body but right of the | — is an error. The error tells you the body’s column and suggests either moving back to the | (to pipe the whole match) or under the body (to continue the arm). weir does not guess which one you meant.

if / elif / else

if is an expression. else is optional only when the then-branch is unit, and elif is short for else if. The condition can be a command chain written directly: its arguments stop at then, and the condition must still be a bool:

if git rev-parse HEAD | succeeds then print "in a repo"

let

let binds a value, defines a function (let f x y = …, curried), or destructures (let host, port = target, let { names = n } = row). The right-hand side can be a command chain written directly, wherever a let appears:

let tree = git rev-parse HEAD | line
print tree[..6]

for … in … do

for runs a block for each element of a seq, for its effects. The seq goes on the right of in, a pattern on the left. The body streams output and raises errors as each iteration runs. It is the same as Seq.iter; to transform values, use pipelines. The comprehension form [for … -> …] builds a seq:

for greeting in ["hello"; "again"] do
    print greeting

let squares = [for x in [1..5] -> x * x]
squares |> Seq.map show |> print

Declarations

type and module are statements too; import must come first in the file. A file that starts with module is a module: it contains only declarations, can be imported, and cannot be run. Directives (#sig, #schema) go at the top of the file and are read at check time.

Commands

How a line decides

The first word of a statement decides how the line is read. If it is a name bound in scope (or a builtin), the line is an expression — an ordinary function application. If it is an unbound bare word, weir runs the external program of that name, resolved against PATH before anything runs. Builtins take precedence over PATH, and ^ls forces the real program. Inside a function body, its parameters also take precedence over PATH:

let greet name = print $"hi {name}"
greet "io"
echo hi io

Argv

On a command line every word is passed as written: nothing expands, splits or concatenates. A spliced value becomes exactly one argv word. Pieces written next to each other are an error rather than being glued together:

let root = "build"
rm -rf $root/* // argv words do not concatenate — write $"{root}/*"

A command line continues onto indented lines, like every other statement. There is no \ line continuation:

printf "%s %s\n" first
    second

What command lines do not do:

• no backslash escapes — a \ word is an error that shows the replacement (\; is ";", a literal backslash argument is "\\", and \ls is ^ls)
• no glob expansion — Path.glob is a function
• no $VAR expansion — splice weir bindings instead
• ~ is the one exception, and only when typed directly: an unquoted word that is ~ or starts with ~/ means your home directory, resolved when the line runs (cat ~/.bashrc, ~/bin/tool, cd ~). A quoted "~/x", an interpolation and a spliced value stay literal, because weir never re-reads data as syntax. ~user is not expanded. In an expression, build the path with Path.home (), or with Path.configHome/Path.stateHome/Path.cacheHome for the XDG directories: File.read $"{Path.home ()}/.bashrc". Each is a pure unit -> string. On Windows they use %APPDATA%/%LOCALAPPDATA%; on POSIX, the $XDG_* variables with the usual fallbacks such as ~/.config
• cd dir changes the session’s directory (relative to the current one; cd alone goes home) and returns the absolute path it moved to. pwd is the current directory as a string, read at the moment it is used
• no && — write two statements, or chain them with | and / | or
• no redirects — > is passed as a literal argument, with a warning that suggests File.write

When you need bash behaviour, run bash: sh -c "the line". Inside that quoted string, $w is a shell variable, not a weir binding — to pass a weir value, interpolate it (sh -c $"echo {w}").

Splices

$name splices a binding, (expr) splices an expression, and $@xs splats a seq, so N elements become N words:

let marker = "ref"
echo tagged $marker (40 + 2)
echo files: $@(["a.txt"; "b.txt"])

A splice can also read a record field path — $cli.tag, $cli.out.dir, $@cli.files, or a dynamic head ^$cli.bin. It is still one word (or one program, for a head). Only an identifier extends the path, so $x. and $x/y are refused as glued words. This means bash’s $f.bak reads a field; on a string it is an error that suggests $"{f}.bak".

type Cli = { tag: string; bin: string }
let cli = { tag = "v1"; bin = "echo" }
^$cli.bin release $cli.tag

Typed values do not convert to argv implicitly. Splicing a Duration is an error that suggests the explicit forms (Duration.toMillis d or show d). A Secret does splice in the clear — passing it to a command is what the type is for — but it is refused in interpolation and at the serialization boundaries.

Pipes

The operator depends on what is on the right: | feeds a program, |> applies a function. Using the wrong one is an error that names the right one:

git ls-files | sort | head -1
git ls-files |> Seq.length |> show |> print

A value on the left of | becomes the program’s stdin:

["b"; "a"] | sort

Streaming, capture, and the markers

A command written as a statement on its own streams its output. With a let in front, the output is captured instead, as a seq<string> with one element per line, and nothing is streamed. A bare command is an ordinary statement in any block and any match case, so most command lines need no marker at all:

let files = git ls-files
print $"{files |> Seq.length} tracked"

if 2 > 1 then
    git status --porcelain
    print (($(git rev-parse HEAD) |> Seq.head)[..6])

$(...) captures a command chain where a bare command can’t go: inside an expression such as an interpolation hole, a record or a splice (as in the example above). A command line runs to the end of the line — ; there is just an argv word — so each command needs a line of its own.

Environment variables for a single command go before it, as in bash: EDITOR=nano git commit. Each stage of a pipeline takes its own; after the program name, CC=gcc is an ordinary argument. An env overlay bound to e applies to a block of commands with within env e, to a capture with $e(...), and combines with a prefix — where both set the same name, the prefix wins. There is no ! negation; use the word not. To choose between two known tools, branch on the whole command line. When the program really is a runtime value, run it with a dynamic head.

Dynamic heads

^$name runs the program named by a string value — the same force-external ^, applied to a runtime string. The value is always one program name and is never re-parsed: a value containing spaces is one (odd) program name, the arguments after it splice as usual, and nothing is globbed or word-split. Use it to dispatch to plugins or callbacks without sh -c:

let tool = "printf"
^$tool dyn-head-ok

A string-typed capture works directly as a head (^$(… | line)). A seq-typed value is refused, because one program has to be chosen and weir never picks a line for you:

^$(git branch) status // which line is the program? bind and pick first

The program is looked up when the line runs, not at check time. weir check reports no command-not-found for a dynamic head, since there is nothing to look up yet. A missing program is a run-time error that points at the line and names the value, and weir check --can reports the head as not statically known (--strict treats it like other sites it cannot see through). Reifiers, pipes, captures and env overlays work exactly as with a literal head: ^$tool build | complete gives you the computed program’s exit.

Reifiers and chaining

A failing command raises an error when its output is read. A reifier — a | stage after the command — turns the run into a value instead. Where the command’s output goes follows from what you get back: it is captured when the value contains it, streams to the terminal when you only get the exit status, and is discarded by succeeds:

let r = sh -c "echo out; exit 3" | complete
print $"exit {r.exitCode}, said {r.stdout |> Seq.head}"

A reifier can also follow a whole chain, a | b | c | line. The chain’s exit code is that of the leftmost failing stage (where the problem began), or 0. A complete record holds the last stage’s stdout and every stage’s stderr, in stage order. When a later stage stops reading early (git log | head -1), the earlier stage is told to stop, and its exit does not count as a failure. Only exec needs a single command, because a pipeline cannot replace the process (use sh -c "a | b" | exec).

let newest = sh -c "printf 'b\na\n'" | sort | head -1 | line
print newest

exitCode is an error where its result would be captured or thrown away, and the error explains what to do:

sh -c "exit 3" | exitCode // a bare statement discards the code — bind or match it

line, text and exec

The last three rows use the same | spelling but aren’t about the exit code:

• cmd | line — the single stdout line, trimmed, as a string. It raises on a nonzero exit, or if there are no lines or more than one: let sha = git rev-parse HEAD | line.
• cmd | text — all of stdout as one string, with trailing blank lines dropped, like bash’s $(…). It raises on a nonzero exit: let notes = git log -1 --format=%B | text.
• cmd | exec — replaces the weir process with the command (execve; on Windows weir runs it, waits, and exits with its code). The command keeps weir’s pid, so a container entrypoint gets signals directly. It never returns, so it can stand alone as a statement. It can’t take piped input and isn’t allowed inside plan.

All three accept an env overlay ($e(cmd | line)), and line and text accept piped input (xs | grep foo | line).

Chaining

cmd | and next runs next only if cmd succeeded, like bash’s &&; if cmd fails, that failure is an error, so the script stops there. cmd | or next runs next only if cmd failed, like ||; there the failure picks the branch instead of raising. Both stream output and return unit, and the right side is a whole command line, so a builtin such as cd works there:

sh -c "exit 1" | or echo "fell back"
echo built | and echo linked

• One word per chain. a | and b | and c and a | or b | or c are fine; a | and b | or c is an error. For “if a, then b, else c”, write if a | succeeds then b else c (why mixing is refused: coming from bash).
• The left of | or is an external command or a pipeline, which fails with its leftmost failing code. A builtin can’t be there: it raises instead of returning an exit code.
• No reifier at either end. a | and b | complete would capture only b, and a | succeeds | and b has no exit left to branch on; capture on a separate line instead. | exec may end a chain, since it hands over.

if sh -c "exit 1" | succeeds then echo "took the then" else echo "took the else"

Signatures

weir check looks up every command named literally in a script. A declared signature (#sig tool, generated by weir add sig) extends the check to the tool’s flags. The details are on the tooling page.

Types

Scalars

• int — 64-bit. Arithmetic overflow raises an error rather than wrapping around, while a range simply stops at the type’s limit, so every value it yields is correct
• float — always finite: an operation that would produce NaN or Infinity raises an error, and == on floats is a check error that suggests Float.near
• string
• bool
• unit — the value an effect returns, written ()

Nothing converts implicitly: 3 / 2 is integer division, and mixing int and float is a type error that suggests Float.ofInt:

print $"{3 / 2.0}" // no implicit widening; use Float.ofInt 3

% is integer remainder, truncated, so the sign follows the dividend (-7 % 3 is -1, as in F# and .NET; Python’s floored % gives 2). Dividing by zero raises an error, as with /. Floats are refused, because weir floats are always finite and IEEE remainder can produce NaN:

print $"{7 % 3} {-7 % 3}"

print $"{7.5 % 2.0}" // '%' is integer-only — Float.toInt one side

The unit-bearing scalars

Duration, Size, and Instant carry their unit in the value. Durations and sizes have literals (Lexical); instants come from Instant.now (), Instant.parse or Instant.parseWith. Arithmetic between values of the same type works where it makes sense. Arithmetic across types doesn’t exist, and the errors name the explicit conversions (Duration.toMillis, Size.parse, Instant.epochMs).

Uuid

A 128-bit identifier with its own type, not just a string. Uuid.v7 is time-ordered and strictly increasing within the process, so v7 ids sort by creation both as uuids and as their text; Uuid.v4 is random; Uuid.v5 is name-based and deterministic. Uuid.parse reads the hex-and-dash form, 32 bare hex digits, or a urn:uuid: prefix, in any case, and raises on anything else; Uuid.tryParse returns an Option.

let id = Uuid.v7 ()
print $"{id} is version {Uuid.version id}"
print $"{Uuid.v5 Uuid.ns.url "https://example.com"}"

Uuids compare for equality and sort (Seq.sort, Seq.min), by their big-endian bytes, which is the same order as their text. There is no <, since identifiers are not quantities. In JSON and YAML they are written as the lowercase string, and they splice into a command’s argv as that same text.

seq

A seq is lazy. Pipelines compute only what they need, and ranges are generated lazily, while [a; b; c] literals are ordinary eager values. Iterating a bound pipeline a second time runs its effects again, including external commands. Seq.freeze computes the values once and keeps them, and is the usual fix. The checker warns when a binding backed by a command is iterated in a second place without being frozen (possible re-enumeration; this is only a warning, and weir check still exits 0). Capturing a command gives a seq<string>, one element per line.

A let bound to a command, a pipeline of commands, ls or Path.glob holds a lazy value: nothing runs when it is bound, and each read runs it again, in the directory and environment current at that read; only a within cd/within env it was written inside is kept, however late the read (let top = ls, then cd "src": top lists src). These run at once instead: the reifiers (| line, | text, | complete, | succeeds, | exitCode, | orFail, | and/| or), Seq.freeze and any other function that reads the whole sequence, and a $(…) or $@xs in a command argument (argv is built immediately). The contexts (guide):

• script: nothing runs until the value is used
• REPL: the echo of a lazy let shows name : type (command-backed — runs on each use; type name to run it) and never runs it
• init file and modules: a command, a pipeline of commands or a value piped into a command is allowed; the eager forms and passing the command to a function are refused, since nothing may run at load

List items are separated by ; (or by line breaks). A comma builds a tuple, so [1, 2] is a one-item list holding (1, 2); the checker warns about that shape and suggests [1; 2], or [(1, 2)] if the tuple was meant. A list of several pairs, ["a", 1; "b", 2], is fine.

xs[i] is Seq.item i xs and raises an error when out of range. The bracket must directly follow the name, because f [0] is a function call. xs[a..b] slices, inclusive and clamped to the available range (an out-of-range or reversed range gives an empty result rather than an error), and either end can be left open: xs[..b] / xs[a..]. A bounded slice stops reading a lazy source, so nats[0..4] terminates. A slice has the type of what you slice: a seq gives a seq, a string a string ("weir"[1..2] is "ei", counted in UTF-16 chars), and Bytes gives Bytes. ^n counts from the end (^n = length − n): xs[^1] is the last element, xs[..^2] all but the last, xs[^2..] the last two, xs[^3..^1] uses the end for both bounds. A ^ bound needs the length, so slicing a seq from the end reads the whole sequence; slices that count from the start stay lazy. There is no dotted xs.[i].

Tuples

(a, b) — two or more elements. A tuple type is just its element types; it needs no declaration. As soon as the parts need names, declare a record instead. fst/snd work on pairs only.

Records

Records are nominal and have a fixed set of fields: a record literal must name every field, and with copies a record with some fields changed but cannot add new ones:

type Score = { Name: string; Points: int }

let s = { Name = "a"; Points = 12 }
let s2 = { s with Points = 13 }
print $"{s2.Points}"

type P = { N: int }
let p = { N = 1 }
let q = { p with Extra = 2 } // record update cannot add fields
print $"{q}"

Two declared records with the same fields are different types. Anonymous record types like {| ip: string |} are the exception: two with the same fields are the same type, whatever the field order. They are meant for reading an external shape once (from json {| ip: string |}); for your own data, declare a record. Fields can take attributes (Lexical), which are read at check time and have no effect at runtime. A field whose JSON/YAML key is not a legal identifier gives the key with [<Wire "key">].

Unions

Each case can carry a payload; a payload of several values is a tuple. You construct a value by writing the case name. For an imported union, constructing a value needs the module name (X.Red), but a pattern names the case bare (| Red ->):

type Verdict =
    | Pass of int
    | Fail

let v = Pass 12

match v with
| Pass n -> print $"{n}"
| Fail -> print "no"

Option

Some x / None represent a value that may be missing. The try functions return them (Seq.tryFind, Str.tryToInt, Bytes.tryFromBase64), and you handle them with match or the Option module (defaultValue, map, orFail).

Map

Map<string, T> only allows string keys, matching JSON object keys. The functions are ofPairs (the last duplicate key wins), get (raises an error naming a missing key), tryGet, has, and pairs/keys/values (sorted by key). There is no m[k] indexing, and == is not defined:

let a = Map.ofPairs [("k", 1)]
print (show (a == a)) // '==' is not defined for Map<string, int>

Bytes and Secret

Bytes holds binary data. It is never converted to or from text implicitly — you read and write it with functions like File.readBytes and File.writeBytes — and anywhere it would be rendered as text the error names the function to use instead (the guide). It slices like a sequence — b[1..3], b[..2], b[3..], inclusive and clamped, giving Bytes — but has no single-element b[i]; use Bytes.sub start len to take a range, including a single byte (Bytes.sub i 1). Secret marks a credential so it is never shown by accident: show masks it, interpolation and serialization refuse it, Secret.reveal is the only way to get the text out, and splicing it into argv passes it as-is.

Functions

let f x y = … is curried, and you can partially apply any function. Bindings are generic where possible: let id x = x works on any type, and a function-typed parameter is inferred too, so let apply f x = f x has type ('a -> 'b) -> 'a -> 'b and can be called like any function:

let apply f x = f x
print (apply (fun n -> n + 1) 1)

The one place inference falls short: + on two values of unknown type can’t be inferred (int or string?), so pin one side down, for example with x + 0.

You can also write a function type — in a union payload, a record field, or a generic argument: Custom of (string -> bool), { matches: string -> bool }. -> is right-associative and binds more loosely than * and generics (int * string -> bool is (int * string) -> bool); a function-typed argument needs parentheses ((unit -> int) -> string). You can construct such a value and call the function inside it, but ==, to json, to yaml and show reject any type that contains a function anywhere, and the error names the field. So whether a record can be serialized depends on its fields: a record of plain scalars works everywhere.

Constraints

Equality, rendering and ordering each work through a built-in constraint. Constraints are inferred, never written out, and you cannot define your own (there are no user type classes). A helper like let same x y = x == y works on any type that supports equality, and using it with any other type is an error where it is called. Functions and seqs can’t be compared, and for floats the error suggests Float.near.

let same x y = x == y
print $"{same 1 1} {same "a" "b"}"

Patterns

Patterns appear in match arms (the | pattern -> … lines), let, for, and function parameters. A parameter is a plain identifier, (), a parenthesized tuple pattern (let dist (x, y) = …), or a record pattern (without parentheses: let label { names = n } = n). In these binding positions the pattern must always succeed; a pattern that can fail (Some x, a literal) is rejected there — use match or function instead.

type Crew = { names: string }
let label { names = n } = n
let swap (a, b) = (b, a)
print (label { names = "kestrel" })
print $"{swap (1, 2)}"

Variables and constructors: lowercase vs uppercase

A lowercase name in a pattern binds a variable. An uppercase name is a constructor. A mistyped constructor name would therefore bind a variable and silently match everything, so an arm that becomes unreachable because of it is an error with a did-you-mean:

type V =
    | Pass
    | Failing
match Pass with
| pass -> print "ok" // 'pass' binds — did you mean 'Pass'?
| Failing -> print "no"

Literals

Int, string, and bool literals match by equality:

let word =
    match 2 with
    | 0 -> "zero"
    | 2 -> "two"
    | _ -> "other"

print word

Literal arms alone never make a match complete; end with _ or a variable:

let t =
    match 1 with
    | 0 -> "zero"
    | 1 -> "one" // literals never complete a match: add a _ or var arm
print t

Wildcard

_ matches anything and binds nothing. _ also has two expression shorthands — _.field and _[i] — which are lambdas, not patterns.

Tuple patterns

(a, b) destructures a pair; the pattern must have as many elements as the tuple. It works in let too:

let host, port = ("db", 5432)
print $"{host}:{port}"

fst and snd work on pairs only; a longer tuple is a type error:

print (show (fst (1, 2, 3))) // expected 'a2 * 'a3, got int * int * int

Constructors

A case name matches that case, and a nested pattern destructures its payload, including tuple payloads. Patterns can be nested to any depth:

type C = { names: string }

type W =
    | Wrap of C
    | Empty

let n =
    match Wrap { names = "api" } with
    | Wrap { names = n } -> n
    | Empty -> "-"

print n

Record patterns

A record pattern can name any subset of fields; the rest are ignored. Field names keep their declared capitalization, while the names you bind are lowercase:

type Container = { State: string; Names: string }

let r =
    match { State = "up"; Names = "api" } with
    | { State = "up" } -> "running"
    | _ -> "not running"

print r

A field may hold a literal, so one arm can both filter and destructure. Such a pattern can fail to match, so it never makes a match complete on its own:

type St = { state: string }
match { state = "up" } with
| { state = "up" } -> print "x" // a refutable record arm needs a catch-all below it

There is no punning — { names = n }, never { names }:

type Pn = { names: string }
let { names } = { names = "x" } // no punning: bind explicitly, { names = n }
print "unreachable"

There is also no {| |} pattern. Plain braces destructure a record whether its type was declared or anonymous:

let f {| id = i |} = i // no {| |} patterns — the plain brace spelling destructures anonymous shapes too
print (f 1)

Guards

Alternatives share one arm: | "a" | "b" -> …, | Debug | Info -> …. Each alternative behaves as its own arm with the same guard and body, so a union’s alternatives count toward exhaustiveness. An alternative cannot bind a name yet — | (n, 0) | (0, n) -> n is an error; write one arm per alternative. An arm takes at most 64 alternatives; for a longer list, test membership in a guard: | x when Seq.contains x values -> ….

type Level = Debug | Info | Warn | Error
let loud l =
    match l with
    | Debug | Info -> false
    | Warn | Error -> true
print $"{loud Info} {loud Error}"

when adds a condition to any arm. An arm with a when guard never counts toward exhaustiveness:

let tier =
    match 42 with
    | 0 -> "empty"
    | n when n > 100 -> "huge"
    | _ -> "ordinary"

print tier

The Regex pattern

Matches a regex and binds its captures in one arm. The regex must be a raw string (@"..." or """..."""). It is compiled at check time, so an invalid regex is a check error, and the tuple after it must have exactly as many names as the regex has capture groups. Groups are bound as strings:

match "cache=42" with
| Regex @"(\w+)=(\d+)" (key, count) -> print $"{key} -> {count}"
| _ -> print "unparsed"

function

function is a lambda that matches on its argument — short for fun x -> match x with:

["cache=42"; "noise"]
    |> Seq.choose (function
        | Regex @"(\w+)=(\d+)" (k, v) -> Some $"{k}: {v}"
        | _ -> None)
    |> Seq.iter print

Exhaustiveness

A match that doesn’t cover every case is an error, not a warning. Likewise, an arm that can never be reached because a catch-all comes before it is an error. When matching on a union, listing every case makes the match complete; literal arms and record arms that can fail never do.

Interpolation and rendering

Holes

$"…{expr}…" inserts the text of expr into the string. A hole renders anything show can, records and seqs included. Functions cannot be rendered:

type Score = { Name: string; Points: int }
let s = { Name = "a"; Points = 12 }
print $"{s} and {[1; 2; 3]}"

print $"{fun x -> x}" // 'a1 -> 'a1 cannot be shown (functions never render)

{{ and }} are literal braces. A comment cannot go inside a hole. The raw interpolated form $"""…""" has holes but no escapes, and each line of a $<<< heredoc block follows the same hole rules, with $ still an ordinary character. The $$<<< splice heredoc uses a different marker: $name/${expr} substitute and braces stay literal (Lexical).

Generic holes

A hole that uses a parameter makes the function generic, just as show would: the function accepts any value a hole can render, and a function that reads fields works on any record that has them.

let dash n = $"-{n}"
print (dash 5 + dash "x")

type Spec = { name: string; port: int }
let addr s = $"{s.name}:{s.port}"
print (addr { name = "a"; port = 1 })

The one exception is Secret: passing one to such a function is an error at the call, just as it is in a hole written directly (a Secret nested inside a record is rendered masked). A hole whose type cannot be generalized, because the statement it is in does not bind a name, defaults to string.

show

show x produces the same text as a hole, as a plain string. Use it where a hole doesn’t fit: as a function value (Seq.map show), and for a Secret, which show masks as *** while interpolation refuses it.

Rendering is meant for reading, not for exchanging data: strings inside rendered structures are quoted, and long seqs are truncated. Use print for raw output and to json for data other programs will read.

Two values render as summaries

A Secret always renders as ***. A Bytes value renders as its size (<12 B>), never its content, since raw bytes can garble a terminal. Where either is refused, the error names the function to use instead (Secret.reveal; Bytes.toBase64 / File.writeBytes).

Scopes

within holds a resource for the length of a block and releases it however the block exits: normal completion, an error, exit n, SIGINT or SIGTERM. This works both in a terminal and detached: a kill -INT/kill -TERM sent to a setsid or backgrounded weir cleans up the same way, exiting with 130/143. The cleanup runs on the script’s own thread, and no statement after the signal runs: a sleep or a wait on a scoped process is cut short, and the block unwinds from there. A reader closing weir’s stdout (weir s.weir | head -1) ends the script the same way, exiting with 141 (bash’s SIGPIPE status) and no message. A second signal during cleanup exits immediately, so pressing Ctrl+C twice gets you out. There are two exceptions, both by design. kill -9 of weir itself skips cleanup (only a lock is still released, by the kernel). And a weir started in the background from an interactive shell (weir … &/nohup, which keeps a controlling terminal) starts with SIGINT ignored, following the usual job-control convention, so Ctrl+C in the terminal does not reach it; send it SIGTERM, or kill -INT its pid directly. The block is an ordinary block: its statements run and the last expression is its value. It also works as a plain statement.

tmp

Creates a fresh directory and binds its path. It is fine for the block to remove the directory itself before it exits:

let digest = within tmp d
    ["payload"] |> File.write $"{d}/f.txt"
    Str.sha256 (File.read $"{d}/f.txt" |> Str.join "-")

print digest[..11]

cd

Runs its block in the given directory and restores the previous one however the block exits. A missing directory is an error, raised before the block runs, that shows the absolute path.

env

Adds environment variables for every process started in the block. Inside the block, Env.get, Env.vars and Env.load see the overlay too, as pwd sees within cd; after it, they read the unchanged process environment. Nested overlays combine, with inner values winning, and an env given directly on a capture ($e(...)) wins over any enclosing within env:

let vars = [Env.pair "GREETING" "scoped"]

within env vars
    sh -c "echo child sees $GREETING"

print (Env.get "GREETING" |> Option.defaultValue "parent stays clean")

The variables can also be written right after within env, as you would for one command (NAME=value cmd):

let stage = "prod"
within env STAGE=$stage REGION=eu-1
    sh -c "echo $STAGE in $REGION"

A body of one command can go on the same line: within env A=1 make, within cd "src" make.

Bare within and always

Holds no resource; the always block runs however the body exits. When both the body and the cleanup fail, the body’s error is the one raised, the cleanup’s failure is printed to stderr with a marker, and cleanup of the enclosing scopes continues:

within tmp d
    within lock $"{d}/demo.lock" timeout=10s
        within
            print "one holder at a time"
        always
            print "released either way"

always after any kind

Every kind of within can take a trailing always. It runs inside the scope while the resource is still held, and the resource is released afterwards. So the cleanup still sees the tmp directory, runs in the cd directory with the env overlay, holds the lock, and finds a proc or serve still running (they are stopped after it). The bound name is still in scope:

within tmp d
    ["report"] |> File.write $"{d}/report.txt"
always
    cp $"{d}/report.txt" report.txt

It behaves exactly like a bare within … always nested inside the scope, so all the rules above apply.

lock

An advisory file lock. It waits for the lock by default; with timeout=30s it raises an error if the time runs out. It works across processes and across parallel pmap workers.

proc

Starts a background process and binds a handle to it. However the block exits, the process and its children are killed and cleaned up. Several scoped processes are stopped in reverse order of starting. A child’s own exit status is a value (Proc.wait), not an error. The guide covers the details: watch=, output files and Proc.tail. A process that must outlive the script is a daemon and belongs under systemd; weir has no nohup.

serve

An HTTP listener held for the block. within serve srv = { port = 8080; maxConcurrent = 4 } handler opens the socket on loopback, runs handler — a plain synchronous HttpServerRequest -> HttpServerResponse function — once per request, and closes the socket however the block exits (normally, by an error, SIGINT, SIGTERM), so the port is freed. As with proc, the server lives exactly as long as the block, and there is no stop function. Server.port, Server.running and Server.streamErrors are all you can do with the handle.

The listener answers on the same port for all the common loopback names — 127.0.0.1, localhost and [::1] — so a client using any of them reaches the handler ([::1] is skipped quietly on a host without IPv6 loopback). It only listens on loopback and never binds all interfaces, so it can’t be reached from other machines; put a reverse proxy in front of it for a public address.

The handler routes on req.path with an ordinary match; there is no routing framework:

let handler = fun req ->
    match req.path with
    | "/health" -> HttpServerResponse { status = 200; headers = []; body = Text "ok" }
    | _ -> HttpServerResponse { status = 404; headers = []; body = Text "not found" }

The response body is an HttpBody, shared with the Http client — NoBody, Text, Json, Form, or Stream of seq<string>. A Stream body is written chunked and flushed per element (SSE-shaped: one event per element, one data: line per line of it, so a newline cannot forge an event), so a lazily produced seq streams as it goes: the client sees the first elements before the sequence is finished. If a Stream producer raises partway through, the error is not raised out of the handler. Instead it is recorded on the handle, and you read it with Server.streamErrors srv (the response is aborted, so a careful client can tell it was cut short). maxConcurrent limits how many handlers run at once, as with Seq.pmapWith; extra requests wait in a queue.

The config record is { port; maxConcurrent }, optionally with bodyTimeout (a Duration, default 30s) that limits how long reading the request body may take, and maxBody (a Size, default 16MiB) that limits its size. A client that sends its body too slowly gets a 408 instead of tying up a handler; a body larger than maxBody gets a 413 and is never buffered whole.

HttpServerRequest carries:

• method — an HttpMethod. A valid method the union has no case for arrives as Other of string (match it with | Other v ->), QUERY arrives as Query, and a malformed method gets a 400 before your handler runs
• path
• query — the raw string without the leading ?; split it with Str.trySplitOnce
• headers — pairs, in the order received. The underlying listener keeps only the last value of a repeated header, so a proxied X-Forwarded-For chain shows only the last hop
• body — the request text

Deliberately not supported in v1:

• TLS — put a reverse proxy in front
• a routing DSL — the match is the router
• WebSockets
• request-body streaming
• HTTP/2

Boundaries: argv and env

Command-line arguments and environment variables load the same way: declare a record, load it once, and use the typed values from then on. Loading is strict and reports every problem at once, in a single error, before the script does anything.

Args.load

Field names become kebab-case flags (dryRun → --dry-run), plus a first-letter short flag where that is unambiguous. A bool field is true when the flag is present. string, int and the other scalars are required, and Option makes a field optional. The first line of the field’s /// comment is its --help text:

type Cli = {
    [<Short "C">]
    /// clean the target first
    clean: bool

    port: Option<int>
}

let cli = Args.load Cli
print $"{cli.clean} {cli.port}"

[<Short "c">] sets a short flag ("h" is reserved for --help), and [<NoShort>] removes one. These problems are all reported together:

• unknown flags (with a did-you-mean)
• unexpected arguments
• missing required flags
• unparseable values

--help prints the usage even when the rest of the command line is invalid.

There are no positional arguments; pass operands as flags. To parse arguments by hand, Args.flag and Args.value scan the raw Self.args.

Subcommands

Declare subcommands as a union whose cases carry records. The first argument picks the case, the rest are parsed as that case’s flags, and the checker makes sure your match covers every case. Flags shared by all subcommands go once on a containing record, and may appear before or after the subcommand name:

type CloneArgs = { remote: string; force: bool }
type Cmd = Clone of CloneArgs | Status
match Args.load Cmd with // no argv here: "missing subcommand; one of: clone, status"
| Clone a -> print a.remote
| Status -> print "status"

Defaults

[<Default v>] supplies a value when the flag is absent; the field stays non-Option, and --help shows the default. On a bool, [<Default true>] adds a --no-x flag to turn it off. [<Default false>] is rejected on a bool, since a missing flag is already false. The attribute takes literals only; for a computed default, keep the field an Option and fill it in with one line of code.

Env.load

The same approach works for environment variables. Field names match variable names exactly, with no case conversion (use [<Wire "NAME">] for a name that is not a legal identifier). [<Default>] fills in missing variables, and a Secret field is the standard way to take in a token. Env bools are read from text (FLAG=false), not from whether the variable is set.

When a variable has a fixed set of allowed values, declare it as a union of cases without payloads. Matching is case-insensitive (env values are usually uppercase), and an unknown value is an error that lists the allowed ones with a did-you-mean:

type Level =
    | Debug
    | Info

type LogCfg = { REF_BOUND_LEVEL: Level }

["REF_BOUND_LEVEL=debug"] |> File.write "ref-bound.env"
let e = Env.fromFile "ref-bound.env"
within env e
    sh -c "echo level=$REF_BOUND_LEVEL"
print "declared sets beat stringly config"

Env.get "NAME" reads one variable as Option<string>. Env.fromFile reads a subset of dotenv (KEY=VALUE, quotes, # comments; no export and no $VAR expansion).

What both refuse

Both refuse Bytes fields, and the error names the conversion to use. Both parse Instant fields as ISO 8601. A Secret passed as a flag is visible in ps output; weir does not hide argv.

Adapters

from reads a data format into a type you declare; to writes one. Three formats work in both directions (json, jsonl, yaml), and three more are read-only (toml, xml, table). You always say which format you mean: from json T reads one document however many lines it spans, while from jsonl T reads one document per line (blank lines are skipped) and yields seq<T>.

type Peer = { host: string; port: int }

let peer = ["{\"host\": \"a\", \"port\": 9000}"] |> from json Peer
print $"{peer.host}:{peer.port}"

let peers = ["{\"host\": \"a\", \"port\": 1}"; "{\"host\": \"b\", \"port\": 2}"] |> from jsonl Peer
print $"{peers |> Seq.length} peers"

Writing mirrors reading. to json writes one minified document: a record becomes an object and a seq becomes an array (built in memory all at once, since a single line cannot be streamed). to jsonl writes NDJSON, one document per element, lazily. Strings escape only what JSON requires (", \, control characters); <, &, ' and non-ASCII text are written as-is, characters beyond the BMP as a \uXXXX surrogate pair. Each format reads back what it writes: to json |> from json T, to jsonl |> from jsonl T.

type P = { a: int }
{ a = 1 } |> to json |> Seq.iter print
[{ a = 1 }; { a = 2 }] |> to json |> Seq.iter print
[{ a = 1 }; { a = 2 }] |> to jsonl |> Seq.iter print

(prints {"a":1}, then [{"a":1},{"a":2}] — one array document — then the two NDJSON lines.)

Which field types are allowed

A field is one of:

• a scalar (int, float, string, bool)
• an Option of one of these types
• a record whose fields are all of these types
• a seq of one of these types
• a Map<string, T>

The rule applies recursively. A self-referential record is a check error that names the cycle. For a top-level JSON array, say so in the type: from json seq<Peer>. Integer-looking JSON numbers are accepted by float fields (JSON has only one number type).

A missing array is an error, not a silent []; use Option for fields that may be absent. Unknown keys are ignored on read. A key that is not a legal weir identifier is mapped with [<Wire "key">], and two fields that map to the same key are an error at the declaration.

Documents in several shapes

A tagged union reads documents whose shape depends on one field. [<Tag "kind">] on the union names that field. Each case carries a declared record, or nothing for a document that has only the tag. The tag value defaults to the case name; [<Wire "v1">] on a case overrides it. Tagged unions work in JSON and YAML, at the top level or nested, so from jsonl KDoc reads mixed NDJSON and from json seq<KDoc> reads a mixed array. Adding one [<Other>] case (of string, or with no payload) makes the union accept unknown tags: they land in that case instead of raising an error. A document with no tag field is always an error, since that is malformed rather than unknown. When writing, the tag is written first, and an [<Other>] value cannot be written. Unions without a tag are not supported; the error suggests [<Tag>].

Keys that are data

Map<string, T> reads an object keyed by IDs, either as a field or as the whole document. Keys must be strings, entries are iterated in key order, and for duplicate keys the last one wins. to json writes the object back.

YAML

from yaml T accepts the same shapes as JSON. Quoting decides a scalar’s type in both directions: rate: 1.5 is a number, "1.5" is a string. An empty value and the plain words null, Null, NULL and ~ are null (YAML 1.2’s core schema): None in an Option field, an error in a required one; "null" is a string. A quoted scalar may continue on more deeply indented lines, as in kubectl’s long message: values:

• the closing quote ends it
• each line break folds to a single space
• an empty continuation line becomes a newline
• the folded value stays a string

Literal block scalars (key: | and key: |-) read as strings. An indentation indicator such as |2 or |2-, which kubeconfigs sometimes carry, sets the content’s indentation relative to the key, so the first line may keep leading spaces. Folded scalars (>) and |+ are not supported.

from yaml stream T reads a ----separated stream of documents, each as T. To read a mixed bundle such as a Kubernetes apply file, use from yaml stream KDoc with a tagged union: stream means “many documents”, and the union picks the shape of each one. An empty stream gives zero documents.

Writing mirrors reading exactly. to yaml writes one document: a record becomes a mapping, a seq a sequence document, and a seq of pairs one mapping. to yaml stream writes one document per element. Each form reads back with the matching reader (to yaml |> from yaml seq<T>, to yaml stream |> from yaml stream T). A multiline string is written as a block scalar. The yaml template literal (with checked structure, splices as nodes, and schema=) is part of the language and is covered in the guide; vendoring schemas is on the tooling page.

TOML

from toml T reads one TOML document into T — a Cargo.toml, a pyproject.toml, a tool’s config. It reads TOML 1.1, so every TOML 1.0 file too, and it is read-only: there is no to toml. The document is a table, so T is a record (or a tagged union); seq, stream and Map tops are refused. Inside, the field types follow YAML’s rules: tables are records, arrays and arrays of tables ([[bin]]) are seqs, a key that may be missing is an Option, and [<Wire "key">] names a key that isn’t a weir name, such as requires-python.

• Integers in any TOML spelling (1_000, 0xff, 0o7, 0b1) read as int; inf and nan parse, but reading one into a float field is an error, since weir floats are finite.
• A date or time is read as its text. An offset date-time such as 2024-03-01T10:00:00Z reads into an Instant field marked [<Iso8601>].
• Duplicate keys and tables defined twice are errors, reported with the line, as the TOML spec requires.

type Package = { name: string; version: string }
type Cargo = { package: Package; bin: seq<{| name: string |}> }

let cargo = <<<
    [package]
    name = "demo"
    version = "0.3.1"

    [[bin]]
    name = "cli"

let c = cargo |> from toml Cargo
print $"{c.package.name} {c.package.version}: {c.bin |> Seq.map _.name |> Str.join ","}"

XML

from xml T reads one XML document into T. It is read-only and supports a subset of XML. The document’s root element maps to the top-level record. A field matches a child element by local name (a default xmlns, like MSBuild’s, is stripped so field names stay plain). [<Attr>] (or [<Attr "Include">]) reads an attribute. [<Elem "ProjectReference">] names the repeated child element that a seq< > field reads; by default that is the element type’s name for seq<record> and the field name for seq<string>. A nested record reads a child element recursively.

type Ref  = { [<Attr>] Include: string }
type Pg   = { IsPackable: Option<string> }
type Proj = { [<Elem "PropertyGroup">] groups: seq<Pg>
              [<Elem "ProjectReference">] refs: seq<Ref> }
let proj =
    [ "<Project>"
      "  <PropertyGroup><IsPackable>false</IsPackable></PropertyGroup>"
      "  <ProjectReference Include=\"../Core/Core.csproj\" />"
      "</Project>" ]
    |> from xml Proj
print $"{Seq.length proj.refs} refs, {Seq.length proj.groups} property groups"

Every XML leaf is text, so a field is string, Option<string> (a present-or-absent element or attribute), a record, or a seq of a string or record — nothing else. A numeric or boolean field is declared string and converted (Str.toInt); the checker tells you this rather than guessing at a convention XML does not define. [<Attr>] fits only string/Option<string>, [<Elem>] only a seq, and the top level is a single root element, so there is no from xml seq<T> (repeated children are read with a seq< > field). There is no to xml.

Aligned tables

from table T reads aligned column output, the kind kubectl and docker print (one header row followed by aligned data rows), into declared row records, yielding seq<T>. The first non-blank line is the header. Columns are cut at the header positions, not at whitespace, so a value containing spaces (Up 2 hours, a free-text last column) stays intact. Headers are separated by two or more spaces; a single space stays inside a header, so CONTAINER ID is one column (both tools pad columns with three spaces).

type Pod = { name: string; status: string; restarts: int; node: Option<string> }
let pods =
    [ "NAME    STATUS    RESTARTS   NODE"
      "web-1   Running   0          k3d-a"
      "db-0    Pending   3          <none>" ]
    |> from table Pod
pods |> Seq.iter (fun p -> print $"{p.name}: {p.status} ({show p.restarts} restarts)")

A field matches its header by name, ignoring case and anything that is not a letter or digit: name reads NAME, podTemplateHash reads POD-TEMPLATE-HASH. [<Wire "HEADER">] matches a header exactly as written. Cells are trimmed and converted to the field’s type (string, int, float, bool). An Option field reads an empty cell, or a cell that is exactly <none> (as kubectl prints), as None; an empty cell in a required field is an error that suggests making it an Option. Extra columns are ignored (as with unknown JSON keys), blank lines are skipped, and a table with only a header is an empty seq (docker ps with nothing running). Errors say where: a missing column is named along with the headers that were found, and a cell of the wrong type is reported with its row and column. The result is already a seq of rows, so you don’t write seq/stream/Map around the type. There is no to table.

az … -o table (and other tabulate-style tools) draw a dashes rule line under the header (------ ----------). from table skips that separator when it is the first data row, so az output reads without a garbage row and #infer types from the real rows. Tables with no separator (kubectl, docker) are unchanged; only a row that is entirely dashes and spaces is dropped, and only in first position.

#infer <src> from table as Pod (or sample |> Table.inferShape) drafts the row record from a real sample. It infers each column’s type, uses Option where a column has empty or <none> cells, and notes that the value reads as seq<Pod>.

Editing YAML: Yaml.parse and yaml patch

from yaml T reads into a declared record and drops every field you did not declare, so it is the wrong tool for read-modify-write. For that, use the untyped pair, which keeps the whole document. Yaml.parse reads one document into Yaml nodes (scalars get their type from their text, exactly as in a yaml block), and Yaml.merge applies a yaml patch block. The patch’s structure says where each change goes — kustomize’s strategic-merge model, with no path language. Maps are merged recursively, adding or updating keys. A sequence item is appended if absent, or, with by=<key> on the marker line, updated by that key (and inserted if no item matches). Scalars are replaced. The $- marker removes things: in value position it removes the key it sits under, and as - $- <content> it removes the matching item. The order of changes does not matter and applying a patch twice gives the same result, so with by= you never write an “update or insert” branch yourself.

let doc = <<<
    kind: Kustomization
    images:
        - name: app
          newTag: v1
|> Yaml.parse
let p = yaml patch by=name
    images:
        - name: app
          newTag: v2
doc |> Yaml.merge p |> to yaml |> Seq.iter print

A patch has type YamlPatch, not Yaml, and the type enforces the rules. to yaml on a patch is a check error, because a patch is a set of instructions rather than a document, so a $- removal marker can never end up in a file. $- outside a yaml patch block is an error, and patch cannot be combined with schema= (a patch is partial, while schemas validate whole documents). Yaml.parse never produces a removal marker; parsed text is always plain data. There is no function that edits a file in place. You write the round-trip as a pipeline, File.read f |> Yaml.parse |> Yaml.merge p |> to yaml |> File.write f, so the change stays visible.

Which types serialize automatically

Types with one obvious encoding are serialized automatically. Types that could be encoded in more than one way are refused, and the error names the explicit conversion. JSON and YAML follow the same rule in both directions, with the same messages.

• int, float, string, bool and Uuid work directly. A Uuid is written as its lowercase string and read back with any form Uuid.parse accepts; a malformed string raises an error naming the field. A JSON-lines log keyed by Uuid.v7 stays sortable by id as text.
• Instant, Duration and Size are refused unless you say how to encode them: an epoch number and a text form are both reasonable, and weir won’t guess which one the other side expects. Put a codec attribute on the field, or convert explicitly; the error message offers both.

type Event = {
    [<Iso8601>] at: Instant
    [<Millis; Wire "elapsed_ms">] took: Duration
}
let line = [{ at = Instant.parse "2026-08-14T12:00:00Z"; took = 1500ms }] |> to jsonl |> Seq.head
print line
let back = [line] |> from jsonl Event |> Seq.head
print (show back.took)

One declaration covers both directions, so the writer and the reader cannot disagree. A codec applies to a T, Option<T> or seq<T> field, and it must fit the field’s type; this is checked where the record is declared. [<EpochSec>] and [<Seconds>] raise an error on a value with sub-second precision rather than silently dropping it. Codecs affect only to/from json, jsonl and yaml; show and == ignore them.

• Bytes is refused; the error suggests Bytes.toBase64.
• Secret is always refused. Credentials are never serialized, in any encoding.

Anonymous shapes at the boundary

For a shape you read only once, you can write the type inline:

let n = ["{\"count\": 3, \"noise\": true}"] |> from json {| count: int |} |> _.count
print $"{n}"

Declared records are distinct types even when their fields match. Two anonymous shapes with the same fields are the same type, whatever the field order.

Modules and imports

What a module is

A file that starts with module (alone, or module Name) is a module. It can be imported, it contains only declarations (type and let; no commands and no bare expressions), and it cannot be run on its own. A module’s let cannot run a command when the module is imported (| line and the other reifiers, |> Seq.freeze, passing the command to a function); wrap the command in a function, and it runs when a script calls that function. A plain command value (let log = git log -n 10, or a pipeline of commands) is allowed: it is lazy, so importing runs nothing and each use runs it again. A module’s top-level let values are evaluated when the importing program runs, never by weir check, which never evaluates anything.

Import forms

import comes first in the file, before any declarations. How a path resolves depends only on how it is written, never on which files exist:

• import "./lib/x.weir" as X — a file path, relative to the importing file’s directory (lib.weir and names without an extension work too), or an absolute path. If the importing file is a symlink, its real location counts: a script linked into ~/bin imports the files beside the original
• import "weir:name" as N — a vendored module: weir looks upward for a .weir/ directory and loads .weir/modules/name.weir (tooling)
• as is optional — the alias defaults to the module’s declared name, or the capitalized filename

let modSrc = <<<
    module RefMod

    /// doubles
    let twice : int -> int

    let twice n = n * 2

let useSrc = <<<
    import "./refmod.weir" as M

    print $"{M.twice 21}"

modSrc |> File.write "refmod.weir"
useSrc |> File.write "use-refmod.weir"
weir use-refmod.weir

The signature is the export

A member is exported by declaring its signature — let twice : int -> int, with no = — above its implementation. Members without a signature are private to the module: their types are inferred inside the module, importers can’t see them, and using one from an importer is a check error that shows the signature to add (with the inferred type). The implementation needs no type annotations, because it is checked against the signature. A parameter can therefore pattern-match on its declared union type, and a generic signature ('a -> 'a) is enforced: an implementation that is less general than its signature is an error. The signature must come before the implementation, and a signature with no implementation is an error. Put /// docs on the signature line, where the API is documented. type declarations are always exported. Scripts can’t use signatures; in a script, types are always inferred.

Qualified access, and what never leaks

Imported values are always qualified: X.helper. Imported types can be used by their plain name — Ctx { field = v }, from json Ctx — and a record can also be built with the qualified X.Ctx { field = v }. An imported union’s cases are qualified when you construct a value (X.Red) but named bare in a pattern (| Red ->), and a local declaration always takes precedence over an imported name. A module exports only its own declarations, not what it imported.

The graph

Imports are transitive. A module imported by two others is checked only once. An import cycle is a check error that shows the loop, and a module cannot import itself. Paths are resolved at check time, from the path as written; nothing is looked up at runtime, and a missing file is an error at the import that shows the resolved absolute path.

Script-only

import needs a file to resolve paths against, so it is not allowed in -e or at the REPL prompt; the error explains why. The REPL’s init file is a file, so it can import.

Capabilities travel

check --can follows imports transitively: a module’s commands, file writes and network access appear in the importing script’s report, located at the module’s own file:line.

Loops and parallelism

There is no while, and no unbounded loop in any form. Every loop has a limit: retry (a number of attempts), poll (a time limit), for (a seq), and the parallel fan-outs.

retry and poll

Both have the same form: key=value options after the keyword, a block whose last statement is its value, and an optional until section that binds that value and tests it. If the block’s value is a bool, that is the success condition, and the whole form returns unit:

retry attempts=3 delay=100ms
    weir -e "print 1" | succeeds

To keep the successful attempt’s output, yield a value and bind it in until:

let out = retry attempts=3 delay=100ms
    let r = weir -e "print 42" | complete
    r
until r
    r.exitCode == 0

print (out.stdout |> Seq.head)

poll timeout=5m interval=10s has the same form but is limited by time; it is the loop for waiting until something is ready. watch=<proc handle> makes it fail immediately if the watched child process dies. When attempts or time run out, the error states the attempts made and the time elapsed. The options are an ordinary record, so you can compute and share them: let fast = { Retry.defaults with attempts = 3 }, then retry fast.

Seq.pmap / Seq.piter

These run a function over a seq in parallel. Results come back in input order, every item is processed, and if any fail, the error from the earliest item (in input order) is raised once all have finished:

[30; 10; 20] |> Seq.pmap (fun ms -> ms * 2) |> Seq.freeze |> Seq.map show |> print

Each worker gets its own copy of the session, so a cd or env change inside one only affects that worker and is gone afterwards. At most 64 run at once. The limit protects system resources rather than matching CPU count, since the work is usually I/O-bound. Seq.pmapWith / Seq.piterWith set the limit explicitly, and a value below 1 is an error:

[1] |> Seq.pmapWith 0 (fun x -> x) |> Seq.freeze // degree must be >= 1

There is no async/await, and there won’t be: concurrency in weir comes from processes and pipelines. A task that really needs async belongs in full F#.

Background processes

within proc h = cmd runs a background process for the length of a block. The process and its children are killed and cleaned up however the block exits. poll watch=h catches a process that crashes on startup. The child’s output goes to files (Proc.tail reads the last lines), and its exit status is a value you get from Proc.wait rather than an error. The guide walks through an example with a running server, and the scopes page covers how scopes work.

Errors and diagnostics

Check, then run

weir check reports all diagnostics at once, each with a location and a code, without running anything. A missing command is a warning at check time (exit 0, so you can still edit scripts for tools you haven’t installed) and an error at run time:

["nosuchcmd --flag"] |> File.write "ref-missing.weir"
let c = weir check ref-missing.weir | complete
print $"check exits {c.exitCode}"
let r = weir ref-missing.weir | complete
print $"run exits {r.exitCode}"

weir check --json emits the same diagnostics as an array of {file, line, col, endLine, endCol, severity, code, message} — for editors, CI gates and agent loops.

Which error you see

When a line has more than one thing wrong, you see one error: the one at the furthest point the parser reached. A later mistake cannot hide an earlier one, and separate broken statements each report their own error. The position is always a real spot in your file; a hint may replace the message, but never moves the position. check, check --json and the LSP all report the same error.

An error while the script runs is reported as file:line:col too, at the statement that failed — inside an if, match, for, within or retry body, a pipeline, or a lambda, not at the block’s first line. A failed command points at the command itself, even when its output is only read a few lines later. Other errors (fail, a builtin) point at the start of the failing line. A failure inside a function reports the line in the function, then where it was called from, one line per call, innermost first:

lib.weir:7:5: error: command failed with exit code 9: sh -c exit 9
  called from deploy.weir:4:1

Inline lambdas and for bodies add no called from line; they are part of the statement they’re written in.

Raising

A failing command raises an error when its output is read; a reifier turns the failure into a value instead (commands). Builtins raise errors with a location and a readable message (File.read: no such file: …). There is no try/catch block. A resource that needs cleanup goes in a within scope, which releases it however the block exits.

To turn a failure into a value, end an expression with |> try — the expression twin of | complete:

• e |> try is Option<'T>: Some value, or None if evaluating e raised.
• e |> try result is Result<'T, string>: Ok value, or Error with the message. Result has map, defaultValue, toOption and isOk.
• Everything to the left of |> try is captured (|> groups left to right), and the value is fully evaluated inside, sequences included, so a failure can’t surface after try returns. An infinite sequence on the left never finishes.
• exit still exits, and weir’s own internal errors are not caught. Effects that happened before the failure are not undone.
• try is only valid after |>.

A script’s own union cases take precedence over the prelude’s: a type Status = Ok | Error declared in the script keeps constructing its own Ok, while a match on a try result value still sees Result’s cases.

fail and exit

fail "reason" stops the script with a located error and exit 1. exit n exits silently with a specific code, which is how you pass on a child process’s failure:

let r = sh -c "exit 3" | complete
if r.exitCode <> 0 then print $"would exit {r.exitCode}"

Log and log levels

Log.trace/debug/info/warn write levelled diagnostics to stderr; WEIR_LOG sets the level for one run (off silences them). There is deliberately no Log.error, because an error message should never be hidden by an environment variable. For a message that must always appear, use printerr; to stop, use fail. Stdout is exactly the same at every log level:

let e = Env.ofPairs [("WEIR_LOG", "off")]
within env e
    weir -e "Log.info \"hidden\" ; printerr \"loud\" ; print 1"

Warnings

Warnings never stop a run; they point out a likely mistake and carry on. Examples are a missing command at check time, > passed as a literal argv word, and ; in a command line. Each warning says what to use instead.