Repository navigation
Language Reference
shoal's language unites command-line ergonomics with a rigorous, statically-typed expression
language. There is no separate "shell mode" and "scripting mode" — the same grammar, the same
evaluator, and the same value model back the REPL, .shl scripts, and agent-submitted source. This
page follows docs/TDD.md (the
normative contract) and cites real cases from the
conformance corpus (1,218 cases across
74 files) wherever possible — every fenced example below either is, or is drawn directly from, a
corpus case. See also Execution-Model for what happens after parsing, and
Agent-Surface for how source submitted by an agent is treated identically.
Source is UTF-8. The lexer is modal: the parser drives it between CMD mode (command word
soup) and EXPR mode (conventional tokens). Mode is a property of grammar position, never of
runtime state — the same identifier can open a command in one statement and an expression in the
next, deterministically, based on what it resolves to (§2).
-
Comments:
#begins a comment only at token start (preceded by whitespace, line start, or an opening delimiter) —ver#2in CMD mode is one word, not a word plus a comment. -
Terminators: newline or
;. A statement continues across a newline when the line ends with a binary operator,,, or an unclosed( [ {; when the next line begins with.(chain continuation) orcatch/else; or after a trailing\. -
Strings:
"…"interpolates —{expr}embeds any expression — with escapes\n \t \r \0 \\ \" \{ \} \u{1F980}.'…'is raw — zero escapes, cannot contain'. Triple forms"""…"""/'''…'''are multiline, with common leading whitespace stripped. -
Numbers:
123,1_000_000,0xFF,0o755,0b1010,3.14,1e9. Maximal munch binds a trailing unit into a single literal — see §4 for the full unit tables. -
Reserved words:
let var fn alias use export return break continue if else match for in while try catch true false null. -
Illegal, with curated diagnostics: a lone
|outside amatchpattern orsh { };$("shoal variables have no sigil"); a backtick (points atsh { }/re"…"/t"…"instead).
For each statement, examine the first token:
- A reserved word parses that construct (
let,if,for,fn, …). - A non-identifier (literal,
(,[,{,-,!, a leading.chain-continuation) is an EXPR statement. - An identifier
X— peek one token:- next is
=or a compound-assign → assignment (Xmust be avar). -
Xresolves to a bound variable in lexical scope → EXPR statement (x - 1is subtraction). - otherwise → command statement (rest of the line lexes CMD;
Xresolves through sessionfn/alias→ adapters → reef/PATH; unresolved iscommand-not-foundwith did-you-mean across all three). - identifier immediately followed by
.then another identifier, no whitespace → EXPR statement (invoke-then-chain:ls.where(…)≡ls().where(…)).
- next is
- Escape hatches:
^X …forces command interpretation regardless of shadowing;run("name", args…)is the fully dynamic form. Shadowing a resolvable command name withletis a lint, not an error —^lsis always available.
# From spec/cases/operators.toml — `true`/`false` are reserved literal tokens, so `^` forces
# command interpretation of the coreutils-style `true`/`false` binaries:
^true && ^true
1 + 1
# -> 2
Render forms below are exactly what the corpus asserts (render_inline).
| Form | Examples | Notes |
|---|---|---|
| int |
42, 1_000_000, 0xFF → 255, 0o755 → 493, 0b1010 → 10
|
underscores anywhere; hex/octal/binary prefixes |
| float |
3.14, 1e9 → 1000000000, 0.5
|
Rust Display formatting |
| bool / null |
true, false, null
|
no truthiness anywhere (§8) |
| size |
237b, 1kb → 1kb, 1020b → 1.02kb, 1.5mb, 2tb, 1kib → 1.02kb
|
decimal (b kb mb gb tb) and binary (kib mib gib tib) units; render always picks the largest decimal unit with integer part ≥ 1, ≤2 decimals, trailing zeros trimmed — binary-unit literals render in decimal too |
| duration |
250ms, 90s → 1m30s, 1.5h → 1h30m, 30d → 4w2d, -90s → -1m30s
|
units ns us ms s m h d w; render is compound, nonzero parts only |
| time |
10:00am → 10:00, 23:15, 9:05am → 09:05
|
\d{1,2}:\d{2}(:\d{2})?(am|pm)?, one lexical token; render always zero-pads |
| datetime |
t"2026-07-09T14:00Z" → 2026-07-09T14:00:00Z
|
tagged literal only — no bare absolute-date lexical form |
| regex |
re"\d+", re"a\.b"
|
tagged, raw/verbatim inside the tag |
| glob / path (constructors) |
glob("*.rs") → *.rs, path("a.txt") → a.txt
|
glob renders as its pattern; path renders lossy, quoted only if it contains spaces |
# spec/cases/literals.toml
1kib # -> 1.02kb (binary literal, decimal render)
4mib # -> 4.19mb
90s # -> 1m30s
1.5h # -> 1h30m
30d # -> 4w2d (4 weeks + 2 days)
10:30:15pm # -> 22:30:15
At CMD-mode word position the same maximal-munch rule applies to bare words: a word beginning
~/, ./, ../, or / lexes as a path literal; a word containing unquoted *, ?, […],
or ** lexes as a glob literal, expanded at the callee, never at the lexer (§6); a word
matching --ident(=…)? or -[A-Za-z0-9]+ is a flag; IDENT=rest at head position is an
env-prefix; everything else is a bare str word.
# spec/cases/strings.toml
"a\nb" # -> "a\nb" (real newline, re-escaped on render)
'a\nb' # -> "a\\nb" (raw: the backslash-n stays two characters)
"answer {6 * 7}" # -> "answer 42"
"hi {name.upper()}" # interpolation embeds any expression, including method calls
"xs = {[1, 2]}" # -> "xs = [1, 2]" (any value renders inline inside a hole)
"\u{1F980}" # -> "🦀"
let s = """
hello
world
"""
s # -> "hello\nworld" (common leading whitespace stripped)
String methods (.len .lines .words .chars .split .starts_with .ends_with .replace .parse_int .parse_float .matches .match .upper .lower .trim …) obey the same signature machinery as any
fn. .lines() strips \r?\n (CRLF-safe); .matches(re"...") returns every match, .match(...)
the first.
"the quick fox".words() # -> ["the", "quick", "fox"]
"a1b22c333".matches(re"[0-9]+") # -> ["1", "22", "333"]
"foo bar foo".replace("foo", "baz") # -> "baz bar baz"
Tightest to loosest: . ?. [] () → unary ! - → * / % → + - → .. ..= → == != < <= > >= in
→ && → || → ?? → catch (postfix) → =. Comparison operators do not chain — 1 <= 2 < 3
is a parse error with a fix-it, not silently (1<=2) < 3.
# spec/cases/operators.toml
1 <= 2 < 3 # parse_error, "do not chain"
2 in [1, 2, 3] # -> true
"a" in {a: 1, b: 2} # -> true (record: key membership)
3 in 1..5 # -> true; 5 in 1..5 -> false (exclusive end)
null ?? null ?? 5 # -> 5
3 ?? (1 / 0) # -> 3 (?? never evaluates the rhs once lhs is non-null)
let x = null
x?.foo # -> null (safe-nav short-circuits through null)
Coercion happens at exactly two sites (TDD §4.2) — nowhere else, ever:
-
Arithmetic promotion.
int→floatin mixed arithmetic;size±size,duration±duration,datetime±duration(commutative for+),datetime-datetime→duration,size*int,size/int,size/size→float. Every other pairing is atype_error— there is no implicit numeric-to-string or truthy coercion anywhere. -
Word binding. A CMD-mode word coerces to its declared parameter type at call-bind time:
str(identity),path,glob(compiled, unexpanded),int/float/size/duration/time(parse orarg_error),bool(flag presence),datetime,list<T>(repeated flags/positionals accumulate). Unknown-signature (T0) targets — no adapter, nofn— pass every word asstr, verbatim, always; see Ecosystem-and-Tooling for the T0/T1/T2 tiers.
# spec/cases/coercion.toml
0.5 + 2 # -> 2.5
2kb - 500b # -> 1.5kb
1kb - 2kb # -> type_error, "negative" (size cannot go negative)
10kb / 4kb # -> 2.5 (size/size -> float)
1h + t"2026-07-09T14:00Z" # -> 2026-07-09T15:00:00Z (duration + datetime, commutative)
1s + 1 # -> type_error (duration + int is NOT one of the allowed pairs)
fn addn(a: int, b: int) { a + b }
addn 2 3 # -> 5 (word-bind coercion at CMD-mode call site)
fn showglob(g: glob) { g }
showglob *.txt # -> *.txt (glob param receives the pattern, unexpanded)
fn showbool(b: bool = false) { b }
showbool --b # -> true (bool param = flag presence)
A glob value carries its pattern and origin cwd. Expansion happens at the callee: a
parameter typed glob receives the compiled pattern; list<path> receives the sorted matches
(lazy, origin cwd); path is a type error. T0 externals receive the expanded matches as separate
argv entries — an empty match yields zero argv entries plus a statement-level lint (nullglob by
construction, never a literal * string). ** recurses; dotfiles are excluded unless the pattern
itself starts with ..
Blocks ({ … }) evaluate to their trailing expression.
# spec/cases/core.toml / closures.toml
if true { 1 } else { 2 } # -> 1
if [1] { 1 } # -> type_error, "no truthiness"
var s = 0
for i in 1..4 { s += i }
s # -> 6
var i = 0
while i < 5 { i += 1 }
i # -> 5
for i in 1..10 { if i == 5 { break }; s += i } # break/continue work as expected
fn fact(n: int) { if n <= 1 { 1 } else { n * fact(n - 1) } }
fact(5) # -> 120 (ordinary recursion)
if, &&, ||, and ! admit only bool or a command outcome (whose truth is its
success) — nothing else, ever.
# spec/cases/core.toml, outcome.toml
if [1] { 1 } # -> type_error, "no truthiness"
1 && true # -> type_error (int is not bool/outcome)
echo hi && false # -> false (outcome is truthy, so && proceeds to rhs)
!(echo hi) # -> false (echo succeeded, so ! negates true)
if (echo hi) { "yes" } else { "no" } # -> "yes"
&&/|| return the short-circuiting operand verbatim, not a forced bool — a chain of
outcome-returning commands stays chainable (.status, .out still reachable on the result).
A fn is immediately invocable as a command: with tab completion, synthesized --help, typed
coercion, and flag parsing all derived from its signature. There is no separate "function call"
vs. "command invocation" syntax — they are the same call.
fn deploy(env: str, dry: bool = false) { … }
deploy staging --dry # CMD-mode call: env="staging", dry=true
deploy(env: "staging", dry: true) # EXPR-mode call: identical binding
# spec/cases/core.toml
fn inc(a: int, by: int = 1) { a + by }
inc(4) # -> 5 (default parameter)
[1,2,3].map(x => x * 2) # -> [2, 4, 6]
let add = (a, b) => a + b
add(3, 4) # -> 7
(params) => expr|block or x => x.method(). In argument position only, a leading .
desugars into a one-parameter lambda:
| Sugar | Desugars to |
|---|---|
.field <op> e |
__item => __item.field <op> e |
.method(args) |
__item => __item.method(args) |
ls.where(.size > 1mb) # === ls.where(x => x.size > 1mb)
names.where(.len() > 3).map(.upper()) # === names.where(x=>x.len()>3).map(x=>x.upper())
Closures capture lexically and share the enclosing var's binding cell (not a copy):
# spec/cases/closures.toml
let x = 10
let add_x = y => y + x
add_x(5) # -> 15
var total = 0
let acc = x => { total += x }
[1, 2, 3].each(acc)
total # -> 6 (each call through the closure mutates the shared var)
fn adder(n: int) { let f = x => x + n; f }
let add10 = adder(10)
add10(5) # -> 15 (returned closure still sees its captured param)
There is no |. Composition is a dot-chain over typed values; a lone | outside a match pattern
or sh { } is a parse error with a teaching diagnostic naming the replacement.
# spec/cases/core.toml
ls | wc # parse_error, "no pipe operator"
$HOME # parse_error, "no sigil"
`pwd` # parse_error (backtick — points at sh{} / re"..." / t"...")
The one asylum for |: alternation inside match patterns (§12), and raw POSIX payloads inside
sh { … }.
matchx = "match" expr "{" { arm TERM } "}" ;
arm = pat { "|" pat } ["if" expr] "=>" (expr | block) ;
pat = literal | rangepat | "_" | IDENT | type IDENT
| "{" fieldpats "}" | "[" listpats "]" ;Every pattern kind, straight from spec/cases/match.toml:
# range patterns — inclusive/exclusive boundary is exact
match 5 { 0..3 => "low"; 3..=10 => "mid"; _ => "high" } # -> "mid"
match 3 { 0..3 => "low"; 3..=10 => "mid"; _ => "high" } # -> "mid" (3 excluded from 0..3)
# type patterns — bind and narrow by dynamic type; mismatches fall through
match 5 { int n => "int:{n}"; _ => "other" } # -> "int:5"
match "hi" { int n => "int:{n}"; str s => "str:{s}" } # -> "str:hi"
# record patterns — shorthand binding, subpatterns, missing-field fallthrough, guards
match {name: "ada", age: 30} { {name, age} => "{name} is {age}"; _ => "no match" }
# -> "ada is 30"
match {point: {x: 1, y: 2}} { {point: {x, y}} => x + y; _ => 0 } # -> 3
match {name: "ada"} { {name, age} => "{name} is {age}"; _ => "no age" }
# -> "no age"
match {status: 200} { {status} if status >= 200 && status < 300 => "ok"; {status} => "other:{status}" }
# -> "ok"
# list patterns — fixed arity, rest-binding, arity fallthrough, empty
match [1, 2, 3] { [a, b, c] => a + b + c; _ => 0 } # -> 6
match [1, 2, 3, 4] { [first, ...rest] => rest.len(); _ => 0 } # -> 3
match [1, 2] { [a, b, c] => "three"; [a, b] => "two"; _ => "other" } # -> "two"
match [] { [] => "empty"; _ => "nonempty" } # -> "empty"
# `|` alternation (the one asylum, TDD §1.4) plus a guard
match 7 { 1 | 2 | 3 => "small"; n if n > 5 => "big"; _ => "medium" } # -> "big"
Every eval error carries a stable code, a message, a span, and often a hint. try/catch
intercepts it as a first-class error value; a postfix catch is sugar for the same construct.
# spec/cases/operators.toml, core.toml
try { 1 / 0 } catch e { e } # -> error(div_zero: division by zero)
(1 / 0) catch e { "caught" } # -> "caught"
(1 + 1) catch "fallback" # -> 2 (catch is skipped when there's no error)
try { try { 1 / 0 } catch { 99 } } catch { -1 } # -> 99 (inner catch handles it; outer never runs)
Pinned error codes (CONTRACTS §4): parse_error type_error arg_error undefined_var not_found cmd_failed div_zero index_range field_missing utf8_error stream_consumed no_matches custom assert_failed permission recursion_limit, plus reef's reef_unlocked reef_drift reef_conflict reef_not_found reef_provider (Reef) and IO's feed_error lang_block_unbalanced runner_not_found.
shoal curates parse-time errors for every box-era spelling instead of failing generically, so the error itself teaches the replacement:
| Spelling | Diagnostic names |
|---|---|
cmd | other |
.where/.map/dot-chain, or .feed(cmd) for raw byte plumbing |
$VAR |
"shoal variables have no sigil" |
`cmd` |
points at sh { } / re"…" / t"…"
|
1 < 2 < 3 |
"comparison operators do not chain" |
<< EOF, <<< "text"
|
"no heredocs — value.feed(cmd)" / "no here-strings — "text".feed(cmd)" |
2>, &>
|
"no fd-numbered redirects — .stderr on the outcome" |
See Execution-Model for what an outcome's .stderr/.out actually look like, and
docs/IO.md for the full
heredoc-replacement design — .feed and interpreter blocks (python { … }, jq'…') are both
implemented today (see Ecosystem-and-Tooling and spec/cases/io.toml), e.g.:
# spec/cases/io.toml
python3 { import json; print(json.dumps({"n": 2 + 2})) }.out.n
# -> 4 (interpreter block; JSON stdout is structured .out)
{a: 2, b: 3}.feed(python3 { import sys, json; d = json.load(sys.stdin); print(d["a"] + d["b"]) }).out
# -> "5" (.feed composes with a block: record on stdin)
- Execution-Model — statement vs. value position, outcomes, streams, tasks.
- Reef — how a bare command word actually resolves to a binary.
- Ecosystem-and-Tooling — adapters, which give a command head typed params and structured output instead of T0/T1 guessing.
-
Agent-Surface — the same grammar, submitted as
srcover the wire, evaluated identically.