Skip to content
eucalypt
v0.15.0

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

A binary operator is declared by writing the operand names and the operator symbol in parentheses:

(x <+> y): x + y + 1
result: 3 <+> 4
result: 8

Operator names use symbolic characters: +, -, *, /, <, >, |, &, !, @, #, ~, ^, and any Unicode symbol or punctuation characters.

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:

(★): 42
answer: ★

Prefix operators have the operator before the operand:

(¬ x): not(x)
result: ¬ true
result: false

Postfix operators have the operator after the operand:

(x !!): x * x
result: 5 !!
result: 25

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:

Terminal window
eu -e '1 + 2 * 3'
7

Because * (precedence 80) binds tighter than + (precedence 75), this is parsed as 1 + (2 * 3), not (1 + 2) * 3.

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.

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 * y

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

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 integer
b: 2.0 ^ 63 # a float, as an operand is a float
c: 2 ^ 63 # error: numeric overflow

An integer raised to a negative integer power, such as 2 ^ (0 - 1), is a float (0.5).

Two special operators are provided for testing:

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

Like //= but returns the asserted value (not a boolean) on success, and also attaches the assertion as metadata:

checked: 2 + 2 //=> 4 # checked: 4

Both are useful for embedding tests and sanity checks in code.

Attach metadata to any value:

tagged: 42 // { note: "the answer" }

The metadata can be retrieved with meta:

note: meta(tagged).note
note: the answer

See Advanced Topics for more on metadata.

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 << overlay
base:
a:
x: 1
y: 2
b: 3
overlay:
a:
y: 9
z: 10
result:
a:
x: 1
y: 9
z: 10
b: 3

Concatenate two lists:

Terminal window
eu -e '[1, 2] ++ [3, 4]'
- 1
- 2
- 3
- 4

The dot operator can be used as a section to create lookup functions:

Terminal window
eu -e '[{x: 1}, {x: 2}, {x: 3}] map(.x)'
- 1
- 2
- 3

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

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

  • 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 precedence and associates on custom operators
  • The prelude provides standard arithmetic, comparison, boolean, and utility operators