Frequently Asked Questions
Getting Started
Section titled “Getting Started”How do I install eucalypt?
Section titled “How do I install eucalypt?”On macOS, use Homebrew:
brew install curvelogic/homebrew-tap/eucalyptOn Linux or macOS without Homebrew, use the install script:
curl -sSf https://raw.githubusercontent.com/curvelogic/eucalypt/master/install.sh | shYou can also download a binary from the
GitHub releases
page, or build from source with cargo install --path ..
Verify installation with:
eu versionHow do I convert between data formats?
Section titled “How do I convert between data formats?”Pass a file in one format and specify the output format with -x or
-j:
# YAML to JSONeu data.yaml -j
# JSON to YAML (default output)eu data.json
# YAML to TOMLeu data.yaml -x tomlWhat data formats does eucalypt support?
Section titled “What data formats does eucalypt support?”Input formats: YAML, JSON, JSON Lines (jsonl), TOML, EDN, XML,
CSV, plain text, and eucalypt’s own .eu syntax.
Output formats: YAML (default), JSON, TOML, EDN, and plain text.
Streaming input formats (for large files): jsonl-stream,
csv-stream, text-stream.
How do I use eucalypt in a pipeline?
Section titled “How do I use eucalypt in a pipeline?”eu reads from stdin by default when used in a pipe and writes to
stdout:
# Filter JSON from an APIcurl -s https://api.example.com/data | eu -e 'items filter(.active)'
# Transform and re-exportcat data.yaml | eu transform.eu -j > output.jsonUse -e to specify an expression to evaluate against the input data.
How do I pass arguments to a eucalypt program?
Section titled “How do I pass arguments to a eucalypt program?”Use -- to separate eu flags from program arguments:
eu program.eu -- arg1 arg2 arg3Inside your program, access them via io.args:
name: io.args head-or("World")greeting: "Hello, {name}!"Language
Section titled “Language”How do functions work in eucalypt?
Section titled “How do functions work in eucalypt?”Define functions with a parameter list after the name:
double(x): x * 2result: double(21) //=> 42Functions are curried – applying fewer arguments than expected returns a partially applied function:
add(x, y): x + yincrement: add(1)result: increment(9) //=> 10What is catenation?
Section titled “What is catenation?”Catenation is eucalypt’s pipeline syntax. Writing x f applies f to
x as a single argument:
add-one(x): x + 1result: 5 add-one //=> 6Chain multiple transforms by writing them in sequence:
double(x): x * 2add-one(x): x + 1result: 5 double add-one //=> 11This reads left to right: start with 5, double it (10), add one (11).
What are anaphora and when should I use them?
Section titled “What are anaphora and when should I use them?”Anaphora are implicit parameters that let you define simple functions without naming them. There are three kinds:
Expression anaphora (_, _0, _1): turn an expression into a
function.
squares: [1, 2, 3] map(_0 * _0) //=> [1, 4, 9]String anaphora ({}, {0}, {1}): turn a string template into
a function.
labels: [1, 2, 3] map("item-{}") //=> ["item-1", "item-2", "item-3"]Block anaphora (•, •0, •1): turn a block into a function.
Use anaphora for simple, readable cases. For anything more complex, prefer a named function. See Anaphora for details.
Why is there no lambda syntax?
Section titled “Why is there no lambda syntax?”Eucalypt deliberately omits lambda expressions. Instead, use:
- Named functions for anything non-trivial
- Anaphora (
_,{}) for simple one-liners - Sections (
(+ 1),(* 2)) for operator-based functions - Partial application (
add(1)) for curried functions
# All equivalent ways to add one:add-one(x): x + 1result1: [1, 2, 3] map(add-one) //=> [2, 3, 4]result2: [1, 2, 3] map(_ + 1) //=> [2, 3, 4]result3: [1, 2, 3] map(+ 1) //=> [2, 3, 4]How does block merging work?
Section titled “How does block merging work?”When you write one block after another (catenation), they merge:
base: { a: 1 b: 2 }overlay: { b: 3 c: 4 }merged: base overlay //=> { a: 1 b: 3 c: 4 }The second block’s values override the first. This is a shallow
merge. For recursive deep merge, use the << operator:
base: { x: { a: 1 b: 2 } }extra: { x: { c: 3 } }result: base << extraHow do I handle the lookup precedence gotcha?
Section titled “How do I handle the lookup precedence gotcha?”The . (lookup) operator has higher precedence than catenation, so
xs head.id groups head.id into one unit first — and that unit,
not xs, is what gets applied: it parses as head.id(xs), not
(xs head).id. The ↑ (head) prefix operator binds even tighter
still: ↑xs.id means (↑xs).id, not ↑(xs.id).
Use explicit parentheses:
data: [{ id: 1 }, { id: 2 }]first-id: (data head).id //=> 1See Syntax Gotchas for more.
Data Processing
Section titled “Data Processing”How do I filter and transform lists?
Section titled “How do I filter and transform lists?”Use map to transform and filter to select:
numbers: [1, 2, 3, 4, 5, 6]small: numbers filter(< 4) //=> [1, 2, 3]doubled: numbers map(* 2) //=> [2, 4, 6, 8, 10, 12]Combine them in a pipeline:
result: [1, 2, 3, 4, 5, 6] filter(> 3) map(* 10) //=> [40, 50, 60]How do I look up values in nested blocks?
Section titled “How do I look up values in nested blocks?”Use chained . lookups for known paths:
config: { db: { host: "localhost" port: 5432 } }host: config.db.host //=> "localhost"For dynamic key lookup, use lookup with a symbol:
data: { name: "Alice" age: 30 }field: data lookup(:name) //=> "Alice"Use lookup-or to provide a default:
data: { name: "Alice" }age: data lookup-or(:age, 0) //=> 0How do I search deeply nested data?
Section titled “How do I search deeply nested data?”Use deep-find for recursive key search:
# Finds all values for key "id" at any depthids: data deep-find("id")Use lookup-path for a known sequence of keys:
data: { a: { b: { c: 42 } } }result: data lookup-path([:a, :b, :c]) //=> 42How do I sort data?
Section titled “How do I sort data?”Sort lists with sort-nums or sort-strs:
names: ["Charlie", "Alice", "Bob"]sorted: names sort-strs //=> ["Alice", "Bob", "Charlie"]nums: [5, 1, 3, 2, 4]sorted: nums sort-nums //=> [1, 2, 3, 4, 5]For sorting by a key, use sort-by-str or sort-by-num:
people: [{ name: "Zoe" age: 25 }, { name: "Amy" age: 30 }]by-name: people sort-by-str(.name)youngest: (by-name head).name //=> "Amy"How do I work with dates?
Section titled “How do I work with dates?”Use t"..." literals for date-time values:
meeting: t"2024-03-15T14:30:00Z"date-only: t"2024-03-15"before: t"2024-01-01" < t"2024-12-31" //=> trueSee Date, Time, and Random Numbers for parsing, formatting, and arithmetic.
Advanced
Section titled “Advanced”How do I attach metadata to declarations?
Section titled “How do I attach metadata to declarations?”Use the backtick (`) prefix:
` "Compute the square of a number"square(x): x * x
result: square(5) //=> 25Metadata can be a string (documentation) or a block with structured data:
` { doc: "Custom operator" associates: :left precedence: 75 }(l <+> r): l + rHow do imports work?
Section titled “How do imports work?”Imports are specified in declaration metadata using the import key:
{ import: "helpers.eu" }
result: helper-function(42)For named imports (scoped access):
{ import: "cfg=config.eu" }
host: cfg.hostSee Import Formats for the full syntax including git imports.
How do I write tests?
Section titled “How do I write tests?”Use the //=> assertion operator to check values inline:
double(x): x * 2result: double(21) //=> 42If the assertion fails, eucalypt panics with a non-zero exit code. Other assertion operators:
x: 5check1: (x > 3) //!check2: x //=? (> 0)How do I generate random values?
Section titled “How do I generate random values?”Use io.random for a stream of random floats, or pass --seed for
reproducible output:
die: random.int(6, io.random).value + 1eu --seed 42 game.euSee Random Numbers for the full API.
What are sets and how do I use them?
Section titled “What are sets and how do I use them?”The set namespace provides set operations. Convert lists to sets
with set.from-list:
sa: set.from-list([1, 2, 3, 4])sb: set.from-list([3, 4, 5, 6])common: sa set.intersect(sb) set.to-list //=> [3, 4]combined: sa set.union(sb) set.to-list sort-nums //=> [1, 2, 3, 4, 5, 6]diff: sa set.diff(sb) set.to-list sort-nums //=> [1, 2]Project
Section titled “Project”What licence is eucalypt released under?
Section titled “What licence is eucalypt released under?”Eucalypt is dual-licensed under the Apache License, Version 2.0 and the MIT License, at your option — the customary dual licence of the Rust ecosystem. The full texts are in LICENSE-APACHE and LICENSE-MIT.
Unless you state otherwise, any contribution you submit for inclusion in the project is dual-licensed on the same terms.