Skip to content

Language Reference

Allie Coleman edited this page Jul 15, 2026 · 4 revisions

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.

1. Lexical structure

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#2 in 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) or catch/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 a match pattern or sh { }; $ ("shoal variables have no sigil"); a backtick (points at sh { } / re"…" / t"…" instead).

2. Statement dispatch — the two-mode rule

For each statement, examine the first token:

  1. A reserved word parses that construct (let, if, for, fn, …).
  2. A non-identifier (literal, (, [, {, -, !, a leading . chain-continuation) is an EXPR statement.
  3. An identifier X — peek one token:
    • next is = or a compound-assign → assignment (X must be a var).
    • X resolves to a bound variable in lexical scope → EXPR statement (x - 1 is subtraction).
    • otherwise → command statement (rest of the line lexes CMD; X resolves through session fn/alias → adapters → reef/PATH; unresolved is command-not-found with did-you-mean across all three).
    • identifier immediately followed by . then another identifier, no whitespace → EXPR statement (invoke-then-chain: ls.where(…) ≡ ls().where(…)).
  4. Escape hatches: ^X … forces command interpretation regardless of shadowing; run("name", args…) is the fully dynamic form. Shadowing a resolvable command name with let is a lint, not an error — ^ls is 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

3. Literals

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.

4. Strings

# 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"

5. Operators, precedence, and coercion

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:

  1. Arithmetic promotion. int→float in mixed arithmetic; size±size, duration±duration, datetime±duration (commutative for +), datetime-datetime→duration, size*int, size/int, size/size→float. Every other pairing is a type_error — there is no implicit numeric-to-string or truthy coercion anywhere.
  2. 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 or arg_error), bool (flag presence), datetime, list<T> (repeated flags/positionals accumulate). Unknown-signature (T0) targets — no adapter, no fn — pass every word as str, 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)

6. Globs

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

7. Control flow

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)

8. No truthiness

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

9. Functions as commands — the §1.6 unification

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

10. Lambdas and implicit .field sugar

(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)

11. Dot-chain composition — the pipe replacement

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 { … }.

12. match

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"

13. Error handling

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.

14. Teaching diagnostics

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)

Cross-links

  • 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 src over the wire, evaluated identically.