Skip to content
eucalypt
v0.15.0

Eucalypt by Example

This page presents a collection of worked examples showing how eucalypt solves real-world problems. Each example includes the problem, the eucalypt code, and the expected output.

Problem: Convert a JSON configuration file to YAML.

Terminal window
echo '{"database": {"host": "db.example.com", "port": 5432}}' | eu

Output:

database:
host: db.example.com
port: 5432

Eucalypt reads JSON natively and defaults to YAML output. No code needed.

Problem: Given a list of users in JSON, extract just their names.

Terminal window
eu u=- -e 'u map(.name)' <<'JSON'
[
{"name": "Alice", "role": "admin"},
{"name": "Bob", "role": "user"},
{"name": "Charlie", "role": "user"}
]
JSON

Output:

- Alice
- Bob
- Charlie

The _ is an expression anaphor – _.name means “look up name in whatever the argument is”.

Problem: From a list of products, find those over a price threshold and format them.

products.eu
products: [
{ name: "Widget" price: 9.99 },
{ name: "Gadget" price: 24.99 },
{ name: "Gizmo" price: 49.99 },
{ name: "Doohickey" price: 4.99 }
]
expensive: products
filter(.price > 20)
map(.name str.to-upper)
Terminal window
eu products.eu -e expensive

Output:

- GADGET
- GIZMO

4. Generating Configuration with Shared Defaults

Section titled “4. Generating Configuration with Shared Defaults”

Problem: Generate environment-specific configs that share common defaults.

config.eu
base: {
app: "my-service"
port: 8080
log-level: "info"
db: { host: "localhost" port: 5432 }
}
production: base << {
log-level: "warn"
db: { host: "prod-db.internal" }
}
staging: base << {
db: { host: "staging-db.internal" }
}
Terminal window
eu config.eu -e production -j

Output:

{
"app": "my-service",
"port": 8080,
"log-level": "warn",
"db": {
"host": "prod-db.internal",
"port": 5432
}
}

The << operator deep-merges blocks, so nested keys like db.port are preserved while db.host is overridden.

Problem: Read a CSV file and output as a JSON array.

Given people.csv:

name,age,city
Alice,30,London
Bob,25,Manchester
Charlie,35,Edinburgh
Terminal window
eu rows=people.csv -j -e 'rows map(.name)'

Output:

["Alice", "Bob", "Charlie"]

Or to transform the data:

Terminal window
eu rows=people.csv -j -e 'rows map{ name: •0.name age: •0.age num }'

This converts age from string to number (CSV values are always strings).

Problem: Generate AWS availability zone names from a list of zone letters.

Terminal window
eu -e '["a", "b", "c"] map("eu-west-2{}")'

Output:

- eu-west-2a
- eu-west-2b
- eu-west-2c

The string "eu-west-2{}" is a function: {} is a string anaphor that takes one argument.

Problem: Combine values from several YAML files into a single output.

Given defaults.yaml:

timeout: 30
retries: 3

Given overrides.yaml:

timeout: 60
debug: true
Terminal window
eu defaults.yaml overrides.yaml

Output:

timeout: 60
retries: 3
debug: true

Later inputs override earlier ones. For a merged view with both available, use named inputs:

Terminal window
eu d=defaults.yaml o=overrides.yaml -e 'd << o'

Problem: Compute summary statistics from structured data.

sales.eu
sales: [
{ region: "North" amount: 1200 },
{ region: "South" amount: 800 },
{ region: "North" amount: 600 },
{ region: "South" amount: 1500 },
{ region: "East" amount: 900 }
]
` :suppress
amounts: sales map(.amount)
n: sales count
summary: {
total: amounts sum
count: n
average: (amounts sum) / n
max: amounts max-of
min: amounts min-of
}
Terminal window
eu sales.eu -e summary

Output:

total: 5000
count: 5
average: 1000
max: 1500
min: 600

Problem: Find all port numbers in a complex configuration.

Terminal window
eu -e '{
web: { host: "0.0.0.0" port: 80 }
api: { host: "0.0.0.0" port: 8080 }
db: { host: "localhost" port: 5432 }
cache: { host: "localhost" port: 6379 }
} deep-query("port")'

Output:

- 80
- 8080
- 5432
- 6379

deep-query recursively searches nested blocks. You can also use wildcards: deep-query("*.port", data) matches ports one level deep, while deep-query("**.port", data) matches at any depth.

Problem: Extract timestamps and levels from log lines.

logs.eu
lines: [
"2024-03-15 10:30:00 ERROR Connection timeout",
"2024-03-15 10:30:05 INFO Retry attempt 1",
"2024-03-15 10:30:10 ERROR Connection timeout",
"2024-03-15 10:30:15 INFO Connected"
]
` :suppress
parse(line): line str.match-with("(\S+ \S+) (\w+) (.*)") tail
parsed: lines map(parse) map({parts: •}.({
timestamp: parts first
level: parts second
message: parts nth(2)
}))
errors: parsed filter(.level = "ERROR")
Terminal window
eu logs.eu -e errors

Output:

- timestamp: "2024-03-15 10:30:00"
level: ERROR
message: Connection timeout
- timestamp: "2024-03-15 10:30:10"
level: ERROR
message: Connection timeout

Problem: Generate YAML with custom tags for CloudFormation.

cfn.eu
resource(type, props): {
Type: type
Properties: props
}
resources: {
MyBucket: resource("AWS::S3::Bucket", {
BucketName: "my-bucket"
})
MyQueue: resource("AWS::SQS::Queue", {
QueueName: "my-queue"
})
}

This example shows how a simple function can template repetitive structure.

Problem: Filter events by date and format the output.

events.eu
events: [
{ name: "Launch" date: t"2024-01-15" },
{ name: "Review" date: t"2024-06-01" },
{ name: "Release" date: t"2024-09-30" }
]
cutoff: t"2024-06-01"
upcoming: events
filter(.date >= cutoff)
map(.name)
Terminal window
eu events.eu -e upcoming

Output:

- Review
- Release

The t"..." syntax creates date-time literals that support comparison operators.

Problem: Build a key-value mapping from two parallel lists.

Terminal window
eu -e '["Alice", 30, "London"] zip-kv[:name, :age, :city]'

Output:

name: Alice
age: 30
city: London

zip-kv pairs up symbols as keys with values to produce a block. Note that zip-kv[:name, :age, :city] is shorthand for zip-kv([:name, :age, :city]) — when a function takes a single list or block argument, the outer parentheses can be omitted.

Problem: Write a reusable script that accepts command-line arguments.

greet.eu
name: io.args head-or("World")
times: io.args tail head-or("1") num
greetings: repeat("Hello, {name}!") take(times)
Terminal window
eu greet.eu -e greetings -- Alice 3

Output:

- Hello, Alice!
- Hello, Alice!
- Hello, Alice!

Arguments after -- are available via io.args as a list of strings. Use num to convert to numbers.

Problem: Find the unique tags across multiple items and compute overlaps.

items: [
{ name: "A" tags: ["fast", "reliable", "cheap"] },
{ name: "B" tags: ["fast", "expensive"] },
{ name: "C" tags: ["reliable", "cheap", "slow"] }
]
` :suppress
tag-sets: items map(.tags set.from-list)
all-tags: tag-sets foldl(set.union, ∅) set.to-list
common-tags: tag-sets foldl(set.intersect, tag-sets head) set.to-list
result: {
all: all-tags
common: common-tags
}
Terminal window
eu tags.eu -e result

Output:

all:
- cheap
- expensive
- fast
- reliable
- slow
common: []