diff --git a/SPEC.md b/SPEC.md index 0cd77164..38b32750 100644 --- a/SPEC.md +++ b/SPEC.md @@ -421,6 +421,8 @@ f v:n>n;- 0 v -- OK: binary subtract: 0 - v = -v The lexer splits a glued negative literal back into `Minus + Number` when the previous token is one of `;`, `\n`, `=`, `{`, `(`, or `-`. The `-` context covers the operand slot of an outer prefix-minus, so `- -0 a b` lexes as `-, -, 0, a, b` and parses as `Subtract(Subtract(0, a), b)` = `-a - b` rather than tripping `ILO-P020`. Negative literals after an Ident, `[`, or another prefix binop (`+`, `*`, `/`) stay glued so call args (`at xs -1`), list literals (`[-2 1 3]`), and binary operands (`+a -3`) read naturally. +**Subtraction spacing convention**: for general subtraction at statement position, write `a - b` with spaces on **both** sides. `a -b` (glued, no space before the `-`) is not a binary subtract: the lexer packs `-b` into a negative-literal token because the previous token (`a`, an Ident) is one of the keep-glued contexts above. That's deliberate so call args and list elements read naturally, but it means `0 -1.5` is a parse error (`ILO-P001: expected declaration, got number `-1.5`` with a tailored hint pointing at this rule). For a bare negative value as an expression, wrap in parens: `(-1.5)`. + --- ## String Literals diff --git a/ai.txt b/ai.txt index a3cdf007..14f81267 100644 --- a/ai.txt +++ b/ai.txt @@ -4,7 +4,7 @@ FUNCTIONS: : ...>; No parens around param TYPES: `n`=number (f64) `t`=text (string) `b`=bool `_`=any/unknown (wildcard type) `L n`=list of number `R n t`=result: ok=number, err=text `O n`=optional number (nil or n) `M t n`=map from text keys to numbers `S red green blue`=sum type - one of named text variants `F n t`=function type: takes n, returns t (used in HOF params) `order`=named type `a`=type variable - any single lowercase letter except n, t, b [Optional (`O T`)] `O T` accepts either `nil` or a value of type `T`. f x:O n>n;??x 0 -- unwrap optional or default to 0 g>O n;nil -- returns nil (valid O n) h>O n;42 -- returns 42 (valid O n) `??x default` - nil-coalesce: returns `x` if non-nil, else `default`. Unwraps `O T` to `T`. [Sum types (`S a b c`)] Closed set of named text variants. Verifier-enforced; runtime value is always `t`. color x:S red green blue > t ?x{red:"ff0000";green:"00ff00";blue:"0000ff"} Sum types are compatible with `t` - a sum value can be passed to any `t` parameter. [Map type (`M k v`)] Dynamic key-value collection. Keys are typed: text (`t`) or integer (`n`). `Int(1)` and `Text("1")` are distinct keys. mmap -- empty map mset m k v -- return new map with key k set to v mget m k -- value at key k, or nil mget-or m k default -- value at key k, or default if missing (never nil) mhas m k -- b: true if key exists mkeys m -- L t: sorted list of keys mvals m -- L v: values sorted by key mpairs m -- L (L _): sorted [k, v] pairs; mpairs m == zip (mkeys m) (mvals m) mdel m k -- return new map with key k removed len m -- number of entries Numeric keys work directly - no `str` conversion needed. Float keys floor to `i64` at the builtin boundary (matching `at xs i`); NaN/Infinity raise at runtime. idx=mmap idx=mset idx 7 "seven" -- M n t, integer key mget idx 7 -- "seven" mhas idx 7 -- true mhas idx "7" -- false (Int and Text are distinct) `jdmp` stringifies numeric keys for JSON output (JSON object keys are always strings). The round-trip via `jpar` is lossy - numeric keys come back as text. Example: scores>M t n m=mmap m=mset m "alice" 99 m=mset m "bob" 87 mget m "alice" -- 99 [Type variables] A single lowercase letter (other than `n`, `t`, `b`) in type position is a type variable, treated as `unknown` during verification. Used for higher-order function signatures: identity x:a>a;x apply f:F a a x:a>a;f x Type variables provide weak generics - the verifier accepts any type for `a` without consistency checking across call sites. [Inline lambdas] Pass a function literal directly to a HOF instead of defining a one-off top-level helper: by-dist xs:L n>L n;srt (x:n>n;abs x) xs nonempty ws:L t>L t;flt (s:t>b;>(len s) 0) ws sumsq xs:L n>n;fld (a:n x:n>n;+a *x x) xs 0 Syntax: `(: ...>;)`. Same shape as a top-level function declaration, wrapped in parens, no name. **Phase 1 (no captures)** lifts the literal to a synthetic top-level decl and works across every engine (tree, VM, Cranelift JIT, AOT). The body's free variables must all be params, locals defined inside the lambda body, or known top-level fns. **Phase 2 (closure capture)** lets the body reference variables from the enclosing scope: f xs:L n thr:n>L n;flt (x:n>b;>x thr) xs -- captures `thr` Phase 2 captures run natively on every engine: the tree interpreter, the register VM, the Cranelift JIT, and the Cranelift AOT backend. Each free variable is snapshot by value at the call site (`Expr::MakeClosure`) and appended to the call frame's arg slice on dispatch. The AOT backend additionally embeds the postcard-serialised `CompiledProgram` into the binary's `.rodata` and publishes TLS pointers on startup, so dispatch helpers can re-enter the VM on user-fn callbacks. The ctx-arg form (`srt fn ctx xs`) remains the cross-engine alternative when you want explicit state without forming a closure. NAMING: Short names everywhere. 1–3 chars. `order`=`ord`=truncate `customers`=`cs`=consonants `data`=`d`=single letter `level`=`lv`=drop vowels `discount`=`dc`=initials `final`=`fin`=first 3 `items`=`its`=first 3 Function names follow the same rules. Field names in constructors and external tool names keep their full form - they define the public interface. [Identifier syntax] Identifiers are lowercase ASCII only, optionally with hyphenated segments. Formally: `[a-z][a-z0-9]*(-[a-z0-9]+)*`. Capital letters and underscores are rejected at the binding and call site. run -- OK run-d -- OK (hyphen separates segments) r2 -- OK (digit after first letter) runD -- ERROR (capital letter) RunD -- ERROR (leading capital) run_d -- ERROR (underscore not allowed in bindings) -run -- ERROR (must start with a letter) `runD` in the interactive CLI surfaces as `ILO-L003 unexpected token` with a suggestion to use `run-d` or `rund`. The constraint is intentional: a single lexical shape per identifier keeps the token stream predictable for agents and avoids style debates over camelCase vs snake_case vs kebab-case. The only place capital letters and underscores are accepted is **after `.` or `.?`** at field-access position, so heterogeneous JSON keys from real APIs work without rewriting. See [Field names at dot-access](#field-names-at-dot-access) for the full list of post-dot relaxations (`r.URL`, `r.AccessKey`, `r.user_name`, etc.). Binding names (`AccessKey = ...`) and function names (`AccessKey x:n>n;...`) still error. [Reserved words] The following identifiers are reserved and cannot be used as names: `if`, `return`, `let`, `fn`, `def`, `var`, `const`. Using them produces a friendly error with the ilo equivalent: -- ERROR: `if` is a reserved word. Use: ?cond{true:...;false:...} -- ERROR: `return` is a reserved word. Last expression is the return value. -- ERROR: `let` is a reserved word. Use: name = expr -- ERROR: `fn`/`def` is a reserved word. Use: name param:type > rettype; body Builtin names (`flat`, `frq`, `map`, `flt`, `cat`, `len`, `srt`, `hd`, `tl`, `ord`, `fld`, `lst`, ...) are also rejected as user-function names and as local-binding LHS. Without this, calls to the user fn or use sites of the local binding silently mis-dispatch to the builtin and surface as a confusing `ILO-T006` arity mismatch. The parser intercepts at the declaration site with ILO-P011 and a rename hint: flat n:n>n;n -- ERROR ILO-P011: `flat` is a builtin and cannot be used as a function name -- hint: rename to something like `myflat` or `flatof`. main>n;flat=cat xs " ";spl flat ". " -- ERROR ILO-P011: `flat` is a builtin and cannot be used as a binding name -- hint: rename to something like `myflat` or `flatv`. [Reserved namespaces] Short builtin names are precious surface and ilo reserves a stable subset of them. To save agents (and their carry-forward scripts) from "what got reserved this release?" debugging cycles, the language publishes the full short-name reserve list plus a forward-compatibility rule for future builtins. **Currently reserved short names (1-3 characters).** Every name in this list is a builtin today and triggers `ILO-P011` if used as a binding or user-function name: 1-char e 2-char at hd pi tl rd wr ct 3-char abs avg cap cat cel chr cos det dot env exp fft fld flr flt fmt frq get grp has inv len log lsd lst lwr map max min mod now num ord pow pst rdb rdl rev rgx rng rnd rou run sin slc spl srt str sum tan tau trm unq upr wra wrl zip All builtin aliases (`head`, `length`, `filter`, `concat`, `tail`, `sort`, `reverse`, `flatten`, `contains`, `group`, `average`, `print`, `trim`, `split`, `format`, `regex`, `read`, `readlines`, `readbuf`, `write`, `writelines`, `lset`, `floor`, `ceil`, `round`, `rand`, `random`, `rng`, `string`, `number`, `slice`, `unique`, `fold`) are reserved with the same shadow-prevention semantics as canonical builtin names. Binding an alias name or using it as a user-function name fires `ILO-P011` at parse time with the canonical form in the diagnostic, since the call-site rewrite to the canonical builtin silently bypasses any user binding of the same name. Previously only `rng` and `rand` had individual guards; as of 0.12.1 every alias in the table above is covered by a single `resolve_alias` check, so new aliases automatically inherit the protection when added to the table. Longer builtin names (`acos`, `asin`, `atan`, `flat`, `take`, `drop`, `mget`, `mset`, `mmap`, `prnt`, `mapr`, `solve`, `clamp`, `cumsum`, `cprod`, `median`, `matmul`, `range`, `window`, `chunks`, `walk`, `glob`, `prod`, `fsize`, `mtime`, `isfile`, `isdir`, …) are also reserved and rejected by `ILO-P011`, but the short-name namespace above is where carry-forward scripts most often collide, so it gets explicit enumeration. **Forward-compatibility rule.** Future ilo releases add new builtins under names **4 characters or longer**. A 2-character name that is not on this list today is safe to use as a binding or function name and stays safe across releases. A 3-character name that is not on this list is _highly likely_ to stay safe but is not a hard promise - the 3-char surface is already dense, and a rare ergonomic win may justify an addition, called out in the changelog. This gives agents a deterministic safe-name strategy: **2 chars**: any unreserved 2-char name is permanently fine for bindings (`ce` for "category", `ix` for index, `mn` for "mean", `pq` for "priority queue", …). Names on the reserved list above never get removed. **3 chars**: prefer unreserved 3-char names where possible. If a future release reserves one, the migration is a 1-character rename plus a changelog entry. **4+ chars**: always safe. New builtins land here first; any short alias is added later only if the long name is unambiguous and the short doesn't shadow a plausible user binding. When a collision does happen, `ILO-P011` surfaces it at the binding site with a rename suggestion - never silently mis-dispatches at the call site (see the `flat=cat xs " "` example above). Combined with the reserve list, that turns every name-collision incident into a single-character rename instead of a debugging spiral. [Cross-language gotchas] Common shapes reached for from other languages. The parser and lexer surface each with a friendly hint: `AND a b`, `OR a b`, `NOT a`=`&a b`, `|a b`, `!a`=`ILO-L001` `=a b`=`<=a b`, `>=a b` (single token)=`ILO-P003` `f=fn x:n>n;+x 1` (lambda)=`(x:n>n;+x 1)` (parenthesised lambda)=`ILO-P009` `\x{+x 1}` (Haskell/Rust lambda)=`(x:n>n;+x 1)` (parenthesised lambda)=`ILO-L001` `main:>n;body`=`main>n;body` (no `:` before `>`)=`ILO-P003` Multi-line body without braces=`@k xs{body}`, `cond{body}` on one line=`ILO-P003` `cond{^"err"}` braced-cond=Braceless `cond ^"err"` for early return=hint only `- -*a b *c d` (double-minus)=`- 0 +*a b *c d` (negate the sum)=`ILO-P021` `[k fmt2 v 2]` (call in list)=`[k (fmt2 v 2)]` or bind-first=`ILO-P101` Each case fires a hint pointing at the canonical form; the agent's first retry should be the right one. Identifier-shaped collisions with builtin names (`len=...`, `sin=...`) are rejected with `ILO-P011` plus a rename suggestion. The list-literal call trap (`ILO-P101`) catches the case where a variadic builtin (`fmt`, `fmt2`) appears bare inside `[...]`. Fixed-arity builtins (`str`, `at`, `map`, ...) auto-expand to a call as one element, but variadic ones can't (the parser doesn't know where their args end), so the bare form would silently fall through as multiple elements with the builtin name as an undefined Ref. Fix by wrapping the call in parens (`[k (fmt2 v 2)]`) or binding first. The double-minus trap (`ILO-P021`) catches the silent-miscompile shape `- - a b c d` for `` in `{+,*,/}`. Read intuitively as `-(a*b) - (c*d)` but parses as `-((a*b) - (c*d)) = -(a*b) + (c*d)` because the inner `-` greedily consumes both prefix-binop groups as binary subtract and the outer `-` falls back to unary negate. Fix by negating the sum (`- 0 +*a b *c d`) or binding first (`p=*a b;q=*c d;- 0 +p q`). Single-atom variants like `- -a b` remain accepted since they're unambiguous. COMMENTS: -- full line comment +a b -- end of line comment -- no multi-line comments; use consecutive -- lines -- like this Single-line only. `--` to end of line. No multi-line comment syntax - newlines are a human display concern, not a language concern. An entire ilo program can be one line. Use consecutive `--` lines when humans need multi-line comments. Stripped at the lexer level before parsing - comments produce no AST nodes and cost zero runtime tokens. Generating `--` costs 1 LLM token, so comments are essentially free. **Gotcha:** `--x 1` is a comment, not "negate (x minus 1)". The lexer matches `--` greedily as a comment and eats the rest of the line. To negate a subtraction, use a space or bind first: -- DON'T: --x 1 (comment, not negate-subtract) -- DO: - -x 1 (space separates the two minus operators) -- DO: r=-x 1;-r (bind first) -OPERATORS: Both prefix and infix notation are supported. **Prefix is preferred** - it is the token-optimal form that eliminates parentheses and produces denser code. Infix is available for readability when needed. [Binary] `+a b`=`a + b`=add / concat / list concat=`n`, `t`, `L` `+=a v`=append to list (returns new list, see [Append semantics](#append-semantics-+=))=`L` `-a b`=`a - b`=subtract=`n` `*a b`=`a * b`=multiply=`n` `/a b`=`a / b`=divide=`n` `=a b`=`a == b`=equal (prefix `=` is preferred; `==a b` also accepted)=any `!=a b`=`a != b`=not equal=any `>a b`=`a > b`=greater than=`n`, `t` `=a b`=`a >= b`=greater or equal=`n`, `t` `<=a b`=`a <= b`=less or equal=`n`, `t` `&a b`=`a & b`=logical AND (short-circuit)=any (truthy) `|a b`=`a | b`=logical OR (short-circuit)=any (truthy) [Append semantics (`+=`)] `+=xs v` is **pure-shaped**, despite the imperative-looking syntax. It returns a new list with `v` appended and does **not** mutate `xs` in the caller's scope. It works in every position a value-producing expression works: -- 1. Rebind (canonical accumulator pattern) xs=[];@i 0..3{xs=+=xs i};xs -- [0, 1, 2] -- 2. Non-rebind assignment (xs preserved) xs=[1, 2, 3];ys=+=xs 99 -- xs is still [1, 2, 3]; ys is [1, 2, 3, 99] -- 3. Pipeline / argument position len +=xs 99 -- length of [xs..., 99] sum +=xs 99 -- sum of [xs..., 99] The rebind shape `xs = +=xs v` is the standard foreach-build accumulator. When the binding is RC=1 the engines mutate the underlying buffer in place (amortised O(1) per push) - but this is a behind-the-scenes optimisation. To any observer the operation is still functional: nothing outside the rebind sees the old `xs`. The non-rebind shape `ys = +=xs v` always allocates a fresh list and leaves `xs` untouched, so source aliases are safe. There is no separate `push` builtin. `+=` covers every use case and is shorter; adding an alias would mean two ways to spell the same operation, costing reasoning tokens and surface area. [Unary] `-x`=negate=`n` `!x`=logical NOT=any (truthy) [Special infix] `a??b`=nil-coalesce (if a is nil, return b)=any `a>>f`=pipe (desugar to `f(a)`)=any [Prefix nesting (no parens needed)] +*a b c -- (a * b) + c *a +b c -- a * (b + c) >=+x y 100 -- (x + y) >= 100 -*a b *c d -- (a * b) - (c * d) The outer prefix op binds the inner prefix subexpression as its **left** operand, regardless of operator precedence. With two same-precedence ops side by side this is easy to misread: */a b c -- (a/b) * c ← NOT (a*b)/c /*a b c -- (a*b) / c ← NOT (a/b)*c +-a b c -- (a-b) + c ← NOT (a+b)-c -+a b c -- (a+b) - c ← NOT (a-b)+c The runtime emits a `hint:` diagnostic when one of these four pairs appears at a prefix position, since the parse order disagrees with the natural left-to-right reading. To force the other grouping, swap the ops or bind the inner result first: -- Want (a*b)/c with a=6, b=2, c=3: r=*a b;/r c -- bind, then divide → 4 /*a b c -- equivalent, swapping the prefix-pair order [Infix precedence] Standard mathematical precedence (higher binds tighter): 6=`*` `/` 5=`+` `-` `+=` 4=`>` `<` `>=` `<=` 3=`=` `!=` 2=`&` 1=`|` Function application binds tighter than all infix operators: f a + b -- (f a) + b, NOT f(a + b) x * y + 1 -- (x * y) + 1 (x + y) * 2 -- parens override precedence Each nested prefix operator saves 2 tokens (no `(` `)` needed). Flat prefix like `+a b` saves 1 char vs `a + b`. Across 25 expression patterns, prefix notation saves **22% tokens** and **42% characters** vs infix. See [research/explorations/prefix-vs-infix/](research/explorations/prefix-vs-infix/) for the full benchmark. Disambiguation: `-` followed by one atom is unary negate, followed by two atoms is binary subtract. [Operands] Operator operands are **atoms** (literals, refs, field access), **nested prefix operators**, or **known-arity function calls**. The prefix-binop operand parser dispatches to call parsing when the ident at the cursor is a known-arity user fn or builtin AND the next token can start another operand: wh >len q 0{body} -- parses as wh > (len q) 0 { body } +f g h -- if f is 1-arity: BinOp(+, Call(f, [g]), h) -lnx 5 lnx 3 -- BinOp(-, Call(lnx, [5]), Call(lnx, [3])) dbl 5 -- Negate(Call(dbl, [5])) - unary on a call This parallels the `??` precedent: `??x default` accepts a call expression on the value side. Applies to every prefix-binop family member - `+`, `-`, `*`, `/`, comparisons, `&`, `|`, `+=` - and to unary negate when the call consumes the only operand. The same expansion also applies to the then/else slots of the prefix-ternary family (`?=cond a b`, `?>cond a b`, …) and the `?h cond a b` keyword form, so `?h =a b sev sc "NONE"` parses `sev sc` as a nested call without parens or a bind-first. Bare locals that shadow a user fn name still resolve via `Ref` rather than expanding into a zero-arg call, so `&e f{...}` where `f` is a local still parses as the bool operator with two refs. When the call expansion isn't available (the ident is a local that shadows a fn name, or the call's arity doesn't fit the remaining tokens), bind the call result first: r=fac p;*n r -- bind, then operate - always unambiguous **Negative literals vs binary minus**: the lexer greedily includes a leading `-` into number tokens. `-1`, `-7`, `-0` are all number literals at fresh-expression positions. To subtract from zero at the start of a statement, use a space: `- 0 v` (Minus token, then `0`, then `v`). f v:n>n;-0 v -- WRONG: -0 is Number(-0.0); v is a stray token f v:n>n;- 0 v -- OK: binary subtract: 0 - v = -v The lexer splits a glued negative literal back into `Minus + Number` when the previous token is one of `;`, `\n`, `=`, `{`, `(`, or `-`. The `-` context covers the operand slot of an outer prefix-minus, so `- -0 a b` lexes as `-, -, 0, a, b` and parses as `Subtract(Subtract(0, a), b)` = `-a - b` rather than tripping `ILO-P020`. Negative literals after an Ident, `[`, or another prefix binop (`+`, `*`, `/`) stay glued so call args (`at xs -1`), list literals (`[-2 1 3]`), and binary operands (`+a -3`) read naturally. +OPERATORS: Both prefix and infix notation are supported. **Prefix is preferred** - it is the token-optimal form that eliminates parentheses and produces denser code. Infix is available for readability when needed. [Binary] `+a b`=`a + b`=add / concat / list concat=`n`, `t`, `L` `+=a v`=append to list (returns new list, see [Append semantics](#append-semantics-+=))=`L` `-a b`=`a - b`=subtract=`n` `*a b`=`a * b`=multiply=`n` `/a b`=`a / b`=divide=`n` `=a b`=`a == b`=equal (prefix `=` is preferred; `==a b` also accepted)=any `!=a b`=`a != b`=not equal=any `>a b`=`a > b`=greater than=`n`, `t` `=a b`=`a >= b`=greater or equal=`n`, `t` `<=a b`=`a <= b`=less or equal=`n`, `t` `&a b`=`a & b`=logical AND (short-circuit)=any (truthy) `|a b`=`a | b`=logical OR (short-circuit)=any (truthy) [Append semantics (`+=`)] `+=xs v` is **pure-shaped**, despite the imperative-looking syntax. It returns a new list with `v` appended and does **not** mutate `xs` in the caller's scope. It works in every position a value-producing expression works: -- 1. Rebind (canonical accumulator pattern) xs=[];@i 0..3{xs=+=xs i};xs -- [0, 1, 2] -- 2. Non-rebind assignment (xs preserved) xs=[1, 2, 3];ys=+=xs 99 -- xs is still [1, 2, 3]; ys is [1, 2, 3, 99] -- 3. Pipeline / argument position len +=xs 99 -- length of [xs..., 99] sum +=xs 99 -- sum of [xs..., 99] The rebind shape `xs = +=xs v` is the standard foreach-build accumulator. When the binding is RC=1 the engines mutate the underlying buffer in place (amortised O(1) per push) - but this is a behind-the-scenes optimisation. To any observer the operation is still functional: nothing outside the rebind sees the old `xs`. The non-rebind shape `ys = +=xs v` always allocates a fresh list and leaves `xs` untouched, so source aliases are safe. There is no separate `push` builtin. `+=` covers every use case and is shorter; adding an alias would mean two ways to spell the same operation, costing reasoning tokens and surface area. [Unary] `-x`=negate=`n` `!x`=logical NOT=any (truthy) [Special infix] `a??b`=nil-coalesce (if a is nil, return b)=any `a>>f`=pipe (desugar to `f(a)`)=any [Prefix nesting (no parens needed)] +*a b c -- (a * b) + c *a +b c -- a * (b + c) >=+x y 100 -- (x + y) >= 100 -*a b *c d -- (a * b) - (c * d) The outer prefix op binds the inner prefix subexpression as its **left** operand, regardless of operator precedence. With two same-precedence ops side by side this is easy to misread: */a b c -- (a/b) * c ← NOT (a*b)/c /*a b c -- (a*b) / c ← NOT (a/b)*c +-a b c -- (a-b) + c ← NOT (a+b)-c -+a b c -- (a+b) - c ← NOT (a-b)+c The runtime emits a `hint:` diagnostic when one of these four pairs appears at a prefix position, since the parse order disagrees with the natural left-to-right reading. To force the other grouping, swap the ops or bind the inner result first: -- Want (a*b)/c with a=6, b=2, c=3: r=*a b;/r c -- bind, then divide → 4 /*a b c -- equivalent, swapping the prefix-pair order [Infix precedence] Standard mathematical precedence (higher binds tighter): 6=`*` `/` 5=`+` `-` `+=` 4=`>` `<` `>=` `<=` 3=`=` `!=` 2=`&` 1=`|` Function application binds tighter than all infix operators: f a + b -- (f a) + b, NOT f(a + b) x * y + 1 -- (x * y) + 1 (x + y) * 2 -- parens override precedence Each nested prefix operator saves 2 tokens (no `(` `)` needed). Flat prefix like `+a b` saves 1 char vs `a + b`. Across 25 expression patterns, prefix notation saves **22% tokens** and **42% characters** vs infix. See [research/explorations/prefix-vs-infix/](research/explorations/prefix-vs-infix/) for the full benchmark. Disambiguation: `-` followed by one atom is unary negate, followed by two atoms is binary subtract. [Operands] Operator operands are **atoms** (literals, refs, field access), **nested prefix operators**, or **known-arity function calls**. The prefix-binop operand parser dispatches to call parsing when the ident at the cursor is a known-arity user fn or builtin AND the next token can start another operand: wh >len q 0{body} -- parses as wh > (len q) 0 { body } +f g h -- if f is 1-arity: BinOp(+, Call(f, [g]), h) -lnx 5 lnx 3 -- BinOp(-, Call(lnx, [5]), Call(lnx, [3])) dbl 5 -- Negate(Call(dbl, [5])) - unary on a call This parallels the `??` precedent: `??x default` accepts a call expression on the value side. Applies to every prefix-binop family member - `+`, `-`, `*`, `/`, comparisons, `&`, `|`, `+=` - and to unary negate when the call consumes the only operand. The same expansion also applies to the then/else slots of the prefix-ternary family (`?=cond a b`, `?>cond a b`, …) and the `?h cond a b` keyword form, so `?h =a b sev sc "NONE"` parses `sev sc` as a nested call without parens or a bind-first. Bare locals that shadow a user fn name still resolve via `Ref` rather than expanding into a zero-arg call, so `&e f{...}` where `f` is a local still parses as the bool operator with two refs. When the call expansion isn't available (the ident is a local that shadows a fn name, or the call's arity doesn't fit the remaining tokens), bind the call result first: r=fac p;*n r -- bind, then operate - always unambiguous **Negative literals vs binary minus**: the lexer greedily includes a leading `-` into number tokens. `-1`, `-7`, `-0` are all number literals at fresh-expression positions. To subtract from zero at the start of a statement, use a space: `- 0 v` (Minus token, then `0`, then `v`). f v:n>n;-0 v -- WRONG: -0 is Number(-0.0); v is a stray token f v:n>n;- 0 v -- OK: binary subtract: 0 - v = -v The lexer splits a glued negative literal back into `Minus + Number` when the previous token is one of `;`, `\n`, `=`, `{`, `(`, or `-`. The `-` context covers the operand slot of an outer prefix-minus, so `- -0 a b` lexes as `-, -, 0, a, b` and parses as `Subtract(Subtract(0, a), b)` = `-a - b` rather than tripping `ILO-P020`. Negative literals after an Ident, `[`, or another prefix binop (`+`, `*`, `/`) stay glued so call args (`at xs -1`), list literals (`[-2 1 3]`), and binary operands (`+a -3`) read naturally. **Subtraction spacing convention**: for general subtraction at statement position, write `a - b` with spaces on **both** sides. `a -b` (glued, no space before the `-`) is not a binary subtract: the lexer packs `-b` into a negative-literal token because the previous token (`a`, an Ident) is one of the keep-glued contexts above. That's deliberate so call args and list elements read naturally, but it means `0 -1.5` is a parse error (`ILO-P001: expected declaration, got number `-1.5`` with a tailored hint pointing at this rule). For a bare negative value as an expression, wrap in parens: `(-1.5)`. STRING LITERALS: Text values are written in double quotes. Escape sequences: `\n`=newline (0x0A) `\t`=tab (0x09) `\r`=carriage return (0x0D) `\f`=form feed (0x0C, PDF page separator) `\b`=backspace (0x08) `\v`=vertical tab (0x0B) `\a`=bell (0x07) `\0`=null (0x00) `\"`=literal double quote `\\`=literal backslash `\/`=literal forward slash (JSON passthrough) Unknown escapes (e.g. `\z`) preserve the backslash + char verbatim. "hello\nworld" -- two-line string "col1\tcol2" -- tab-separated spl text "\n" -- split file content into lines spl pdf "\f" -- split pdftotext output into pages BUILTINS: Called like functions, compiled to dedicated opcodes. `len x`=length of string (bytes) or list (elements)=`n` `str n`=number to text (integers format without `.0`)=`t` `num t`=text to number; trims leading/trailing ASCII whitespace before parsing (Err if unparseable)=`R n t` `abs n`=absolute value=`n` `min a b`=minimum of two numbers=`n` `min xs`=minimum element of a numeric list (error if empty)=`n` `max a b`=maximum of two numbers=`n` `max xs`=maximum element of a numeric list (error if empty)=`n` `mod a b`=C-style signed remainder; result sign matches dividend. Errors on zero divisor. For negative inputs use `fmod`.=`n` `fmod a b`=Floor-mod: always non-negative when `b > 0`. Equivalent to Python `a % b`. Errors on zero divisor. NaN/Inf inputs propagate via IEEE 754 (same policy as every other math builtin). Use instead of `(a % b + b) % b` workarounds for weekday/timezone arithmetic.=`n` `flr n`=floor (round toward negative infinity)=`n` `cel n`=ceiling (round toward positive infinity)=`n` `rnd`=random float in [0, 1). NOT round - for round use `rou` (alias: `round`). Aliases: `rand`, `random`.=`n` `rnd a b`=random integer in [a, b] (inclusive)=`n` `now`=current Unix timestamp (seconds)=`n` `now-ms`=current Unix timestamp (milliseconds)=`n` `get url`=HTTP GET=`R t t` `get url headers`=HTTP GET with custom headers (`M t t` map)=`R t t` `get-to url timeout-ms`=HTTP GET with explicit timeout (milliseconds); Err if deadline exceeded=`R t t` `pst url body`=HTTP POST with text body (renamed from `post` in 0.12.0)=`R t t` `pst url body headers`=HTTP POST with body and custom headers (`M t t` map)=`R t t` `pst-to url body timeout-ms`=HTTP POST with explicit timeout (milliseconds); Err if deadline exceeded=`R t t` `run cmd argv`=spawn `cmd` with argv list — see [Process spawn](#process-spawn) for the no-shell-no-glob security model=`R (M t t) t` `env key`=read environment variable=`R t t` `env-all`=snapshot the full process environment as `M t t`=`R (M t t) t` `rd path`=read file; format auto-detected from extension (`.csv`/`.tsv`→grid, `.json`→graph, else text)=`R _ t` `rd path fmt`=read file with explicit format override (`"csv"`, `"tsv"`, `"json"`, `"raw"`)=`R _ t` `rdl path`=read file as list of lines=`R (L t) t` `rdin`=read all of stdin as text; Err on I/O failure or WASM=`R t t` `rdinl`=read stdin as list of lines (newlines stripped); Err on I/O failure or WASM=`R (L t) t` `lsd dir`=list directory entries (filenames only, not full paths; sorted lexicographically; includes both files and subdirs; empty dirs return `[]`, not Err). Renamed from `ls` in 0.12.1 so the natural `ls=rdl! p` binding for "lines" stays free.=`R (L t) t` `walk dir`=recursive depth-first traversal; paths returned relative to `dir`, sorted; includes both file and directory entries; symlinks not followed. Unreadable subdirectories (e.g. permission denied) are silently skipped so one locked sibling does not poison the whole walk; an unreadable root still returns `Err`=`R (L t) t` `glob dir pat`=shell-style filter under `dir`: `*`/`?`/`[abc]` within a path segment, `**` across segments; relative-path output, sorted; no matches returns `[]` (not Err). Shares `walk`'s traversal so unreadable subdirectories are skipped silently=`R (L t) t` `dirname path`=POSIX-style parent directory. `dirname "/a/b/c.txt"` → `"/a/b"`, `dirname "/"` → `"/"`, `dirname "foo.txt"` → `""` (POSIX returns `"."` here; ilo returns `""` so `pathjoin [dirname p basename p]` round-trips a plain filename without a phantom `./` prefix), `dirname "foo/"` → `""` (trailing slash stripped, then no directory component remains), `dirname "/a"` → `"/"`. Pure text op, no I/O, no Result. Unix forward-slash semantics; Windows separator handling is a 0.13.0 concern=`t` `basename path`=POSIX-style final path segment. `basename "/a/b/c.txt"` → `"c.txt"`, `basename "/"` → `"/"`, `basename "foo/"` → `"foo"` (trailing slash stripped), `basename ""` → `""`. Pure text op, total=`t` `pathjoin parts`=join a list of path segments with `/`, collapsing duplicate separators at joints and dropping empty segments. `pathjoin ["a" "b" "c.txt"]` → `"a/b/c.txt"`, `pathjoin ["a/" "/b/" "c.txt"]` → `"a/b/c.txt"`, `pathjoin []` → `""`, `pathjoin ["/" "a"]` → `"/a"` (leading absolute root preserved). List form (not variadic) so arity inference stays predictable; matches `cat xs sep`'s shape=`t` `fsize path`=file size in bytes (follows symlinks); `Err` on missing, permission-denied, or path-is-directory. Paired predicate `isfile` collapses the error tier into `false` for one-token branches=`R n t` `mtime path`=last modification time as Unix epoch seconds (`f64`, fractional preserved; follows symlinks); `Err` on missing or permission-denied. Pairs with `now` for "is this file older than N seconds" checks=`R n t` `isfile path`=`true` iff `path` resolves to a regular file (follows symlinks). Missing, permission-denied, or non-file all collapse to `false` — natural shape for `?isfile p{…}`. Asymmetric vs `fsize`/`mtime` (which return `R n t`) by design: predicates want a one-token branch, size/mtime callers want to distinguish missing from perm-denied=`b` `isdir path`=`true` iff `path` resolves to a directory (follows symlinks). Same `false`-on-failure collapse as `isfile`=`b` `rdb s fmt`=parse string/buffer in given format - for data from HTTP, env vars, etc.=`R _ t` `wr path s`=write text to file (overwrite)=`R t t` `wr path data "csv"`=write list-of-lists as CSV (with proper quoting)=`R t t` `wr path data "tsv"`=write list-of-lists as TSV=`R t t` `wr path data "json"`=write any value as pretty JSON=`R t t` `wra path s`=append text to file (create if missing)=`R t t` `wrl path xs`=write list of lines to file (joins with `\n`)=`R t t` `trm s`=trim leading and trailing whitespace=`t` `spl t sep`=split text by separator=`L t` `fmt tmpl args…`=format string - bare `{}` placeholders only, filled left-to-right. Printf-style specs (`{:06d}`, `{:.3f}`) are rejected; compose `fmt2` for decimal precision and `padl` for width/padding. Literal templates require `{}`-count == arg-count (verifier rejects mismatches with `ILO-T013`). Lists are formatted as a single value, not splatted: `fmt "{} {}" [a, b]` is an error - use `fmt "{} {}" a b` instead=`t` `cat xs sep`=join list of text with separator=`t` `has xs v`=membership test (list: element, text: substring)=`b` `hd xs`=head (first element/char) of list or text=element / `t` `tl xs`=tail (all but first) of list or text=`L` / `t` `rev xs`=reverse list or text=same type `srt xs`=sort list (all-number or all-text) or text chars=same type `srt fn xs`=sort list by key function (returns number or text key)=`L` `unq xs`=remove duplicates, preserve order (list or text chars)=same type `slc xs a b`=slice list or text from index a to b (a, b accept negative indices counting from end; bounds clamp)=same type `jpth json path`=JSON dot-path lookup, dot-separated keys + numeric array indices (e.g. `"a.b.0.c"`), not JSONPath - leading `$`, `*`, or `[...]` rejected with a diagnostic. Result is typed: arrays → list, objects → record, scalars → matching primitive.=`R _ t` `jkeys json path`=sorted top-level keys of the JSON object at `path` (empty path = root). Err if the value at the path is not an object.=`R (L t) t` `jdmp value`=serialise ilo value to JSON text=`t` `prnt value`=print value to stdout, return it unchanged (passthrough)=same type `jpar text`=parse JSON text into ilo values=`R _ t` `jpar-list text`=parse JSON text, assert top-level is array, return typed list=`R (L _) t` `grp fn xs`=group list by key function=`M t (L a)` `flat xs`=flatten one level of nesting=`L a` `sum xs`=sum of numeric list (0 for empty)=`n` `prod xs`=product of numeric list (1 for empty)=`n` `avg xs`=mean of numeric list (error if empty)=`n` `rgx pat s`=regex: no groups→all matches; groups→first match captures=`L t` `mmap`=create empty map=`M t _` `mget m k`=value at key k (nil if missing)=element or nil `mset m k v`=new map with key k set to v=`M k v` `mhas m k`=true if key exists=`b` `mkeys m`=sorted list of keys=`L t` `mvals m`=values sorted by key=`L v` `mpairs m`=sorted [k, v] pairs; `mpairs m == zip (mkeys m) (mvals m)`=`L (L _)` `mdel m k`=new map with key k removed=`M k v` `mget-or m k default`=value at key k, or `default` if missing (never nil; default type must match value type)=`v` `at xs i`=i-th element of list or text (0-indexed; negative counts from end; float `i` auto-floors)=element `lget-or xs i default`=element at index `i`, or `default` if OOB (negative indices like `at`; never errors on OOB)=`a` `lst xs i v`=new list with index `i` set to `v` (list update; alias: `lset`)=`L a` `take n xs`=first `n` elements/chars of list or text (n>=0 truncates if n>len; n<0 keeps all but the last `abs n`, Python `xs[:n]`)=same type `drop n xs`=skip first `n` elements/chars (n>=0 returns the rest; n<0 keeps only the last `abs n`, Python `xs[n:]`)=same type `rsrt xs`=sort descending (list or text chars)=same type `rsrt fn xs`=sort descending by key function (returns number or text key)=`L` `rsrt fn ctx xs`=sort descending by key function with explicit ctx arg (closure-bind alternative; `fn` takes `(elem, ctx)`)=`L` `uniqby fn xs`=dedupe by key function (first occurrence wins)=`L a` `zip xs ys`=pairwise pairs of two lists; truncates to shorter input=`L (L _)` `enumerate xs`=pair each element with its index → `[[i, v], ...]`=`L (L _)` `range a b`=half-open numeric range `[a, a+1, ..., b-1]`; empty when `a >= b`=`L n` `map fn xs`=apply `fn` to each element=`L b` `flt fn xs`=keep elements where `fn x` is true=`L a` `ct fn xs`=count elements where `fn x` is true (avoids `len (flt fn xs)`'s intermediate list alloc)=`n` `fld fn xs init`=left fold: `fn (fn (fn init x0) x1) ...`=accumulator `flatmap fn xs`=map then flatten one level=`L b` `mapr fn xs`=map with short-circuit Result propagation: collects Ok values, returns first Err=`R (L b) e` `default-on-err r d`=unwrap `R T E` to `T`, returning `d` if Err; verifier requires `d` matches Ok type. Mirror of `??` for Result (`??` is nil-coalesce for `O T` only - use `default-on-err` for Result). Prefer over `?r{~v:v;^_:d}` when no error payload is needed. ILO-T040 when first arg is not `R T E` (hint steers at `??` only when first arg is Optional); ILO-T042 when the default's type doesn't match the Ok type; ILO-T041 when `??` is used on a Result. T041 is suppressed when the lhs type is `Unknown` (e.g. type-variable params) to avoid false positives on generic code=`T` `partition fn xs`=split list into `[passing, failing]` by predicate=`L (L a)` `chunks n xs`=non-overlapping chunks of size `n` (final chunk may be shorter)=`L (L a)` `window n xs`=sliding windows of size `n` (drops trailing partial; empty if n > len)=`L (L a)` `clamp x lo hi`=restrict `x` to `[lo, hi]` (lower bound wins when `lo > hi`)=`n` `cumsum xs`=running sum; output length matches input=`L n` `cprod xs`=running product; output length matches input=`L n` `frq xs`=frequency map of elements (keys are bare stringified values)=`M t n` `median xs`=median of numeric list=`n` `quantile xs p`=sample quantile (linear interp; `p` clamped to `[0, 1]`)=`n` `stdev xs`=sample standard deviation (divides by N-1)=`n` `variance xs`=sample variance (divides by N-1)=`n` `argmax xs`=index of the maximum element (first occurrence wins on ties; errors on empty list)=`n` `argmin xs`=index of the minimum element (first occurrence wins on ties; errors on empty list)=`n` `argsort xs`=sorted-index permutation ascending - stable sort, indices of smallest to largest (empty list returns `[]`)=`L n` `setunion a b`=set union of two lists (deduped, sorted output)=`L a` `setinter a b`=set intersection (deduped, sorted)=`L a` `setdiff a b`=set difference `a - b` (deduped, sorted)=`L a` `chars s`=explode a string into single-char strings (one per Unicode scalar)=`L t` `ord s`=Unicode codepoint of the first character of `s`=`n` `chr n`=single-character string for codepoint `n`=`t` `upr s`=uppercase (ASCII)=`t` `lwr s`=lowercase (ASCII)=`t` `cap s`=capitalise first char (ASCII)=`t` `padl s w`=left-pad to width `w` with spaces (no-op if already wider)=`t` `padr s w`=right-pad to width `w` with spaces (no-op if already wider)=`t` `padl s w pc`=left-pad to width `w` with 1-character string `pc` (e.g. `"0"` for sortable zero-padded keys)=`t` `padr s w pc`=right-pad to width `w` with 1-character string `pc` (e.g. `"."` for dot-leader alignment)=`t` `rgxall pat s`=every regex match as `L (L t)` (no-group: each match in a 1-elem list)=`L (L t)` `rgxall1 pat s`=flat first-capture-group convenience: 0 groups → `L t` of whole matches; 1 group → `L t` of capture-1 strings; 2+ groups errors=`L t` `rgxall-multi pats s`=multi-pattern flat-match: apply each pattern in `pats:L t` to `s`, concat all hits in pattern order; per-pattern semantics follow `rgxall1` (0 groups → whole matches; 1 group → capture-1 strings; 2+ groups errors)=`L t` `rgxsub pat repl s`=regex substitute all matches; `$1`, `$2`, ... reference capture groups=`t` `dtfmt epoch fmt`=format Unix epoch as text (strftime, UTC)=`R t t` `dtparse s fmt`=parse text to Unix epoch (strftime, UTC)=`R n t` `dtparse-rel s now`=parse relative-date phrase to epoch; `now` is the anchor epoch=`R n t` `dur-parse s`=parse human duration string ("3h 30m", "1 week 2 days", "1.5 hours", "90s") into seconds. Lenient: accepts abbreviations `s`/`m`/`h`/`d`/`w`, full names (singular + plural), decimal quantities, mixed sequences. Err if empty or no unit found=`R n t` `dur-fmt n`=format seconds as human-readable duration ("2h 42m", "1 day", "30s"). Drops zero parts; uses largest applicable units. Zero returns "0s". Negative values format with a leading "-"=`t` `rdjl path`=read JSONL file as `L (R _ t)`: one parse result per non-empty line=`L (R _ t)` `get-many urls`=concurrent HTTP GET fan-out (max 10 parallel), preserves order=`L (R t t)` `sleep ms`=pause current engine for `ms` milliseconds; returns nil=`_` `rou n`=round to nearest integer (banker's rounding)=`n` `rndn mu sigma`=one sample from normal distribution `N(mu, sigma)` (Box-Muller)=`n` `pow b e`=`b` raised to power `e`=`n` `sqrt n`=square root=`n` `exp n`=natural exponent `e^n`=`n` `log n`=natural logarithm=`n` `log10 n`=base-10 logarithm=`n` `log2 n`=base-2 logarithm=`n` `sin n`=sine (radians)=`n` `cos n`=cosine (radians)=`n` `tan n`=tangent (radians)=`n` `asin n`=arcsine, returns radians in `[-pi/2, pi/2]`; NaN outside `[-1, 1]`=`n` `acos n`=arccosine, returns radians in `[0, pi]`; NaN outside `[-1, 1]`=`n` `atan n`=arctangent, returns radians in `[-pi/2, pi/2]`=`n` `atan2 y x`=two-argument arctangent (y, x order; radians)=`n` `pi`=3.141592653589793 (IEEE-754 f64, `f64::consts::PI`)=`n` `tau`=6.283185307179586 (== 2\*pi; one full turn in radians)=`n` `e`=2.718281828459045 (Euler's number, `f64::consts::E`)=`n` `transpose m`=transpose row-major matrix=`L (L n)` `matmul a b`=matrix product=`L (L n)` `dot a b`=vector dot product=`n` `solve a b`=solve `Ax = b` via LU with partial pivoting; errors on singular/non-square=`L n` `inv a`=matrix inverse; errors on singular/non-square=`L (L n)` `det a`=determinant; errors on non-square=`n` `fft xs`=discrete FFT: real samples → `L [re, im]`; zero-padded to next power of 2=`L (L n)` `ifft pairs`=inverse FFT; imaginary part dropped on return=`L n` `fmt2 x digits`=format number `x` to `digits` decimal places (half-to-even rounding; `digits` clamped to `0..=20`). Compose with `fmt` for template + precision: `fmt "x={}" (fmt2 v 2)`=`t` > **`fmt` does not print.** `fmt` and `fmt2` are pure-functional string builders, not `println!`. A bare `fmt "..." v` statement evaluates and discards the resulting text on every engine - nothing reaches stdout. Print with `prnt fmt "..." v` or capture with `line = fmt "..." v`. The verifier emits **ILO-T032** when `fmt`/`fmt2` is a non-tail statement with no binding. Tail position is fine: `say-x v:n>t;fmt "x={}" v` returns the string to the caller as documented. > **`+=`, `mset`, and `mdel` return a new value, they do not mutate in place.** `+=xs v` returns a new list; `mset m k v` and `mdel m k` return a new map. As a bare statement (`@i 0..3{+=out i}`, `mset m "a" 1;m`) the result is silently discarded and the source binding is unchanged. The verifier emits **ILO-T033** when these calls appear at a discarded position - any non-tail statement, or anywhere inside a loop body. Fix is the assignment form: `out=+=out i`, `m=mset m k v`, `m=mdel m k`. Tail position in a function/`?{}` arm is fine - the value flows out as the return. > **`wr` and `wrl` return the written path, not a status.** Both succeed with `~path` (the file path you passed in), not `~"ok"` or nil. A `save` helper that ends with a bare `wrl "tasks.txt" xs` therefore returns `~"tasks.txt"`, and every successful mutation echoes the state-file path to stdout - noise for any caller piping output. Discard the path and return a clean status string instead: `save xs:L t>R t t;r=wrl "tasks.txt" xs;?r{~_:~"ok";^e:^e}`. The error arm still propagates `wrl`'s message. See [`examples/cli-tasks-save-ok.ilo`](examples/cli-tasks-save-ok.ilo) for the full shape. [Datetime (`dtfmt` / `dtparse` / `dtparse-rel`)] UTC only. Format strings follow strftime conventions (`%Y-%m-%d %H:%M:%S`, `%s`, etc). dtfmt 1700000000 "%Y-%m-%d" -- R t t: Ok="2023-11-14", Err if out of range dtparse "2024-01-15" "%Y-%m-%d" -- R n t: Ok=epoch seconds, Err if unparseable dtfmt! e "%H:%M:%S" -- auto-unwrap inside R-returning fn `dtparse-rel s now` resolves a natural-language relative-date phrase to a Unix epoch anchored at `now`. Phrases supported: `today`, `yesterday`, `tomorrow` `N days ago`, `in N days` (also `N day ago`, `in N day`) `N weeks ago`, `in N weeks` `N months ago`, `in N months` (end-of-month clamping: `Jan 31 + 1 month = Feb 28/29`) `last `, `next `, `this ` — weekdays as `monday`–`sunday` or short `mon`–`sun`; `last`/`next` never return today ISO-8601 date literal `YYYY-MM-DD` — passthrough to `dtparse` (ignores `now`) -- now = 1705276800 (2024-01-15, Monday) dtparse-rel!! "yesterday" (now) -- 2024-01-14 00:00 UTC dtparse-rel!! "3 days ago" (now) -- 2024-01-12 00:00 UTC dtparse-rel!! "in 2 weeks" (now) -- 2024-01-29 00:00 UTC dtparse-rel!! "last friday" (now) -- 2024-01-12 00:00 UTC dtparse-rel!! "next wednesday" (now) -- 2024-01-17 00:00 UTC dtparse-rel!! "2023-12-25" (now) -- 1703462400 (ignores now) Unrecognised phrases return `Err` with a message listing valid forms. All times are midnight UTC. [Duration (`dur-parse` / `dur-fmt`)] `dur-parse s > R n t` — parse a human-readable duration string into total seconds as a float. `dur-fmt n > t` — format seconds as a human-readable duration string. Both are tree-bridge eligible: VM and Cranelift dispatch through the same interpreter arm. Accepted units for `dur-parse`: `w`=week, weeks `d`=day, days `h`=hour, hours, hr, hrs `m`=min, mins, minute, minutes `s`=sec, secs, second, seconds dur-parse "3h 30m" -- R n t: Ok=12600, Err if no unit found dur-parse "1 week 2 days" -- R n t: Ok=777600 dur-parse "1.5 hours" -- R n t: Ok=5400 dur-parse "4h32m" -- no space between number and unit: Ok=16320 dur-parse! s -- auto-unwrap inside R-returning fn dur-fmt 9720 -- "2h 42m" dur-fmt 86400 -- "1 day" dur-fmt 90 -- "1m 30s" dur-fmt 90.5 -- "1m 30.5s" (fractional seconds preserved) dur-fmt 0 -- "0s" dur-fmt -90 -- "-1m 30s" (single leading minus) -- Round-trip: parse -> seconds -> format n = dur-parse! "2 days 3 hours" dur-fmt n -- "2 days 3h" **Months are not supported.** `mo`, `month`, `months`, `M` are deliberately omitted because a month is not a fixed number of seconds. Strings like `"3mo"` or `"3 months"` produce a `no recognised unit` error. Use explicit day counts (e.g. `"30 days"`, `"90 days"`). **Sticky sign.** A leading `-` in `dur-parse` is sticky: it applies to every following token until an explicit `+` resets it. So `"-1m 30s"` parses to `-90`, and `"-1h +10m"` parses to `-3000`. This makes the round-trip `dur-fmt -> dur-parse` symmetric for negative durations, where `dur-fmt` emits a single leading minus rather than signing each part. **Fractional seconds.** `dur-fmt` renders sub-second fractions with up to 3 decimal places (trailing zeros stripped), both for sub-second inputs (`0.5 -> "0.5s"`) and for mixed values where the seconds component carries a fraction (`90.5 -> "1m 30.5s"`). Fractional minutes / hours / days / weeks are decomposed into smaller units before formatting. [Set operations] `setunion`, `setinter`, `setdiff` operate on lists of `t`, `n`, or `b` (same constraint as `uniqby`). Output is deduped and sorted by a type-prefixed string key, so results are deterministic across runs and engines. Sort is lexicographic on the key, not numeric - re-sort with `srt` afterwards if you need numeric order. [Linear algebra] `transpose`, `matmul`, `dot`, `solve`, `inv`, `det` operate on row-major matrices (`L (L n)`) and flat vectors (`L n`). `solve`, `inv`, `det` use LU decomposition with partial pivoting and raise on singular or non-square inputs. These ship as host-vetted builtins because hand-rolled implementations risk silent precision loss. [FFT] `fft xs` runs an iterative Cooley-Tukey radix-2 transform on real samples, zero-padding to the next power of two. Output is `L [re, im]` with one inner pair per frequency bin. `ifft pairs` is the inverse, dropping the imaginary part on return. [Builtin aliases] All builtins accept one or more alias names that resolve to the canonical name after parsing. Using an alias triggers a hint suggesting the canonical form. Most aliases go from a familiar long form (e.g. `length`) to the canonical short (`len`), letting newcomers write readable code while learning the canonical names. A small number go the other direction: where the canonical name is already 4+ characters and there is a natural short form with no plausible-user-binding collision, the short form is carved out as a permanent ergonomic alias. `floor`=→=`flr` `ceil`=→=`cel` `round`=→=`rou` `rand`=→=`rnd` `random`=→=`rnd` `rng`=→=`range` `lset`=→=`lst` `regex_all`=→=`rgxall` `regex_sub`=→=`rgxsub` `string`=→=`str` `number`=→=`num` `length`=→=`len` `head`=→=`hd` `tail`=→=`tl` `reverse`=→=`rev` `sort`=→=`srt` `slice`=→=`slc` `unique`=→=`unq` `filter`=→=`flt` `fold`=→=`fld` `flatten`=→=`flat` `concat`=→=`cat` `contains`=→=`has` `group`=→=`grp` `average`=→=`avg` `print`=→=`prnt` `trim`=→=`trm` `split`=→=`spl` `format`=→=`fmt` `regex`=→=`rgx` `read`=→=`rd` `readlines`=→=`rdl` `readbuf`=→=`rdb` `write`=→=`wr` `writelines`=→=`wrl` length xs -- works, but emits: hint: `length` → `len` (canonical form) len xs -- canonical - no hint rng 0 10 -- works, but emits: hint: `rng` → `range` (canonical form) range 0 10 -- canonical - no hint Every alias - both short-form (`rng`, `rand`) and long-form (`head`, `length`, `filter`, `concat`, ...) - follows the same shadow-prevention rule as canonical builtins: using an alias name as a binding LHS or user-function name is rejected at parse time with `ILO-P011`. The alias resolver rewrites call-position uses to the canonical builtin, so if the bind were allowed the user variable would be silently bypassed and the builtin called instead. For example, `head=fmt "### {}" t` then `cat [head body] "\n"` would rewrite `head` in call position to `hd`, emitting empty output with no error. The parser intercepts every alias in all three positions (top-level binding, local binding inside a function, user function declaration) with a rename hint. The full alias table is listed above; every entry triggers `ILO-P011` in all three contexts. `get` and `pst` return `Ok(body)` on success, `Err(message)` on failure (connection error, timeout, DNS failure, etc). In 0.12.0 the `$` sigil was rebound from `get` (parochial — `$` for HTTP is unique to ilo) to the new `run` builtin (argv-list process spawn). `$` for shell-exec reads cross-language — bash, Perl, Ruby, Python, PowerShell, and Zx all use `$` for command substitution. HTTP `get` is still called by name; the `$` shortcut is for process exec only. `post` was renamed to `pst` to bring it into line with the I/O compression family (`rd`, `wr`, `srt`, `flt`, `fld`, `fmt`). get url -- R t t: Ok=response body, Err=error message get! url -- auto-unwrap: Ok→body, Err→propagate to caller pst url body -- R t t: HTTP POST with text body pst url body headers -- R t t: HTTP POST with body and custom headers -- Custom headers: build an M t t map with mmap/mset h=mmap h=mset h "x-api-key" "secret" r=get url h -- GET with x-api-key header r=pst url body h -- POST with x-api-key header -- Explicit timeouts (milliseconds; rounds up to nearest second internally) r=get-to url 5000 -- GET with 5 s timeout; Err if exceeded r=pst-to url body 3000 -- POST with 3 s timeout Behind the `http` feature flag (on by default). Without the feature, `get`/`pst`/`get-to`/`pst-to` return `Err("http feature not enabled")`. [Process spawn] ilo provides one process-spawn primitive: `run cmd argv > R (M t t) t`. The signature is deliberately narrow: the first argument is the program (text), the second is the argv list (`L t`), and the result is a `Result` whose `Ok` carries a three-key Map of stdout / stderr / code as text. r=run "echo" ["hi"] -- Ok({"stdout":"hi\n","stderr":"","code":"0"}) out=mget r.! "stdout" -- "hi\n" $"git" ["status", "--short"] -- equivalent: $ is the sigil shortcut for run **No shell, no interpolation, no glob.** The argv list is passed directly to `std::process::Command::args`. There is no `sh -c`, no string concatenation between `cmd` and `argv`, and no glob expansion. This is the principled defence against shell injection: ilo refuses to provide an injection vector while still providing controlled exec. Compared to bash + `jq`, the argv-list discipline and the typed Result + Map handle make `run` materially safer for agent orchestration. **Non-zero exit is NOT an error.** `Err` is reserved for spawn failures (command not found, permission denied, kernel-level pipe failure, output cap exceeded). A child that returns a non-zero exit code surfaces as `Ok({"stdout":..., "stderr":..., "code":""})`; the caller inspects `code` and branches as needed. This matches Python's `subprocess.run` semantics. **Inherits parent env + cwd.** The first version provides no env or cwd override. Set the parent env / cwd before invoking ilo if you need a different shape. **Captured output is capped at 10 MiB per stream.** Either stream exceeding the cap returns an `Err` rather than partial capture so downstream JSON pipelines never see a truncated payload. **Stdin for child processes.** `run` spawns children with stdin closed (previously `/dev/null`). Use `rdin` / `rdinl` to read the **parent** program's own stdin from the shell pipeline. `rdin` reads all of stdin as text; `rdinl` reads it line by line. Behind the same default build profile as `get`/`pst`; on `wasm32` targets, `run` returns `Err("run: process spawn not available on wasm")`. `env` reads an environment variable by name, returning `Ok(value)` or `Err("env var 'KEY' not set")`: env key -- R t t: Ok=value, Err=not set message env! key -- auto-unwrap: Ok→value, Err→propagate to caller `env-all` returns the full process environment as a `M t t` map wrapped in `R`, mirroring the `env` shape so `env-all!` auto-unwraps inside a Result-returning function. Use it for "merge env over config" patterns where the agent does not know which keys to read up-front: env-all -- R (M t t) t: Ok=map of every env var, Err reserved for future failures env-all! -- auto-unwrap to M t t Non-UTF-8 environment variables are silently skipped (same policy as Rust's `std::env::vars`); the snapshot is always `Ok` today. [JSON builtins] `jpth` extracts a value from a JSON string by dot-separated path. Array elements are accessed by numeric index. **Note: `jpth` is dot-path only, not JSONPath.** A leading `$`, `*` wildcard, or `[...]` bracket selector triggers a diagnostic error pointing at the dot-path form; iterate arrays yourself with `@i` or `map` if you need wildcard behaviour. Since 0.12.1 the Ok variant is **typed**: a JSON array comes back as a list (`@`-iterable, `len`-able), a JSON object comes back as a record (`jdmp`-roundtrippable, `jkeys`-enumerable), and scalars come back as the matching ilo primitive (number, text, bool, nil). Pre-0.12.1 every non-string leaf was stringified, forcing a re-parse via `jpar` to iterate. The signature is now `R _ t`. jpth json "name" -- R _ t: Ok=typed value, Err=error message jpth json "user.name" -- nested path lookup jpth json "items.0.name" -- array index access (dot before index, not [0]) jpth json "spans" -- Ok=L _ when the leaf is a JSON array (iterable!) jpth json "deps" -- Ok=record when the leaf is a JSON object jpth json "n" -- Ok=Number 42 (not Text "42") on a numeric leaf jpth! json "name" -- auto-unwrap jpth json "$.a.b" -- ^"jpth is dot-path only ..." (JSONPath rejected) jpth json "items.*.name" -- ^"jpth is dot-path only ..." (no wildcards) `jkeys json path` returns the **sorted** top-level keys of the JSON object at the dot-path as `L t`. Empty path means root. Errs if the value at the path is not an object. Pairs with `mkeys` (which works on ilo `M` maps) so an agent can enumerate JSON object keys without re-parsing through `jpar`. jkeys json "" -- R (L t) t: Ok=sorted root keys jkeys json "deps" -- sorted keys of the "deps" object jkeys! json "deps" -- auto-unwrap jkeys json "items" -- ^"jkeys: value at path is not a JSON object" `jdmp` serialises any ilo value to a JSON string: jdmp 42 -- "42" jdmp "hello" -- "\"hello\"" jdmp [1 2 3] -- "[1,2,3]" jdmp (pt x:1 y:2) -- "{\"x\":1,\"y\":2}" `jpar` parses a JSON string into ilo values. JSON objects become records with type name `json`, arrays become lists, strings/numbers/bools/null map directly: jpar text -- R _ t: Ok=parsed value, Err=parse error r=jpar! "{\"x\":1}" -- r is a json record, access with r.x `jpar-list` is a typed companion: it parses the JSON string and **asserts the top-level value is an array**. The result is `R (L _) t`, so `jpar-list! body` unwraps directly to a list that `@` can iterate — no intermediate binding or type annotation needed: jpar-list text -- R (L _) t: Ok=list of parsed values, Err=parse or type error -- iterate a JSON array response body: @x (jpar-list! body){prnt x} -- or bind first: xs=jpar-list! body;@i 0..len xs{prnt (at xs i)} Use `jpar` when the JSON top-level shape is unknown (object, array, scalar). Use `jpar-list` when you know the response is an array and want to iterate it immediately. LISTS: xs=[1 2 3] -- space-separated (preferred) xs=[1, 2, 3] -- commas also work mixed=["search" 10] -- heterogeneous lists allowed (type: L _) w="world" words=["hi" w] -- variables work in list literals empty=[] Elements are expressions in brackets, separated by spaces or commas. Variables and expressions are allowed as elements. Lists may contain mixed types (inferred as `L _`). Use with `@` to iterate: @x xs{+x 1} Index by integer literal or variable (dot notation): xs.0 # first element (literal index) xs.2 # third element (literal index) xs.i # i-th element when `i` is a bound variable in scope The variable-index form `xs.i` is sugar for `at xs i` - the parser builds a field-access node and a post-parse desugar pass rewrites it whenever the field identifier resolves to a binding in scope (parameter, let, foreach, range, match-arm). Record field access keeps working: if the identifier is also a declared field on any record type in the program, the rewrite is skipped and the strict `.field` semantics apply. **CLI list arguments:** Pass lists from the command line with commas (brackets also accepted): ilo 'f xs:L n>n;len xs' 1,2,3 → 3 ilo 'f xs:L t>t;xs.0' 'a,b,c' → a diff --git a/examples/glued-negative-literal-spacing.ilo b/examples/glued-negative-literal-spacing.ilo new file mode 100644 index 00000000..5954e64d --- /dev/null +++ b/examples/glued-negative-literal-spacing.ilo @@ -0,0 +1,36 @@ +-- Glued-negative-literal spacing rule. The lexer packs a leading `-` with no +-- preceding space into the number token, so `a -1.5` is `Number(a), +-- Number(-1.5)` not `a, Minus, 1.5`. This is load-bearing for call-arg forms +-- (`mod n -2`, `sub 5 -3`) and list literals (`[1 -2 3]`), but it means a +-- naked `0 -1.5` at statement position is a parse error. +-- +-- This example pins the three idiomatic forms: +-- - `a - b` with spaces both sides for subtraction (canonical). +-- - glued `-N` for call arguments and list elements (load-bearing). +-- - `(-N)` parens for a bare negative value as an expression. + +-- Canonical subtraction: spaces both sides. +sub > n + 0 - 1.5 + +-- Glued negative literal as a call argument. +modn n:n > n + mod n -2 + +-- Glued negative literal as a list element. +midlist > n + l=[1 -2 3] + at l 1 + +-- Parenthesised negation as an expression. +neg > n + (-1.5) + +-- run: sub +-- out: -1.5 +-- run: modn 7 +-- out: 1 +-- run: midlist +-- out: -2 +-- run: neg +-- out: -1.5 diff --git a/skills/ilo/ilo-language.md b/skills/ilo/ilo-language.md index 48189600..c4d6b8f5 100644 --- a/skills/ilo/ilo-language.md +++ b/skills/ilo/ilo-language.md @@ -17,7 +17,7 @@ Prefix-notation, strongly-typed, verified pre-run. Bodies single-line, `;`-separ ## operators -Binary `+ - * / % < > <= >= = !=`, bool `& | !`, append `+=`. Nest: `+*a b c` = `(a*b)+c`; outer binds inner LEFT. Take atoms/nested-ops, NOT calls; bind first: `r=fac -n 1;*n r`. No compound: `<=a b`, not `= <= >= = !=`, bool `& | !`, append `+=`. Nest `+*a b c`=`(a*b)+c`; outer binds inner LEFT. Atoms/nested-ops not calls; bind first: `r=fac -n 1;*n r`. No compound `<=a b`. Glued `-n` = neg literal; bare `0 -1` errs ILO-P001. ## idents diff --git a/src/parser/mod.rs b/src/parser/mod.rs index 2fe17263..8bf02497 100644 --- a/src/parser/mod.rs +++ b/src/parser/mod.rs @@ -586,6 +586,19 @@ impl Parser { Some("the last expression in a function body is the return value — no 'return' keyword".to_string()), Token::KwIf => Some("ilo uses match for conditionals: ?expr{true:...;false:...}".to_string()), + // Glued-negative-literal misparse: `a -1.5` lexes as `Number(a), Number(-1.5)` + // because the lexer packs a leading `-` with no preceding space into the + // number token (this is load-bearing for call-args like `mod n -2` and + // list literals `[1 -2 3]`). When that negative number lands at decl + // position, the user almost certainly meant subtraction with a missing + // space, so spell out the spacing rule and the parenthesised-negation + // workaround instead of the generic "got number `-1.5`" message. + Token::Number(n) if *n < 0.0 => + Some(format!( + "for subtraction, write `a - b` with spaces both sides (e.g. `0 - {}`). for a negative value as an expression, wrap in parens: `({})`. a glued `-N` (no space before) is only parsed as a negative literal when it's a call argument or inside a list.", + n.abs(), + n, + )), _ => None, }; let mut err = self.error("ILO-P001", msg); diff --git a/tests/regression_negative_literal_diag.rs b/tests/regression_negative_literal_diag.rs new file mode 100644 index 00000000..24567dfd --- /dev/null +++ b/tests/regression_negative_literal_diag.rs @@ -0,0 +1,163 @@ +// Regression test for the glued-negative-literal misparse diagnostic. +// +// Background: `a -1.5` lexes as `Number(a), Number(-1.5)` because the lexer +// packs a leading `-` (no space before) into the number token. This is +// load-bearing for call-arg forms (`mod n -2`, `sub 5 -3`) and list literals +// (`[1 -2 3]`), so we deliberately do NOT split in those contexts (see +// `regression_neg_literal_papercut.rs` for the contexts that DO split). +// +// The downside: when a user writes `0 -1.5` meaning "zero minus one point +// five" with an accidental missing space, the parser previously emitted a +// generic "expected declaration, got number `-1.5`" with no hint, leaving +// the user with no clue that the issue was the missing space. +// +// This test pins the tailored ILO-P001 hint that spells out the spacing rule +// and the parenthesised-negation workaround. It also pins the non-regressing +// shapes (spaces-both-sides subtraction, glued call-args, list literals, +// parenthesised negation) so a future lexer tweak that breaks any of those +// shows up here too. The hint emission is engine-independent (parser-level), +// and the positive shapes are exercised on every backend reachable from the +// public CLI: VM and Cranelift JIT (cranelift feature). The tree-walker was +// removed from the public CLI in 0.12.x but still runs in-process as the +// HOF-callback fallback, so the VM arm transitively covers it. + +use std::process::Command; +use std::sync::atomic::{AtomicU64, Ordering}; + +fn ilo() -> Command { + Command::new(env!("CARGO_BIN_EXE_ilo")) +} + +fn write_src(src: &str, tag: &str) -> std::path::PathBuf { + static COUNTER: AtomicU64 = AtomicU64::new(0); + let seq = COUNTER.fetch_add(1, Ordering::SeqCst); + let path = std::env::temp_dir().join(format!( + "ilo_neg_lit_diag_{}_{}_{}.ilo", + std::process::id(), + seq, + tag, + )); + std::fs::write(&path, src).unwrap(); + path +} + +fn run_ok(engine: &str, src: &str, args: &[&str]) -> String { + let path = write_src(src, engine.trim_start_matches("--")); + let mut cmd = ilo(); + cmd.arg(path.to_str().unwrap()).arg(engine); + for a in args { + cmd.arg(a); + } + let out = cmd.output().expect("failed to run ilo"); + assert!( + out.status.success(), + "ilo {engine} failed for src=`{src}` args={args:?}: stderr={}", + String::from_utf8_lossy(&out.stderr) + ); + String::from_utf8_lossy(&out.stdout).trim().to_string() +} + +#[test] +fn glued_neg_literal_at_stmt_position_emits_tailored_hint() { + // `0 -1.5` inside a function body: lexer packs `-1.5`; parser sees + // Number(0), Number(-1.5) and fails out of the body, re-enters + // parse_decl which sees the Number(-1.5) at decl position. + let src = "m > n\n 0 -1.5\nm\n"; + let path = write_src(src, "tailored_hint"); + let out = ilo() + .arg(path.to_str().unwrap()) + .arg("--json") + .output() + .expect("failed to run ilo"); + assert!(!out.status.success(), "expected ilo to fail"); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("ILO-P001"), + "expected ILO-P001, got: {stderr}" + ); + assert!( + stderr.contains("got number `-1.5`"), + "expected message to mention the offending number, got: {stderr}" + ); + // The tailored hint should mention the spaces-both-sides rule AND the + // parenthesised-negation workaround. + assert!( + stderr.contains("spaces both sides"), + "expected hint to mention spaces both sides, got: {stderr}" + ); + assert!( + stderr.contains("(-1.5)"), + "expected hint to mention `(-1.5)` parens workaround, got: {stderr}" + ); + // And it should reference the canonical `0 - 1.5` form. + assert!( + stderr.contains("0 - 1.5"), + "expected hint to suggest the canonical `0 - 1.5` form, got: {stderr}" + ); +} + +#[test] +fn glued_neg_int_literal_at_stmt_position_emits_tailored_hint() { + // Same shape but with an integer to confirm the suggestion uses an + // int-style example (no spurious `.0`). + let src = "m > n\n 4 -1\nm\n"; + let path = write_src(src, "tailored_int_hint"); + let out = ilo() + .arg(path.to_str().unwrap()) + .arg("--json") + .output() + .expect("failed to run ilo"); + assert!(!out.status.success(), "expected ilo to fail"); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("ILO-P001"), + "expected ILO-P001, got: {stderr}" + ); + assert!( + stderr.contains("spaces both sides"), + "expected hint to mention spaces both sides, got: {stderr}" + ); +} + +fn check_positive_shapes(engine: &str) { + // Spaces-both-sides subtraction: the canonical form returns -1.5. + assert_eq!( + run_ok(engine, "m > n\n 0 - 1.5\n", &["m"]), + "-1.5", + "0 - 1.5 (spaces both sides) engine={engine}" + ); + + // Glued negative literal as call argument (load-bearing form). `mod 7 + // -3` must still parse as `mod(7, -3)`. + assert_eq!( + run_ok(engine, "x > n\n mod 7 -3\n", &["x"]), + "1", + "mod 7 -3 (glued call-arg) engine={engine}" + ); + + // Glued negative literal in middle of list literal. + assert_eq!( + run_ok(engine, "x > n\n l=[1 -2 3]\n at l 1\n", &["x"]), + "-2", + "[1 -2 3] (glued list element) engine={engine}" + ); + + // Parenthesised negation: the documented workaround for "I want a + // negative value as an expression". + assert_eq!( + run_ok(engine, "x > n\n (-1.5)\n", &["x"]), + "-1.5", + "(-1.5) (paren negation) engine={engine}" + ); +} + +#[test] +fn neg_literal_positive_shapes_vm() { + check_positive_shapes("--vm"); +} + +#[test] +#[cfg(feature = "cranelift")] +fn neg_literal_positive_shapes_cranelift() { + check_positive_shapes("--jit"); +}