Syntax Gotchas
This document records unintuitive consequences of Eucalypt’s syntax design decisions that can lead to subtle bugs or confusion.
Operator Precedence Issues
Section titled “Operator Precedence Issues”Eucalypt’s catenation (juxtaposition) operator has very low precedence (20) — lower than all arithmetic and comparison operators. This means infix operators bind more tightly than catenation, which can produce surprising parses.
The precedence hierarchy (highest to lowest):
| Precedence | Name | Operators |
|---|---|---|
| 95 | ↑ (head prefix) |
|
| 90 | lookup/call | . (lookup), f(x, y) |
| 88 | bool-unary | ! (not) |
| 85 | exp | ^ (power) |
| 80 | prod | *, /, ÷, % |
| 75 | sum | +, - |
| 50 | cmp | <, >, <=, >= |
| 45 | append | ++ |
| 40 | eq | =, != |
| 35 | bool-prod | ∧ (and) |
| 30 | bool-sum | ∨ (or) |
| 20 | cat | catenation (juxtaposition) |
| 15 | clause | =>, ⇒ (cond clause) |
| 10 | apply | |
| 5 | meta | ` (metadata) |
Field Access vs Catenation
Section titled “Field Access vs Catenation”Problem: The lookup operator (.) has higher precedence (90) than
catenation (precedence 20), which can lead to unexpected parsing.
Gotcha: Writing objects head.id groups head.id into one unit
first, and that unit — not objects — is what gets applied. It is
parsed as head.id(objects), rather than (objects head).id.
Example:
# This doesn't work as expected:objects: range(0, 5) map({ id: _ })result: objects head.id # Parsed as: head.id(objects)
# Correct syntax requires parentheses:result: (objects head).id # Explicitly groups the field accessError Message: When this occurs, you may see confusing errors like:
cannot return function into case table without defaultbad index 18446744073709551615 into environment(under memory pressure)
Solution: Always use parentheses to group the expression you want to access fields from:
- Use
(expression).fieldinstead ofexpression target.field - Be explicit about precedence when combining catenation with field access
The ↑ (head) prefix operator (precedence 95) binds even tighter than
. (90), so it has the same gotcha one level up: ↑xs.id means
(↑xs).id, not ↑(xs.id).
Arithmetic After a Pipeline
Section titled “Arithmetic After a Pipeline”Problem: Infix operators like +, -, * have higher precedence
than catenation. When an infix operator follows a pipeline (catenation
chain), it binds to the last function in the chain, not to the result
of the whole pipeline.
Gotcha: Writing xs foldl(f, 0) + 1 is not parsed as
(xs foldl(f, 0)) + 1. Instead, the shunting-yard algorithm sees:
[xs, cat@20, foldl, call@90, (f,0), +@75, 1]Because + (75) has higher precedence than cat (20), the +
binds first: foldl(f, 0) + 1 is evaluated (adding 1 to a partial
application — a type error), and then the result is applied to xs.
Example:
# WRONG — fails at runtime:n: xs foldl(+, 0) + 1 # Parsed as: (foldl(+, 0) + 1)(xs)
# CORRECT — use parentheses:n: (xs foldl(+, 0)) + 1 # Explicit grouping
# CORRECT — split into two bindings:m: xs foldl(+, 0)n: m + 1Error Messages: the error is raised at the operator — type mismatch: expected number, found a function when it receives the partial
application, or tried to call a number as a function when its result is
called with the pipeline. Either way it carries a note stating the parse,
for example:
note: 'xs foldl(+, 0) + 1' was read as 'xs (foldl(+, 0) + 1)'; parenthesise the pipeline: '(xs foldl(+, 0)) + 1'The note appears only when the operator expression was written without
parentheses as a pipeline step. Inside an expression-anaphor lambda, such
as map(_ nth(0) = 1), it states the parse but suggests no parentheses:
(_ nth(0)) would make the parentheses the anaphor’s scope.
Rule of thumb: If a pipeline result feeds into an infix operator, always use parentheses around the pipeline or bind it to a name first.
Anaphora and Function Syntax
Section titled “Anaphora and Function Syntax”Lambda Syntax Does Not Exist
Section titled “Lambda Syntax Does Not Exist”Problem: Eucalypt does not have lambda expressions or arrow functions. There is no syntax for anonymous multi-parameter functions.
Gotcha: The -> token is the const operator (returns its
left operand, ignoring the right). Writing x -> x + 1 does not
create a function — it evaluates x, discards x + 1, and returns
x.
Invalid Examples:
# NONE of these create functions in Eucalypt:map(\x -> x + 1) # Invalid syntaxmap(|x| x + 1) # Invalid syntaxmap(fn(x) => x + 1) # Invalid syntaxfilter(x -> x > 0) # -> is const, not lambda!Correct Approach: Use sections, anaphora (_, _0, _1), named
functions, or partial application:
# Operator sections (preferred for simple cases):map(+ 1) # Section: adds 1map(^ 2) # Section: squaresfilter(> 0) # Section: positive?
# Identity anaphor — passes an identity function:map(_) # Same as map(identity)
# Anaphora in expressions:map(_ + 1) # Anonymous single-parameter functionfilter(_ > 0) # Anonymous predicate
# Multiple `_` — each is a separate parameter:f: (_ * _) # f is a 2-arg multiply functionf(3, 4) # => 12
# Numbered anaphora for same-param reuse:sq: (_0 * _0) # sq(5) => 25
# Using named function + partial application:add-one(x): x + 1map(add-one)
# For multi-parameter needs, define a named helper:has-y(y, h): first(h) = yfilter(has-y(target-y)) # Partial applicationImportant: Each _ introduces a separate parameter. _ * _
is a 2-arg function (like (_0 * _1)), not (_0 * _0). Use numbered
anaphora _0 * _0 when you need to reference the same parameter twice.
Reference: See Anaphora for detailed explanation of anaphora usage.
Anaphor Scoping: Parens Are Opaque
Section titled “Anaphor Scoping: Parens Are Opaque”Problem: Parentheses create an anaphor scope boundary. Anaphors inside parens form a lambda at the paren level, not at the enclosing expression.
Scoping rules:
-
Parens are opaque by default — anaphors inside parens create a lambda scoped to that paren group. This applies to both
_and_0/_1. -
Subsumption — if the enclosing expression already has direct anaphors, inner paren groups become transparent (their anaphors join the outer scope).
-
ArgTuples follow the same rules — function call arguments are opaque unless subsumed by an outer anaphoric scope.
Examples:
# Parens opaque — paren group forms its own lambda:(_ + 1) # λ(a). a + 1(_ * _) # λ(a, b). a * b(_ = :quux) ∘ tag # (λ(a). a = :quux) ∘ tag ✓ composition works
# Without parens — whole expression is the lambda body:_ + 1 # λ(a). a + 1 (same result here)_ * _ # λ(a, b). a * b
# Parens opaque breaks cross-operator average:(_0 + _1) / 2 # (λ(a,b). a+b) / 2 — type error!# Correct idiom (no parens):_0 + _1 / 2 # λ(a, b). a + b/2 — note: b is halved, not sum
# Subsumption: outer _ makes inner (_ * _) transparent:_ + (_ * _) # λ(a, b, c). a + (b * c) ✓
# ArgTuple opaque by default:map(_ + 1) # map(λ(a). a + 1) ✓filter(_ > 0) # filter(λ(a). a > 0) ✓
# ArgTuple subsumed when outer has anaphors:_0 * (_1 + 2) # λ(a, b). a * (b + 2) ✓Common mistake: Expecting (_0 + _1) / 2 to be a 2-argument
averaging function. Under the opaque parens model, (_0 + _1) forms
its own lambda and / 2 tries to divide that lambda by 2 — a type
error. Use a named helper instead:
avg2(a, b): (a + b) / 2zip-with(avg2, xs, ys)Expanding scope with subsumption: The subsumption rule can be
exploited to make the outer expression anaphoric, causing inner paren
groups to become transparent. A common idiom is to place a direct
anaphor — such as a not-nil check _0✓ — at the outer level:
# _0✓ makes the whole expression anaphoric in _0,# so _0 inside count(_0) is subsumed — both refer to the same parameter._0✓ && count(_0) >= 4 # λ(a). a != null && count(a) >= 4Without the outer _0✓, the _0 inside count(_0) would form a
separate lambda at the ArgTuple level, and the outer && would see a
function value rather than a boolean. The not-nil postfix ✓ is
often the most natural way to introduce the outer anaphor when you
want to also guard against null.
A Bare Numeral in Interpolation Braces Is an Anaphor Index
Section titled “A Bare Numeral in Interpolation Braces Is an Anaphor Index”Problem: Inside a string, {...} is interpolation, and a bare
number in the braces — "{42}" — is not the literal text 42. It is
numbered string anaphora: {0}, {1}, {2}, … refer to the 1st,
2nd, 3rd positional argument of the string-as-a-function. So {42} makes
the string a function of 43 arguments, referencing the 43rd.
Gotcha: This is silent. A string with a bare-numeral brace becomes a function value, and functions are not rendered — so the whole binding just vanishes from the output with no error:
answer: "the answer is {42}" # answer is now a 43-arg functionother: 1$ eu example.eu---other: 1answer produced no output at all. Forcing the value (e.g. with eu -e '"{42}"') turns the silence into a crash instead:
error: bytecode: PAP arity out of range (supplied 1, pending 42, max 16)Fixes:
# Literal braces — double themanswer: "the answer is {{42}}" # => "the answer is {42}"
# Interpolate a *value* named 42 — bind it to a name firstn: 42answer: "the answer is {n}" # => "the answer is 42"Rule: a number inside interpolation braces is always an anaphor index,
never a literal. Use {{ }} for literal braces, and interpolate values
through named bindings ({name}) or a format specifier ({value:%d}),
never a bare numeral. Small indices bite the same way — "{0}" is a
one-argument function, not the digit zero.
Metadata vs Comments
Section titled “Metadata vs Comments”Backtick Is Metadata, Not a Comment
Section titled “Backtick Is Metadata, Not a Comment”Problem: The backtick (`) attaches metadata to the next
declaration. It is not a comment syntax.
Gotcha: Writing ` "some text" with no declaration following
it causes a parse error, often reported at an unexpected location
(e.g., line 1).
Example:
# WRONG — dangling metadata with nothing to attach to:` "This is not a comment"
# CORRECT — use # for comments:# This is a comment
# CORRECT — metadata attached to a declaration:` "Documentation for my-fn"my-fn(x): x + 1Rule: Use # for comments. Only use ` when you intend to
attach metadata to the immediately following declaration.
Single Quote Identifiers
Section titled “Single Quote Identifiers”Single Quotes Are Not String Delimiters
Section titled “Single Quotes Are Not String Delimiters”Problem: Single quotes (') in Eucalypt are used to create
identifiers, not strings.
Gotcha: Coming from languages where single quotes delimit strings,
developers might expect 'text' to be a string literal.
Key Rules:
- Single quotes create normal identifiers that can contain any characters
- The identifier name is the content between the quotes (quotes are stripped)
- This is the only use of single quotes in Eucalypt
- String literals use double quotes (
") only
Examples:
# Single quotes create identifiers (variable names):'my-file.txt': "content" # Creates identifier: my-file.txthome: { '.bashrc': false # Creates identifier: .bashrc '.emacs.d': false # Creates identifier: .emacs.d 'notes.txt': true # Creates identifier: notes.txt}
# Access using lookup:z: home.'notes.txt' # Looks up identifier: notes.txt
# NOT string literals:'hello' = 'hello' # Compares two variable references (not strings)"hello" = "hello" # Compares two string literals (correct)Hyphens and Digits Are Identifier Characters — x-2 Is One Name
Section titled “Hyphens and Digits Are Identifier Characters — x-2 Is One Name”Problem: Eucalypt identifiers are kebab-case: after the initial
letter, an unquoted name may contain hyphens, digits, and the characters
* ! ? _. So x-2 is not x - 2 — it lexes as a single identifier
named x-2:
x: 10r: x-2 # r is not 8 — 'x-2' is one nameerror: unresolved variable 'x-2'Gotcha: this is asymmetric with the other arithmetic operators,
because +, /, <, >, = and friends are not identifier
characters, but - and * are:
r: x+1 # => x + 1 (+ is not an identifier character)r: x-1 # => identifier 'x-1' (- IS an identifier character)r: x*2 # => identifier 'x*2' (* IS an identifier character)Leading digits also disambiguate — the lexer only starts a normal
identifier on a letter, so 2-x is 2 - x, while x-2 is one name. And a
space after the hyphen forces the operator reading, but a space before
it makes the -2 a negative literal in catenation position:
r: 2-x # => 2 - x (subtraction — identifiers can't start with a digit)r: x - 2 # => x - 2 (spaces on both sides — subtraction, the fix)r: x -2 # => catenation of x and the literal -2 (calls -2 as a function)Rule: put spaces around - (and *) whenever you mean the arithmetic
operator next to a name: write x - 2, never x-2. This bites hardest
right after another operator, where the eye reads arithmetic but the lexer
reads a name: n * x-2 is n * (x-2) with x-2 unresolved; you want
n * x - 2.
Division Operators
Section titled “Division Operators”/ Is Floor Division
Section titled “/ Is Floor Division”Problem: The / operator performs floor division (integer
division), not precise division.
Gotcha: 7 / 2 evaluates to 3, not 3.5.
Example:
7 / 2 # => 3 (floor division)7 ÷ 2 # => 3.5 (exact division)Rule: Use ÷ for exact/precise division. Use / only when you
want integer (floor) division.
Cons Patterns vs Normal Lists
Section titled “Cons Patterns vs Normal Lists”The [h : t] cons pattern is only valid in a function parameter position.
A colon inside a list literal in an expression context is not valid:
# Valid — cons pattern in a function parameterlist-head([h : t]): h
# Invalid — colon is not a list separator in expression contextbad: [1 : rest] # parse errorIn expression context, use the ‖ cons operator (precedence 55) or the
cons prelude function:
xs: [1, 2, 3]first: xs head # = 1rest: xs tail # = [2, 3]built: 1 ‖ [2, 3] # = [1, 2, 3]also: cons(1, [2, 3]) # = [1, 2, 3]Block-Dot Lookup Applies to Any Block Literal
Section titled “Block-Dot Lookup Applies to Any Block Literal”The generalised lookup syntax {...}.field and {...}.(expr) works on any
block literal, not only IO monadic blocks. The dot binds the lookup to the
block immediately to its left:
# Field lookup on a plain block{ x: 1, y: 2 }.x # → 1
# Parenthesised expression scoped over the block's bindings{ x: 1, y: 2 }.(x + y) # → 3
# The same syntax is used for IO monadic block return expressions{ :io r: io.shell("echo hello") }.(r.stdout){ :io r: io.shell("echo hello") }.r.stdoutPrecedence: . binds tightly (precedence 90), so the lookup attaches to
the block literal, not to the result of any surrounding expression. Use
parentheses when you need to apply a lookup to a computed value:
# Parsed as: list (head.name) — probably not what you wantlist head.name
# Correct: (list head).name(list head).nameIO monadic block desugaring: { :io r: cmd }.(expr) desugars to
io.bind(cmd, lambda(r). io.return(expr)). The .() return expression is
part of the general block-dot syntax, not IO-specific.
Bare-expression files: A .eu file containing only a block-dot
expression (no outer key: declaration) is supported when the expression
starts with a block literal {...}:
# This works as a standalone .eu file:{ :io r: io.shell("echo hello") }.(r.stdout)Block Field Names Shadow Outer Bindings — {x: x} Is Always Self-Reference
Section titled “Block Field Names Shadow Outer Bindings — {x: x} Is Always Self-Reference”Problem: Every declaration inside a block literal introduces a new binding
that is visible to all other expressions in that block, including its own
right-hand side. The name on the left of : immediately shadows any outer
binding with the same name, so {x: x} does not copy an outer x into the
block — it creates a self-referential binding that refers to itself:
# WRONG — infinite loop: cmd refers to itself, not the function parametershell-spec(cmd): {:io-shell cmd: cmd, timeout: 30}Running eu -e '{cmd: cmd}' gives error: infinite loop detected: binding refers to itself.
Why it bites functions: When a function parameter has the same name as a block field you want to populate, the RHS expression sees the block’s own binding rather than the parameter:
fn(cmd): {cmd: cmd} # cmd: cmd is self-reference — fn's parameter is invisibleFix: Use a different name for the function parameter so it is not shadowed:
# Correct: parameter c is not shadowed by the block field cmdshell-spec(c): {:io-shell cmd: c, timeout: 30}Rule: Never write {key: key} expecting it to read an outer binding named
key. If you need a block field to hold a value from an outer scope, the outer
name and the field name must differ.
Sequential Bindings: Use :let Blocks, Not let … in
Section titled “Sequential Bindings: Use :let Blocks, Not let … in”Eucalypt has no let … in expression syntax (as in Haskell or Standard ML).
Writing result: let x: 1 in x + 2 is a runtime error — let is a prelude
value (the identity monad) and in is unresolved.
The eucalypt idiom for sequential, non-self-referential bindings is a :let
block:
result: { :let x: 1 y: x + 2}.yThe :let prefix marker desugars to a monadic bind, so y can safely
reference x without the self-reference gotcha that affects ordinary block
bindings ({ x: expr y: x + 1 } would make x and y mutually
self-referential).
A :let binding may even reuse a name from the enclosing scope — the one
case where name: name … is not self-reference — because its right-hand side
is evaluated in the outer scope, before the new binding takes effect:
normalise(xs): { :let xs: xs map(_ + 1) }.xsshifted: normalise([1, 2, 3]) # => [2, 3, 4]This is the idiom to reach for when an ordinary { name: name … } would
self-reference — common when a renderer maps over a parameter it would rather
keep calling by its own name.
Why this matters: Before let was defined as a prelude name, attempts to
write let x: 1 in x + 2 gave a diagnostic error “eucalypt has no ‘let’
expression”. That specific hint is no longer raised; the error now falls through
to “unresolved variable ‘in’”. The :let block pattern is the correct
replacement.
Multiple Imports Go in One Metadata Block
Section titled “Multiple Imports Go in One Metadata Block”A file has one unit metadata block — the first block expression at the top of the file. If you need multiple imports, list them in that single block. Do NOT write separate blocks for each import.
# WRONG — the second block is a separate expression, not more metadata{ import: "state.eu" }{ import: "lens.eu" }
# RIGHT — one metadata block with a list of imports{ import: ["state.eu", "lens.eu"] }
# RIGHT — one block with imports and other metadata{ import: ["state.eu", "lens.eu"] doc: "My module" }The wrong pattern causes a compiler error because only the first block is unit metadata — the second becomes an anonymous block declaration catenated into the metadata expression.
Type Annotation String Escaping
Section titled “Type Annotation String Escaping”Record Braces in Type Strings Require {{ Escaping
Section titled “Record Braces in Type Strings Require {{ Escaping”Type annotation values (type:, types:) are ordinary eucalypt strings.
{ inside a eucalypt string starts string interpolation — it does
not produce a literal { for the type parser.
Any record type written in a type annotation string must escape braces
with {{ and }}:
# WRONG — {..r} triggers string interpolation` { type: "{..r} -> {..r}" }pass-through(x): x
# RIGHT — use {{ and }} for literal braces` { type: "{{..r}} -> {{..r}}" }pass-through(x): x
# WRONG — {name: string} triggers interpolation` { type: "{name: string, age: number, ..} -> string" }greet(p): "Hello, {p.name}!"
# RIGHT` { type: "{{name: string, age: number, ..}} -> string" }greet(p): "Hello, {p.name}!"The same applies to types: unit metadata values:
# RIGHT — escape braces in types: values too{ types: { Person: "{{name: string, age: number}}" } }When escaping is NOT needed: type strings that contain no { at all
never need escaping. Simple function types and built-in type constructors
are fine as-is:
` { type: "number -> number" } # fine — no braces` { type: "[a] -> a" } # fine` { type: "IO(block)" } # fine — parens, not braces` { type: "Lens(a, b) -> a -> b" } # fine` { type-def: "Point" } # fine — just a name, no bracesLiteral Types in Annotations
Section titled “Literal Types in Annotations”Two things to remember when a type: annotation contains literal types:
- Literal string types need c-string escapes for the quotes —
c"\"block\" | \"log\"". A plain"..."string does not process\". (Literal symbol types like:blockhave no quotes, so a plain string is fine.) - Mind
|/->precedence —->binds tighter, so a disjunction in argument position needs brackets:(:block | :log) -> bool, not:block | :log -> bool(which is an overloaded-function type). Naming the union in atypes:alias avoids the question.
The ! Asserted-Type Prefix
Section titled “The ! Asserted-Type Prefix”A type: (or types:) annotation string that begins with ! is an
asserted annotation: the checker trusts it without verifying the
body. The ! is stripped and the remainder parsed as the type; the
declaration is simply taken to have that type, whatever its right-hand
side actually is.
Why it exists: it lets you hand the checker a type it could not (or
should not) infer — for example a closed record shape so that
lookup(:key, …) resolves precisely, where the inferred open shape would
not warn on a key typo. This is the !{{…}} you may see in the
Type Checking guide:
` { type: "!{{name: string, age: number}}" }person: { name: "Alice", age: 30 }
lookup(:naem, person) # now warns: unknown record key :naemGotcha: because the body is not checked, an asserted annotation
silences a genuine mismatch. A plain annotation catches it; adding !
makes the warning disappear:
# Plain annotation — the checker verifies the body and WARNS:` { type: "number" }x: "hello" # warning: expected number, found "hello"
# Asserted — the checker trusts the annotation and stays SILENT:` { type: "!number" }x: "hello" # no warning, even though x is a string$ eu check plain.euwarning: expression type does not match annotation ┌─ plain.eu:1:1 ... expected number, found "hello"
$ eu check asserted.eu# (no output — asserted annotation trusted)Rule: reach for ! only to supply a type the checker cannot verify
for itself, never to quiet a warning you have not understood — an asserted
type is a promise the checker will believe and propagate to every use
site, so a wrong one hides the mistake and misleads everything downstream.
Flow-Sensitive Narrowing and User-Defined Branchers
Section titled “Flow-Sensitive Narrowing and User-Defined Branchers”=> (Clause) vs //=> (Assertion)
Section titled “=> (Clause) vs //=> (Assertion)”The => / ⇒ operator (precedence 15) builds a cond clause
(condition => result). It looks similar to the assertion meta-operator
//=> (precedence 5) but has a completely different purpose:
# CLAUSE — builds a cond branch; result is a list elementcond[x > 0 => "positive", "non-positive"]
# ASSERTION — checks a value equals the RHS at meta-evaluation time` { result //=> "positive" }result: "positive"Mixing these up produces confusing type or parse errors.
Non-Structural Brancher Wrappers Disable Narrowing
Section titled “Non-Structural Brancher Wrappers Disable Narrowing”Flow-sensitive narrowing only applies when the checker can verify that
a user function is a structural pass-through of if — i.e. its
body is exactly if(condition, true-branch, false-branch) with
arguments forwarded in order. A wrapper that ignores one branch, reorders
arguments, or adds logic is treated as an opaque function:
# STRUCTURAL — recognised as If-shaped; narrowing firesmy-if(c, t, f): if(c, t, f)
` { type: "(number | string) → number" }safe-add(x): my-if(x number?, x + 1, 0) # no warning
# NON-STRUCTURAL — not a brancher; narrowing does NOT firealways-true(c, t, _f): t
` { type: "(number | string) → number" }safe2(x): always-true(x number?, x + 1, 0) # x is still number|string in bodyThe second example does not produce false-positive warnings because
always-true is not narrowing-aware — x retains its declared type
number | string throughout the body, which is type-safe here.
head on an Empty List Produces a Type Warning
Section titled “head on an Empty List Produces a Type Warning”The type checker tracks list emptiness. [] synthesises as List(Never),
which means head [] is flagged as a potential error:
# WARNING — [] is List(Never); head on an empty listbad: [] head
# OK — non-empty literal is Tuple([number]); head gives numberok: [42] headTo use head safely on a list of unknown size, guard with nil?:
` { type: "[number] → number" }safe-head(xs): if(xs nil?, 0, xs head) # xs is NonEmpty([number]) in the false branchOr annotate the input as NonEmpty([T]) when the caller guarantees
non-emptiness.
:suppress Leaks Through References
Section titled “:suppress Leaks Through References”` :suppress hides a binding from output, but the flag travels with
the binding’s value. Reference that value somewhere else and the field
it lands in silently disappears too.
# WRONG — log4j is suppressed, so the @id field it feeds is dropped` :suppresslog4j: "pkg:maven/log4j-core@2.17.1"
entry: { '@id': log4j } # renders as {} — @id silently goneSuppress a block rather than a value you reference; members looked up out of it are clean:
` :suppresspurls: { log4j: "pkg:maven/log4j-core@2.17.1" }
entry: { '@id': purls.log4j } # => { "@id": "pkg:maven/log4j-core@2.17.1" }Rule: only ` :suppress a binding you don’t reference elsewhere; to
hide values you do reference, group them in a block and suppress that.
Idiot Bracket Gotchas
Section titled “Idiot Bracket Gotchas”Single-Item Idiot Brackets Still Pass a List
Section titled “Single-Item Idiot Brackets Still Pass a List”Idiot brackets always collect their contents into a list before calling the function, even when there is only one item:
⟦ xs ⟧: xs # xs is always a list
single: ⟦ 42 ⟧ # calls ⟦⟧([42]), not ⟦⟧(42)# single => [42], not 42If you expect a scalar, extract the head or use a named parameter with destructuring:
# Extract the head to use a single item as a scalar⌈ [x] ⌉: x ceiling # destructure the single element⌈ 3.7 ⌉ # => 4The prelude ⌈⌉ and ⌊⌋ bracket pairs do this automatically:
they destructure [x] so ⌈3.7⌉ works as expected.
Multi-Token Items Must Be Parenthesised
Section titled “Multi-Token Items Must Be Parenthesised”Items inside idiot brackets are separated by whitespace. A compound
expression such as x + 1 is two items (x and + 1), not one:
⟦ xs ⟧: xs
# THREE items — x, +, 1result: ⟦ x + 1 ⟧ # => [x, +, 1] (+ is the section (+ _))
# ONE item — the expression x + 1result: ⟦ (x + 1) ⟧ # => [x + 1]Parenthesise any expression that should be treated as a single item.
Juxtaposed Call After a Bracket Expression
Section titled “Juxtaposed Call After a Bracket Expression”A bracket expression can be followed immediately by [args] or
{block} to call the result with a further argument. This is valid
syntax, but be aware that the [...] is not parsed as list syntax
here — it is a juxtaposed call with a list argument:
⟦ g ⟧[xs] # evaluate ⟦g⟧, then call the result with list xsMonad Bracket Restrictions
Section titled “Monad Bracket Restrictions”Empty Monad Brackets Are an Error
Section titled “Empty Monad Brackets Are an Error”Monad brackets (e.g. ⟦⟧) cannot be empty. An empty monadic block
has no declarations to bind, so it is meaningless. The desugarer
produces an EmptyMonadicBlock error:
# ERROR — empty monad bracketsresult: ⟦⟧.42
# CORRECT — at least one declaration requiredresult: ⟦ x: some-action ⟧.xThis also applies to block-metadata monadic blocks:
# ERROR — empty monadic blockresult: { :io }.42
# CORRECTresult: { :io r: io.return(42) }.r