Operators
In this chapter you will learn:
- How to define custom nullary, binary, prefix, and postfix operators
- How precedence and associativity work
- How to control operator behaviour with metadata
- The built-in operators provided by the prelude
Defining Binary Operators
Section titled “Defining Binary Operators”A binary operator is declared by writing the operand names and the operator symbol in parentheses:
(x <+> y): x + y + 1
result: 3 <+> 4result: 8Operator names use symbolic characters: +, -, *, /, <, >,
|, &, !, @, #, ~, ^, and any Unicode symbol or
punctuation characters.
Nullary Operators
Section titled “Nullary Operators”A nullary operator takes no operands — it is a constant written as a symbol:
(∅): '__SET.EMPTY'result: ∅ set.to-list∅: []result: []Unlike prefix/postfix/binary operator declarations, a nullary declaration has no parameter list — structurally it is a property declaration, so (unlike a function) it is rendered in the output.
The empty set ∅ is the only nullary operator in the standard prelude,
but you can define your own:
(★): 42answer: ★Prefix and Postfix Operators
Section titled “Prefix and Postfix Operators”Prefix operators have the operator before the operand:
(¬ x): not(x)result: ¬ trueresult: falsePostfix operators have the operator after the operand:
(x !!): x * xresult: 5 !!result: 25Precedence
Section titled “Precedence”Without precedence rules, operator expressions would be ambiguous. In eucalypt, precedence determines which operators bind more tightly.
The prelude defines the standard precedence levels:
| Level | Name | Operators |
|---|---|---|
| 95 | prefix | ↑ (head) |
| 90 | lookup | ., ~ (safe lookup) |
| 88 | bool-unary | !, ¬ (prefix); ✓ (postfix not-null) |
| 88 | – | ∘, ; (composition) |
| 85 | exp | ^, !! (nth) |
| 80 | prod | *, /, ÷, % |
| 75 | sum | +, - |
| 60 | shift | (shift operators, reserved) |
| 55 | bitwise | (bitwise operators, reserved) — ‖ (cons) also uses this numeric level |
| 50 | cmp | <, >, <=, >= |
| 45 | append | ++, << |
| 42 | map | <$> (functor map) |
| 40 | eq | =, != |
| 35 | bool-prod | &&, ∧ |
| 30 | bool-sum | ||, ∨ |
| 20 | cat | (catenation) |
| 15 | clause | =>, ⇒ (cond clause builder) |
| 10 | apply | @ |
| 5 | meta | //, //<<, //=, //=>, //=?, //=?>, //! |
Higher numbers bind more tightly:
eu -e '1 + 2 * 3'7Because * (precedence 80) binds tighter than + (precedence 75),
this is parsed as 1 + (2 * 3), not (1 + 2) * 3.
Associativity
Section titled “Associativity”When the same operator (or operators at the same precedence) appear in sequence, associativity determines the grouping.
- Left-associative:
1 - 2 - 3=(1 - 2) - 3=-4 - Right-associative:
a -> b -> c=a -> (b -> c)
Most arithmetic and comparison operators are left-associative.
Setting Precedence and Associativity
Section titled “Setting Precedence and Associativity”Use declaration metadata to control your operator’s precedence and associativity:
` { associates: :left precedence: :sum }(x +++ y): x + y
` { associates: :right precedence: :prod }(x *** y): x * yPrecedence can be specified as:
- A named level:
:sum,:prod,:exp,:cmp,:eq,:bool-prod,:bool-sum,:append,:map,:bool-unary,:cat,:apply,:meta,:shift,:bitwise - A numeric value: any integer (higher binds tighter)
Associativity can be :left, :right, or omitted (defaults to
:left).
Integer Overflow
Section titled “Integer Overflow”Integers are signed 64-bit. When +, -, * or ^ on two such integers
gives a result outside that range, evaluation stops with a numeric overflow error
pointing at the operator, rather than losing precision:
a: 2 ^ 62 # 4611686018427387904, an integerb: 2.0 ^ 63 # a float, as an operand is a floatc: 2 ^ 63 # error: numeric overflowAn integer raised to a negative integer power, such as 2 ^ (0 - 1), is
a float (0.5).
The Assertion Operators
Section titled “The Assertion Operators”Two special operators are provided for testing:
//= (expect equals)
Section titled “//= (expect equals)”Expects the left side to equal the right side at runtime, returning
true on success. Panics if false (or, in eu test mode, returns
false instead of panicking):
result: 2 + 2 //= 4 # result: true//=> (assert equals with metadata)
Section titled “//=> (assert equals with metadata)”Like //= but returns the asserted value (not a boolean) on
success, and also attaches the assertion as metadata:
checked: 2 + 2 //=> 4 # checked: 4Both are useful for embedding tests and sanity checks in code.
The Metadata Operator //
Section titled “The Metadata Operator //”Attach metadata to any value:
tagged: 42 // { note: "the answer" }The metadata can be retrieved with meta:
note: meta(tagged).notenote: the answerSee Advanced Topics for more on metadata.
The Deep Merge Operator <<
Section titled “The Deep Merge Operator <<”Deep merge combines two blocks, recursively merging nested blocks:
base: { a: { x: 1 y: 2 } b: 3 }overlay: { a: { y: 9 z: 10 } }result: base << overlaybase: a: x: 1 y: 2 b: 3overlay: a: y: 9 z: 10result: a: x: 1 y: 9 z: 10 b: 3The Append Operator ++
Section titled “The Append Operator ++”Concatenate two lists:
eu -e '[1, 2] ++ [3, 4]'- 1- 2- 3- 4Dot Sections
Section titled “Dot Sections”The dot operator can be used as a section to create lookup functions:
eu -e '[{x: 1}, {x: 2}, {x: 3}] map(.x)'- 1- 2- 3Idiot Brackets
Section titled “Idiot Brackets”Eucalypt lets you define custom Unicode bracket pairs that wrap and transform an expression. These are called idiot brackets (inspired by idiom brackets from applicative functor notation, but they are a general bracket overloading mechanism).
⌈ xs ⌉: xs map(_ * 2)
each-doubled: ⌈ 3 4 5 ⌉each-doubled: - 6 - 8 - 10The declaration ⌈ xs ⌉: body defines a function named ⌈⌉ that
takes one argument. Using ⌈ a b c ⌉ in an expression collects the
items into a list and calls the function with [a, b, c].
Any matching Unicode bracket pair can be used:
| Open | Close | Name |
|---|---|---|
⟦ |
⟧ |
Mathematical white square brackets |
⟨ |
⟩ |
Mathematical angle brackets |
⟪ |
⟫ |
Mathematical double angle brackets |
⌈ |
⌉ |
Ceiling brackets |
⌊ |
⌋ |
Floor brackets |
« |
» |
French guillemets |
(and several others — see the syntax reference for the full list.)
Idiot brackets can also be given a monadic interpretation for
sequencing — see Monads and the monad() Utility for
details on bracket pair definitions with :monad metadata.
Key Concepts
Section titled “Key Concepts”- Operators are declared with symbolic names in parentheses:
(x op y):,(op x):,(x op): - Precedence controls binding strength; higher numbers bind tighter
- Associativity determines grouping for equal-precedence operators
- Use metadata to set
precedenceandassociateson custom operators - The prelude provides standard arithmetic, comparison, boolean, and utility operators