eucalypt

eucalypt is a tool, and a little language, for generating and transforming structured data formats like YAML, JSON and TOML.

If you use text-based templating to process these formats or you pipe these formats through several different tools or build steps, eucalypt might be able to help you generate your output more cleanly and with fewer cognitive somersaults.

eucalypt is a purely functional language that can be used quickly and easily from the command line.

It has the following features:

• a concise native syntax that allows you to define data, functions, and operators
• a simple embedding into YAML files to support in-place manipulation of the data (a la templating)
• facilities for manipulating blocks (think JSON objects, YAML mappings)
• facilities for manipulating text including string interpolation and regular expressions
• an ergonomic command line interface and access to environment variables
• metadata annotations and numerous extension points
• a prelude of built-in functions, acting like a standard library

It can currently read YAML, JSON, JSON Lines, TOML, EDN, XML, CSV and plain text and eucalypt's own ("eu") syntax and it can export YAML, JSON, TOML, EDN or plain text.

Warning: eucalypt is still in an early phase of development and subject to change.

A lightning tour

Eucalypt has a native syntax for writing blocks, lists and expressions. The YAML embedding consists of a few YAML tags used to embed eucalypt expression in YAML so a basic understanding of the native syntax is helpful.

A few micro-examples should help give a flavour of eucalypt's native syntax. If you want to follow along, see Quick Start for notes on installation.

Example 1

Here is a simple one:

target-zones: ["a", "b", "c"] map("eu-west-1{}")

You can put this in a file named test.eu and run it with just:

eu test.eu

This outputs the following YAML:

target-zones:
  - eu-west-1a
  - eu-west-1b
  - eu-west-1c

As an aside, although we're looking at the native eucalypt syntax here, this example could just as easily be embedded directly in a YAML file using the !eu tag. Pop the following in a test.yaml file and process it with: eu test.yaml. You'll get the same result.

target-zones: !eu ["a", "b", "c"] map("eu-west-1{}")

First, this example illustrates how we apply transformations like map simply by concatenation. This "pipelining" or "catenation" is the natural way to apply transformations to values in eucalypt.

In fact this is simply a function call with the arguments rearranged a bit. In this example, map is a function of two parameters. Its first argument is provided in parentheses and its second argument is the value of what came before.

Note: Users of languages like Elixir or OCaml may recognise an implicit |> operator here. Clojure users may see an invisible threading macro. Note that writing elements next to each other like this gives you the reverse of what you might expect in Haskell or OCaml or Lisp: we write x f not f x.

There is a lot of freedom in eucalypt to express ideas in different ways and develop colourful and cryptic expressions. In a larger or more ambitious language this could be viewed as rope to hang yourself with. Please be careful.

The string template, "eu-west-1{}", actually defines a function of one argument that returns a string. The key ingredients here are:

• the interpolation syntax "{...}" which allows values to be inserted into the string
• the (hidden) use of numeric anaphora in the interpolation syntax ({0}, {1}, {2}, ...) which cause the string to define a function, not just sequence of characters
• the use of the unnumbered anaphor ({}) which is numbered automatically for us, so in this case, {} is a convenient synonym for {0} - the first argument

Note: Anaphora crop up in various contexts in eucalypt and are generally preferable to the full generality of lambdas. If the idea is too complex to be expressed with anaphora, it should generally be explicitly named.

So:

a: 42 "The answer is {0}"

renders as

a: The answer is 42

eucalypt also has expression anaphora and block anaphora

Note: Users of Groovy or Kotlin may recognise an equivalent of the it parameter. Seasoned Lisp hackers are familiar with anaphoric macros. Clojure users will recognise the %, %1, %2 forms from #(...) contexts. Unlike % repeated uses of unnumbered anaphora in eucalypt refer to different parameters. "{}{}" is a two-argument function which concatenates strings.

Back to:

target-zones: ["a", "b", "c"] map("eu-west-1{}")

The whole line is a declaration. Declarations come in several types - this one is a property declaration. A block is written as a sequence of declarations enclosed in braces. For example:

{
  w: "foo" # a string
  x: 3     # a whole number
  y: 22.2  # a floaty number
  z: true  # the truth
}

(The # character introduces a comment which is ignored.)

Unlike YAML, indentation is never significant.

Unlike JSON, commas are not needed to separate declarations. Instead, the eucalypt parser determines the declarations mainly based on the location of colons. You can write:

{ x: 1 increment negate y: 2 }

...and eucalypt knows it's two declarations.

If that's a bit too crazy for you, then feel free to insert the commas. Eucalypt will accept them. Any of these are okay:

ok1: { a: 1 b: 2 c: 3 }
ok2: { a: 1, b: 2, c: 3 }
ok3: { a: 1, b: 2, c: 3, }

Note: Unlike Clojure which makes commas optional by treating them as whitespace, Eucalypt demands that if you are going to put commas in, they have to be in the right place, at the end of declarations. So you can use them if you believe it makes things clearer but you are prevented from using them in ways which would misguide.

Our target-zones property declaration is at the top level so need not be surrounded by braces. Nevertheless it is in a block: the top level block, known as a unit, that is defined by the file that contains it. You can imagine the braces to be there if you like.

As a final point on this example, it is probably worthwhile documenting declarations. eucalypt offers an easy way to do that using declaration metadata which we squeeze in between a leading backtick and the declaration itself:

` "AZs to deploy alien widgets in"
target-zones: ["a", "b", "c"] map("eu-west-1{}")

In fact, all sorts of things can be wedged in there, but if a string appears on its own, it is interpreted as documentation.

Example 2

Let's look at another small example:

character(name): {
  resource-name: name
  created: io.epoch-time
}

prentice: character("Pirate Prentice") {
  laser-colour: "red"
}

slothrop: character("Tyrone Slothrop") {
  eye-count: 7
}

We've introduced a new type of declaration here of the form f(x):. This is a function declaration.

Remember we saw a property declaration earlier. Eucalypt also has operator declarations but we'll ignore those for now.

The function declaration declares a function called character, which accepts a single parameter (name) and returns a block containing two properties.

Functions, like everything else in eucalypt, are declared in and live in blocks but they are left out when output is rendered, so you won't see them in the YAML or JSON that eucalypt produces.

The braces in the definition of character are there to delimit the resulting block - not to define a function body. A function that returned a number would not need them:

inc(x): x + 1 # this defines an increment function

The next important ingredient in this example is block catenation.

Blocks can be treated as functions of a single parameter. When they are applied as functions, the effect is a block merge.

We've already seen that functions can be applied to arguments by concatenation.

So writing one block after another produces a merged block. It contains the contents of the second block merged "on top" of the first.

There is more to be said on block merge, but for now:

{ a: 1 } { b: 2 } evaluates to { a: 1 b: 2 }.

and

{ a: 1 } { a: 2 } evaluates to { a: 2 }.

In our example, the resulting YAML is just:

prentice:
  resource-name: Pirate Prentice
  created: 1526991765
  laser-colour: red

slothrop:
  resource-name: Tyrone Slothrop
  created: 1526991765
  eye-count: 7

As you can see, io.epoch-time evaluates to a unix timestamp.

This metadata is generated once at launch time, not each time the expression is evaluated. eucalypt the language is a pure functional language, and there are no side-effects or non-deterministic functions (although its command line driver can perform all sorts of side-effects as input to the evaluation and as output from the evaluation and there are one or two dirty tricks in the debugging functions). For this reason, prentice and slothrop will have the same timestamps.

Block merge can be a useful means of generating common content in objects. The common content can appear first as in this case, allowing it to be overridden. Or it could be applied second allowing it to override the existing detail. Or a mixture of both. Many more sophisticated means of combining block data are available too.

Note: This merge is similar to the effect of merge keys in YAML, where a special << mapping key causes a similar merge to occur. Not all YAML processors support this and nor does eucalypt at present, but it probably will some day.

Be aware that eucalypt has nothing like virtual functions. The functions in scope when an expression is created are the ones that are applied. So if you redefine an f like this, in an overriding block...

{ f(x): x+1 a: f(2) } { f(x): x-2 }

...the definition of a will not see it.

a: 3

So block merge is only very loosely related to object oriented inheritance. Also by default you only get a shallow merge - deep merges are provided in the standard prelude. It is possible that a deep merge will become the default for block catenation in future.

Many more complicated ways of processing blocks are possible using functions, block anaphora and standard prelude functions.

Quick tour of the command line

On macOS you can install the eu command line tools using Homebrew with:

brew install curvelogic/homebrew-tap/eucalypt

Check the version you are running with:

eu version

eu is intended to be easy to use for common tasks and does its best to allow you to say what you want succinctly. The intention is to be easy to use in pipelines in combination with other tools like jq.

By default, it runs in ergonomic mode which will make a few assumptions in order to allow you to be a little less explicit. It also pulls in user-specific declarations from ~/.eucalypt. For repeatable builds and scripted usage, it is better to turn ergonomic mode off using the -B (--batch) switch.

The simplest usage is to specify a eucalypt file to evaluate and leave the default render format (YAML) and output (standard out) alone.

> eu test.eu

eu with no arguments will generally be taken to specify that input is coming from standard in. So the above is equivalent to:

> cat test.eu | eu

There is an -x switch to control output format explicitly (setting "yaml", "json", "text", "csv" or "eu") but for the very common case of requiring JSON output there is a shortcut:

> eu test.eu -j

You can, of course, redirect standard output to a file but if you specify the output file explicitly (with -o), eu will infer the output format from the extension:

> eu test.eu -o output.json # equivalent to eu test.eu -j > output.json

Small snippets of eucalypt can be passed in directly using the -e switch.

> eu -e '{ a: 8 * 8 }'

The fact that eucalypt makes relatively infrequent use of single quotes makes this straightforward for most shells.

By default, eu evaluates the entirety of the loaded source and uses all of it to render the result, leaving out any function values and other non-renderable content.

It is possible to select just parts of the eucalypt for rendering:

1. A declaration in the source may be identified as the main target using the :main declaration metadata and we become the part rendered by default.
2. targets may be defined and named using the :target declaration metadata and those targets can then be specified using the -t option to eu
3. The -e option can be used in addition to other source file(s) to identify an expression to be rendered (e.g. eu test.eu -e x.y.z)

So eu's ability to read JSON and YAML natively combined with the last options give a simple way to pick values out of structured data which can be very handy for "querying" services that return YAML or JSON data.

> aws s3api list-buckets | eu -e 'Buckets map(lookup(:Name))'

There is much more to this story. For instance eu can:

• accept several inputs to make definitions in earlier inputs available to subsequent inputs eu test1.eu test2.eu test3.eu
• accept YAML and JSON files as pure data to be merged in: eu data.yaml tools.eu
• accept YAML or JSON annotated with eucalypt to execute: eu data.yaml
• override the default extensions: eu yaml@info.txt
• automatically use Eufile files in the current folder hierarchy

See CLI Reference for more complete documentation.

What is Eucalypt?

Eucalypt is a tool, and a little language, for generating, templating, rendering and processing structured data formats like YAML, JSON and TOML.

If you use text-based templating to process these formats or you pipe these formats through several different tools or build steps, eucalypt might be able to help you generate your output more cleanly and with fewer cognitive somersaults.

Key Features

• A concise native syntax for defining data, functions, and operators
• A simple embedding into YAML files for in-place manipulation (a la templating)
• Facilities for manipulating blocks (think JSON objects, YAML mappings)
• String interpolation and regular expressions
• An ergonomic command line interface with environment variable access
• Metadata annotations and numerous extension points
• A prelude of built-in functions acting as a standard library

Supported Formats

Input: YAML, JSON, JSON Lines, TOML, EDN, XML, CSV, plain text, and eucalypt's own .eu syntax.

Output: YAML, JSON, TOML, EDN, or plain text.

When to Use Eucalypt

Eucalypt is a good fit when you need to:

• Transform data between structured formats (e.g. JSON to YAML)
• Generate configuration files with shared logic
• Query and filter structured data from the command line
• Template YAML or JSON with embedded expressions
• Build data processing pipelines

Learn More

• Quick Start -- install eucalypt and run your first program
• Lightning Tour -- a quick taste of the syntax
• The Eucalypt Guide -- a progressive tutorial

Quick Start

Installation

On macOS via Homebrew

If you use Homebrew, you can install using:

brew install curvelogic/homebrew-tap/eucalypt

Linux / macOS (install script)

Alternatively, install the latest release binary directly:

curl -sSf https://raw.githubusercontent.com/curvelogic/eucalypt/master/install.sh | sh

This installs to ~/.local/bin. Set EUCALYPT_INSTALL_DIR to override the install location.

Otherwise binaries for macOS are available on the releases page.

On Linux

x86_64 and aarch64 binaries built in CI are available on the releases page.

On Windows

Sorry, haven't got there yet. But you could try installing from source.

From source

You will need a Rust installation and cargo.

Build and install should be as simple as:

cargo install --path .

Testing your installation

eu --version

...prints the version:

eu 0.3.0

...and...

eu --help

...shows command line help:

A functional language for structured data

Usage: eu [OPTIONS] [FILES]... [COMMAND]

Commands:
  run           Evaluate eucalypt code (default)
  test          Run tests
  dump          Dump intermediate representations
  version       Show version information
  explain       Explain what would be executed
  list-targets  List targets defined in the source
  fmt           Format eucalypt source files
  lsp           Start the Language Server Protocol server
  help          Print this message or the help of the given subcommand(s)

Arguments:
  [FILES]...  Files to process (used when no subcommand specified)

Options:
  -L, --lib-path <LIB_PATH>                Add directory to lib path
  -Q, --no-prelude                         Don't load the standard prelude
  -B, --batch                              Batch mode (no .eucalypt.d)
  -d, --debug                              Turn on debug features
  -S, --statistics                         Print metrics to stderr before exiting
      --statistics-file <STATISTICS_FILE>  Write statistics as JSON to a file
  -h, --help                               Print help
  -V, --version                            Print version

Use eu <command> --help for detailed help on each subcommand.

Your first program

Create a file called hello.eu:

greeting: "Hello, World!"

Run it:

eu hello.eu

Output:

greeting: Hello, World!

Try JSON output:

eu hello.eu -j

{"greeting": "Hello, World!"}

Next steps

• Read the lightning tour for a quick taste of what eucalypt can do
• Work through The Eucalypt Guide for a progressive tutorial
• Browse Eucalypt by Example for worked examples

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.

1. Format Conversion: JSON to YAML

Problem: Convert a JSON configuration file to YAML.

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.

2. Extracting Fields from API Data

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

eu -e '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".

3. Filtering and Transforming Data

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)

eu products.eu -e expensive

Output:

- GADGET
- GIZMO

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" }
}

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.

5. CSV to JSON Conversion

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

eu rows=people.csv -j -e 'rows map(.name)'

Output:

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

Or to transform the data:

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

6. Generating Availability Zone Names

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

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.

7. Merging Multiple YAML Files

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

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:

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

8. Data Aggregation Pipeline

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
}

eu sales.eu -e summary

Output:

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

9. Querying Deeply Nested Configuration

Problem: Find all port numbers in a complex configuration.

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.

10. String Processing: Parsing Log Lines

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")

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

11. Templating CloudFormation Resources

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.

12. Working with Dates

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)

eu events.eu -e upcoming

Output:

- Review
- Release

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

13. Generating a Lookup Table

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

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.

14. Parameterised Scripts

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)

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.

15. Set Operations: Finding Unique Values

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
}

eu tags.eu -e result

Output:

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

Next Steps

• Work through The Eucalypt Guide for a progressive tutorial
• Browse the Prelude Reference for the full standard library
• See the CLI Reference for all command-line options

Blocks and Declarations

In this chapter you will learn:

• What blocks are and how they relate to structured data formats
• The three types of declarations: property, function, and operator
• How top-level files work as implicit blocks (units)
• How to annotate declarations with metadata

Blocks

A block is eucalypt's fundamental data structure. It corresponds to a JSON object, a YAML mapping, or a TOML table: an ordered collection of named values.

Blocks are written with curly braces:

person: {
  name: "Alice"
  age: 30
  role: "engineer"
}

Running this file produces:

person:
  name: Alice
  age: 30
  role: engineer

Blocks can be nested:

config: {
  database: {
    host: "localhost"
    port: 5432
  }
  cache: {
    host: "localhost"
    port: 6379
  }
}

Property Declarations

The simplest declaration is a property declaration: a name followed by a colon and an expression.

greeting: "Hello, World!"
count: 42
pi: 3.14159
active: true
nothing: null

These declare names bound to values. The values can be any expression: numbers, strings, booleans, null, lists, blocks, or computed expressions.

Commas are Optional

Declarations can be separated by commas or simply by whitespace. Line endings are not significant. All of these are equivalent:

a: { x: 1 y: 2 z: 3 }
b: { x: 1, y: 2, z: 3 }
c: { x: 1, y: 2, z: 3, }

eu -e '{ x: 1 y: 2 z: 3 }'

x: 1
y: 2
z: 3

Symbols

Symbols are written with a colon prefix and behave like interned strings. They are used as keys and as lightweight identifiers:

status: :active
tag: :important

status: active
tag: important

Function Declarations

Adding a parameter list creates a function declaration:

greet(name): "Hello, {name}!"
double(x): x * 2

message: greet("World")
result: double(21)

message: Hello, World!
result: 42

Functions are not rendered in the output -- only property values appear. Functions can take multiple parameters:

add(x, y): x + y
total: add(3, 4)

total: 7

Operator Declarations

You can define custom infix operators using symbolic names:

(x <+> y): [x, y]
pair: 1 <+> 2

pair:
- 1
- 2

Prefix and postfix unary operators are also possible:

(!! x): x * x
squared: !! 5

squared: 25

Operator precedence and associativity are controlled through metadata annotations (covered below). See the Operators chapter for full details.

Note: While function declarations are namespaced to their block, operators do not have a namespace and are available only where they are in scope.

Units: Top-Level Blocks

The top-level of a .eu file is itself a block, called a unit. It does not need surrounding braces. So this file:

name: "Alice"
age: 30

...is equivalent to a block { name: "Alice" age: 30 } and produces:

name: Alice
age: 30

Comments

Comments start with # and continue to the end of the line:

# This is a comment
name: "Alice"  # inline comment

Declaration Metadata

Metadata can be attached to any declaration by placing it between a leading backtick and the declaration:

` "A friendly greeting"
greeting: "Hello!"

` { doc: "Add two numbers" }
add(x, y): x + y

A bare string is shorthand for documentation metadata.

Some metadata keys activate special behaviour:

• :suppress -- hides the declaration from output
• :target -- marks the declaration as an export target
• :main -- marks the default target

` :suppress
helper(x): x + 1

` { target: :my-output }
output: {
  result: helper(41)
}

Running eu file.eu -t my-output renders only the output block.

Block and Unit Metadata

A single expression may precede the declarations in any block and is treated as metadata for that block. At the top level of a file (the unit), this means the first item, if it is an expression rather than a declaration, becomes metadata for the entire unit:

{ doc: "Configuration generator" }

host: "localhost"
port: 8080

Scope and Visibility

Names declared in a block are visible within that block and in any nested blocks:

x: 99
inner: {
  y: x + 1  # x is visible here
}

x: 99
inner:
  y: 100

Names in nested blocks can shadow outer names:

x: 1
inner: {
  x: 2
  y: x  # refers to inner x
}

x: 1
inner:
  x: 2
  y: 2

Warning: Be careful with self-reference. Writing name: name inside a block creates an infinite recursion, because the declaration name refers to itself. This is true regardless of whether name is defined in an outer scope.

Key Concepts

• Blocks are ordered collections of named values (like JSON objects or YAML mappings)
• Property declarations bind a name to a value
• Function declarations bind a name to a function (not rendered in output)
• Operator declarations define custom infix, prefix, or postfix operators
• Metadata annotations control export, documentation, and other special behaviour
• The top-level file is a unit: an implicit block without braces

Expressions and Pipelines

In this chapter you will learn:

• The primitive value types in eucalypt
• How function application works via catenation (pipelining)
• How partial application and currying work
• How to compose pipelines of transformations

Primitive Values

Eucalypt has the following primitive types:

Lists

Lists are comma-separated values in square brackets (unlike in blocks, commas are required):

numbers: [1, 2, 3, 4, 5]
mixed: [1, "two", :three, true]
nested: [[1, 2], [3, 4]]
empty: []

Calling Functions

Functions can be called by placing arguments in parentheses directly after the function name (with no intervening space):

add(x, y): x + y
result: add(3, 4)

result: 7

Catenation: The Pipeline Style

One distinctive feature of eucalypt is catenation: applying a function by writing the argument before the function name, separated by whitespace.

result: 5 inc

This is equivalent to inc(5) and produces 6.

Catenation lets you chain operations into readable pipelines:

eu -e '[1, 2, 3, 4, 5] reverse head'

5

Each step in the pipeline passes its result to the next function. You can read it left to right: "take the list, reverse it, take the head."

Combining Catenation with Arguments

When a function takes multiple arguments, you can supply some in parentheses and the rest via catenation. The catenated value becomes the last argument:

result: [1, 2, 3] map(inc)

Here map takes two arguments: a function and a list. inc is provided in parentheses and [1, 2, 3] is provided by catenation. The result is [2, 3, 4].

This is the standard eucalypt pattern for data processing pipelines:

eu -e '[1, 2, 3, 4, 5] filter(> 3) map(* 10)'

- 40
- 50

Currying and Partial Application

All functions in eucalypt are curried: if you provide fewer arguments than a function expects, you get back a partially applied function.

add(x, y): x + y
add-five: add(5)
result: add-five(3)

result: 8

Curried application also works with multi-argument calls:

f(x, y, z): x + y + z

a: f(1, 2, 3)   # all at once
b: f(1)(2)(3)    # one at a time
c: f(1, 2)(3)    # mixed

All three produce 6.

Lookup: The Dot Operator

The dot operator (.) accesses a named property within a block:

person: { name: "Alice" age: 30 }
name: person.name

person:
  name: Alice
  age: 30
name: Alice

Lookups can be chained:

config: { db: { host: "localhost" port: 5432 } }
host: config.db.host

config:
  db:
    host: localhost
    port: 5432
host: localhost

Warning: The dot operator binds very tightly (precedence 90). Writing list head.name is parsed as list (head.name), not (list head).name. Use explicit parentheses when combining lookup with catenation: (list head).name.

The ↑ (up arrow) prefix operator, which is shorthand for head, binds even tighter (precedence 95). So ↑xs.name means (↑xs).name.

"Juxtaposed" call syntax

When a function is passed only a single list argument or a single block argument, it is possible to omit the outer parentheses for brevity:

result: f[1, 2, 3] ∧ g{a: 1 b: 2}

The "juxtaposition" refers to the resulting feature that directly placing a function together with any form of brackets (with no intervening whitespace) is now call syntax - whereas using an intervening space is a pipeline syntax.

Juxtaposed call syntax: f(x), f[x], f{x}.

Pipeline syntax: x f, [x] f, {x} f.

Generalised Lookup (or "block-dot" notation)

Lookup can be generalised: any expression after the dot is evaluated in the context of the block to the left.

point: { x: 3 y: 4 }
sum: point.(x + y)
pair: point.[x, y]
label: point."{x},{y}"

point:
  x: 3
  y: 4
sum: 7
pair:
- 3
- 4
label: 3,4

This is particularly useful for creating temporary scopes:

result: { a: 10 b: 20 }.(a * b)

result: 200

"Block-dot" syntax is particularly significant in monadic blocks (see Monads and the monad() Utility).

Building Pipelines

Combining catenation, partial application, and the standard prelude creates powerful data processing pipelines:

eu -e '["alice", "bob", "charlie"] map(str.to-upper) filter(str.matches?("^[AB]"))'

- ALICE
- BOB

A more complete example:

people: [
  { name: "Alice" age: 30 }
  { name: "Bob" age: 25 }
  { name: "Charlie" age: 35 }
]

over-thirty: people filter(.age > 30) map(.name)

people:
- name: Alice
  age: 30
- name: Bob
  age: 25
- name: Charlie
  age: 35
over-thirty:
- Charlie

The then Function

The then function provides a pipeline-friendly conditional:

eu -e '5 > 3 then("yes", "no")'

yes

It is equivalent to if with the condition as the last argument, making it natural in pipelines:

result: [1, 2, 3] count (> 2) then("many", "few")

result: many

Key Concepts

• Catenation applies a function by writing the argument before the function name: 5 inc means inc(5)
• Pipelines are built by chaining catenation: data f g h
• Functions are curried: partial application is automatic
• The dot operator looks up properties: block.key
• Generalised lookup evaluates expressions in a block's scope: block.(expr)
• Combine these techniques for concise data processing pipelines

Lists and Transformations

In this chapter you will learn:

• How to create and deconstruct lists
• The core list operations: map, filter, foldl, foldr
• Other useful list functions from the prelude
• How to combine list operations into pipelines

Creating Lists

Lists are written with square brackets and commas:

numbers: [1, 2, 3, 4, 5]
strings: ["hello", "world"]
empty: []
nested: [[1, 2], [3, 4]]

Basic List Operations

head and tail

head returns the first element; tail returns everything after it:

eu -e '[10, 20, 30] head'

10

eu -e '[10, 20, 30] tail'

- 20
- 30

Use head-or to provide a default for empty lists:

eu -e '[] head-or(0)'

0

first and second

first is an alias for head. second returns the second element:

eu -e '[:a, :b, :c] second'

b

cons

cons prepends an element to a list:

eu -e 'cons(0, [1, 2, 3])'

- 0
- 1
- 2
- 3

nil?

Test whether a list is empty:

eu -e '[] nil?'

true

count

Count the elements:

eu -e '[10, 20, 30] count'

3

Transforming Lists

map

Apply a function to every element:

eu -e '[1, 2, 3] map(inc)'

- 2
- 3
- 4

eu -e '[1, 2, 3] map(* 10)'

- 10
- 20
- 30

filter

Keep only elements satisfying a predicate:

eu -e '[1, 2, 3, 4, 5, 6] filter(> 3)'

- 4
- 5
- 6

remove

The opposite of filter -- remove elements satisfying the predicate:

eu -e '[1, 2, 3, 4, 5] remove(> 3)'

- 1
- 2
- 3

Folding

Folds reduce a list to a single value by applying a binary function across all elements.

foldl

Left fold: foldl(op, init, list) applies op from the left:

eu -e 'foldl(+, 0, [1, 2, 3, 4, 5])'

15

foldr

Right fold: foldr(op, init, list) applies op from the right:

eu -e 'foldr(++, [], [[1, 2], [3, 4], [5]])'

- 1
- 2
- 3
- 4
- 5

Slicing

take and drop

eu -e '[1, 2, 3, 4, 5] take(3)'

- 1
- 2
- 3

eu -e '[1, 2, 3, 4, 5] drop(3)'

- 4
- 5

take-while and drop-while

eu -e '[1, 2, 3, 4, 5] take-while(< 4)'

- 1
- 2
- 3

Combining Lists

append and ++

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

- 1
- 2
- 3
- 4

concat

Flatten a list of lists:

eu -e 'concat([[1, 2], [3], [4, 5]])'

- 1
- 2
- 3
- 4
- 5

mapcat

Map then flatten (also known as flatMap or concatMap):

eu -e '["ab", "cd"] mapcat(str.letters)'

- a
- b
- c
- d

Checking Lists

all-true? and any-true?

eu -e '[true, true, false] all-true?'

false

eu -e '[true, true, false] any-true?'

true

all and any

Test with a predicate:

eu -e '[2, 4, 6] all(> 0)'

true

eu -e '[1, 2, 3] any(zero?)'

false

Reordering

reverse

eu -e '[:a, :b, :c] reverse'

- c
- b
- a

zip-with

Combine two lists element by element:

eu -e 'zip-with(+, [1, 2, 3], [10, 20, 30])'

- 11
- 22
- 33

zip-with and pair to create blocks

eu -e 'zip-with(pair, [:x, :y, :z], [1, 2, 3]) block'

x: 1
y: 2
z: 3

Infinite Lists

Eucalypt supports lazy evaluation, so you can work with infinite lists:

eu -e 'repeat(:x) take(4)'

- x
- x
- x
- x

Use take to extract a finite portion.

Sorting

qsort

Sort with a comparison function:

eu -e '[5, 3, 1, 4, 2] qsort(<)'

- 1
- 2
- 3
- 4
- 5

sort-nums

A convenience for sorting numbers in ascending order:

eu -e '[30, 10, 20] sort-nums'

- 10
- 20
- 30

Putting It Together

Here is a more complete example combining multiple list operations:

data: [
  { name: "Alice" score: 85 }
  { name: "Bob" score: 92 }
  { name: "Charlie" score: 78 }
  { name: "Diana" score: 95 }
]

top-scorers: data
  filter(.score >= 90)
  map(.name)

data:
- name: Alice
  score: 85
- name: Bob
  score: 92
- name: Charlie
  score: 78
- name: Diana
  score: 95
top-scorers:
- Bob
- Diana

Key Concepts

• Lists are created with [...] and can be heterogeneous
• map, filter, and foldl/foldr are the core transformation functions
• take, drop, reverse, append (++), and concat reshape lists
• all, any, all-true?, and any-true? test list conditions
• Lazy evaluation allows working with infinite lists via repeat
• qsort sorts with a custom comparator; sort-nums sorts numbers

Strings and Text

In this chapter you will learn:

• The two string literal types (raw and c-strings)
• How to embed expressions in strings using {...} syntax
• How strings with anaphora become functions
• Format specifiers for controlling output
• The string functions available in the str namespace

String Literal Types

Eucalypt has two kinds of string literal: raw strings and c-strings.

Raw Strings

A plain double-quoted string is a raw string — backslashes are literal characters with no escape processing. This is convenient for regular expression usage.

greeting: "Hello, World!"
path: "C:\Users\alice\docs"
regex: "^\d+\.\d+"

The r"..." prefix is equivalent and can be used for clarity when the string contains backslashes:

path: r"C:\Users\alice\docs"
regex: r"^\d+\.\d+"

Raw strings support interpolation with {...}. Use {{ and }} for literal braces.

C-Strings (c"...")

If you require C-style escapes, you can use C-strings:

multiline: c"first line\nsecond line"

C-strings also support interpolation with {...}.

Basic Interpolation

Embed any expression inside a string using curly braces:

name: "World"
greeting: "Hello, {name}!"

name: World
greeting: Hello, World!

Interpolation braces accept names and dotted lookups. To use a computed value, bind it to a name first:

x: 3
y: 4
sum: x + y
result: "{x} + {y} = {sum}"

x: 3
y: 4
sum: 7
result: 3 + 4 = 7

Nested Lookups in Interpolation

You can use dotted paths inside interpolation:

data: { foo: { bar: 99 } }
label: "{data.foo.bar}"

data:
  foo:
    bar: 99
label: '99'

Note: Interpolation braces accept names and dotted lookups, but not arbitrary eucalypt expressions. If you need a computed value, bind it to a name first:

sum: x + y
result: "{sum}"

Escaping Braces

To include a literal brace in a string, double it:

example: "Use {{braces}} for interpolation"

example: Use {braces} for interpolation

This is also needed in regular expressions within interpolated strings:

pattern: "01234" str.match-with("\d{{4}}")

Format Specifiers

Add a format specifier after a colon inside the interpolation braces. These use printf-style format codes:

pi: 3.14159
formatted: "{pi:%.2f}"
padded: "{42:%06d}"

pi: 3.14159
formatted: '3.14'
padded: '000042'

String Anaphora

When a string contains {} (empty braces) or {0}, {1}, etc., the string literal actually defines a function rather than a plain string value:

eu -e '["a", "b", "c"] map("item: {}")'

- 'item: a'
- 'item: b'
- 'item: c'

Numbered anaphora control argument order:

reverse-pair: "{1},{0}"
result: reverse-pair(:a, :b)

result: b,a

You can mix named references and anaphora:

prefix: "Hello"
greet: "{prefix} {}!"
result: greet("World")

prefix: Hello
result: Hello World!

String Functions

The str namespace contains functions for working with strings.

Conversion

eu -e '42 str.of'

'42'

Case Conversion

eu -e '"hello" str.to-upper'

HELLO

eu -e '"GOODBYE" str.to-lower'

goodbye

Splitting and Joining

Split a string on a pattern:

eu -e '"one-two-three" str.split-on("-")'

- one
- two
- three

Join a list of strings:

eu -e '["a", "b", "c"] str.join-on(", ")'

a, b, c

Prefix and Suffix

eu -e '"world" str.prefix("hello ")'

hello world

eu -e '"hello" str.suffix("!")'

hello!

Characters and Letters

eu -e '"hello" str.letters'

- h
- e
- l
- l
- o

eu -e '"hello" str.letters count'

5

Regular Expressions

Testing a Match

eu -e '"hello" str.matches?("^h.*o$")'

true

Extracting Matches

str.match-with returns the full match and capture groups:

eu -e '"192.168.0.1" str.match-with("(\d+)[.](\d+)[.](\d+)[.](\d+)") tail'

- '192'
- '168'
- '0'
- '1'

str.matches-of returns all occurrences of a pattern:

eu -e '"192.168.0.1" str.matches-of("\d+")'

- '192'
- '168'
- '0'
- '1'

Base64 and SHA-256

eu -e '"hello" str.base64-encode'

aGVsbG8=

eu -e '"hello" str.sha256'

2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

Practical Examples

Generating URLs

base: "https://api.example.com"
endpoints: ["users", "posts", "comments"] map("{base}/{}")

base: https://api.example.com
endpoints:
- https://api.example.com/users
- https://api.example.com/posts
- https://api.example.com/comments

Formatting a Table

rows: [
  { name: "Alice" score: 85 }
  { name: "Bob" score: 92 }
]

` :suppress
format-row(r): "{r.name:%10s} | {r.score:%3d}"

table: rows map(format-row)

Key Concepts

• Interpolation uses {expression} inside double-quoted strings
• Empty braces {} and numbered braces {0}, {1} create string functions (anaphora)
• Format specifiers follow a colon: {value:%06d}
• Escape literal braces by doubling them: {{ and }}
• The str namespace provides splitting, joining, case conversion, matching, and more

Functions and Combinators

In this chapter you will learn:

• How to define and call functions
• How destructuring parameters work
• How currying and partial application work
• The standard combinators: identity, const, compose, flip, and forward composition with ;
• How to build functions from other functions without lambdas

Defining Functions

A function declaration has a parameter list in parentheses:

square(x): x * x
add(x, y): x + y
greet(name, greeting): "{greeting}, {name}!"

Functions can be called with arguments in parentheses:

a: square(5)
b: add(3, 4)
c: greet("Alice", "Hello")

a: 25
b: 7
c: Hello, Alice!

Or via catenation (see Expressions and Pipelines):

a: 5 square
b: 4 add(3)

Destructuring Parameters

Function parameters can be destructuring patterns that extract structure from an argument inline, binding its components as named variables in the function body.

Block destructuring

A block pattern binds named fields from a block argument. Shorthand form binds the field name directly:

sum-of-point({x y}): x + y

p: { x: 3 y: 4 }
result: sum-of-point(p)

result: 7

A rename form binds a field under a different local name, using a colon between the field name and the binding name:

scaled({x: a  y: b}, scale): a * scale + b * scale

result: scaled({x: 2  y: 3}, 10)

result: 50

Shorthand and rename can be mixed freely:

describe({x  y: height}): "x={x} h={height}"

result: describe({x: 1  y: 5})

result: x=1 h=5

Fixed-length list destructuring

A list pattern binds positional elements from a list argument:

add-pair([a, b]): a + b

result: add-pair([10, 20])

result: 30

Multiple elements at any position are supported:

third([a, b, c]): c

result: third([1, 2, 3])

result: 3

Head/tail list destructuring

A head/tail pattern separates a list into its first element and the remaining list. A colon inside square brackets separates the fixed elements (heads) from the tail binding:

first-of([x : xs]): x
rest-of([x : xs]): xs

a: first-of([1, 2, 3])
b: rest-of([1, 2, 3])

a: 1
b: [2, 3]

Multiple heads are separated by commas before the colon:

sum-first-two([a, b : rest]): a + b

result: sum-first-two([10, 20, 30])

result: 30

Juxtaposed call syntax

When a function takes a block or list argument, you may call it by placing the block or list immediately after the function name with no space:

sum-xy({x y}): x + y

a: sum-xy{x: 3 y: 4}    # same as sum-xy({x: 3 y: 4})

a: 7

Similarly for list arguments:

add-pair([a, b]): a + b

b: add-pair[10, 20]      # same as add-pair([10, 20])

b: 30

Combined with block destructuring, juxtaposed calls give named arguments as an emergent pattern — no extra language concept needed:

greet({name greeting}): "{greeting}, {name}!"

result: greet{name: "Alice" greeting: "Hello"}

result: Hello, Alice!

Juxtaposed definition syntax

The juxtaposed bracket syntax also works on the definition side. Writing the bracket or brace directly against the function name (no space) is sugar for the parenthesised destructuring form:

# These pairs are equivalent:
add-pair[a, b]: a + b         # sugar for add-pair([a, b]): a + b
add-block{x y}: x + y        # sugar for add-block({x y}): x + y
my-head[h : t]: h             # sugar for my-head([h : t]): h

The cons operator ‖

The ‖ operator (U+2016, DOUBLE VERTICAL LINE) prepends a single element to a list. It is right-associative, so chains build lists left-to-right without parentheses:

a: 1 ‖ [2, 3]          # [1, 2, 3]
b: 1 ‖ 2 ‖ [3]         # [1, 2, 3]
c: 1 ‖ []              # [1]

a: [1, 2, 3]
b: [1, 2, 3]
c: [1]

The precedence of ‖ (55) is between comparison (50) and arithmetic (75), so it binds more tightly than comparisons but less tightly than addition or multiplication.

Mixing patterns

Normal parameters and destructuring patterns can be combined in any order:

weighted-sum(w, [a, b, c]): w * a + w * b + w * c

result: weighted-sum(2, [1, 3, 5])

result: 18

Multiple destructuring parameters are also allowed:

combine({x}, [a, b]): x + a + b

result: combine({x: 10}, [3, 7])

result: 20

Functions are Values

Functions are first-class values. They can be passed as arguments, returned from other functions, and stored in blocks:

apply-twice(f, x): x f f
result: apply-twice(inc, 5)

result: 7

ops: {
  double: * 2
  negate: 0 -
}

result: 5 ops.double ops.negate

result: -10

Currying

All functions are automatically curried. Providing fewer arguments than expected returns a partially applied function:

add(x, y): x + y

add-five: add(5)      # partially applied
result: add-five(3)   # completes the application

result: 8

This is particularly useful with map and filter:

multiply(x, y): x * y
triple: multiply(3)

results: [1, 2, 3] map(triple)

results:
- 3
- 6
- 9

Sections

Operators can be partially applied too. When an operator has a missing operand, eucalypt fills in an implicit parameter:

eu -e '[1, 2, 3] map(+ 10)'

- 11
- 12
- 13

Here + 10 is a section: a function that adds 10 to its argument. Similarly:

eu -e '[1, 2, 3, 4, 5] filter(> 3)'

- 4
- 5

Sections can be used as standalone values:

add: +
sub: -

result: add(2, 3)
diff: sub(8, 3)

result: 5
diff: 5

Passing operators to higher-order functions

Operators can be passed as arguments using their operator name or as a section in parentheses:

total: foldl(+, 0, [1, 2, 3, 4, 5])

total: 15

Standard Combinators

The prelude provides several fundamental combinators.

identity

Returns its argument unchanged:

eu -e '42 identity'

42

const

Returns a function that always produces the given value:

eu -e ':x const(99)'

99

Useful for replacing every element with a fixed value:

eu -e '[1, 2, 3] map(const(:done))'

- done
- done
- done

compose and ∘

Compose two functions: compose(f, g) produces a function that applies g first, then f:

eu -e '1 compose(zero?, dec)'

true

The ∘ operator is an infix form:

eu -e '(str.prefix("<") ∘ str.suffix(">"))("x")'

<x>

Forward composition ;

The ; operator composes in the other direction: f ; g applies f first, then g. This reads naturally in pipelines — left to right:

eu -e '"hello" (str.letters ; count)'

5

Forward composition is often simpler than ∘ because it follows the data flow:

` :suppress
shout: str.to-upper ; str.suffix("!")

result: "hello" shout

result: HELLO!

Use ; when building a pipeline from smaller steps:

eu -e '[3, 1, 4, 1, 5] map(inc ; (* 2))'

- 8
- 4
- 10
- 4
- 12

flip

Swap the first two arguments of a function:

eu -e 'flip(-, 1, 3)'

2

flip is useful for adapting functions to a pipeline:

` :suppress
with-tags: merge flip ({ tags: [:a, :b] })

result: { name: "foo" } with-tags

complement

Negate a predicate:

eu -e '0 complement(zero?)'

false

apply

Apply a function to a list of arguments:

eu -e 'apply(+, [3, 4])'

7

uncurry

Convert a curried function to one that takes a pair (two-element list):

eu -e 'uncurry(+)([3, 4])'

7

curry

The inverse of uncurry -- convert a function expecting a pair to a curried function:

eu -e 'curry(first)("a", "b")'

a

Building Functions without Lambdas

Eucalypt does not have a lambda syntax. Instead, you build functions from:

1. Named functions -- the clearest approach
2. Partial application -- add(5), * 2
3. Sections -- (+ 1), (> 0)
4. Composition -- f ∘ g or g ; f
5. Anaphora -- _ + 1, _0 * _0 (see next chapters)

These compose naturally:

` :suppress
process: filter(> 0) ∘ map(dec)

result: [3, 1, 0, 5, 2] process

Practical Example: Transforming Data

people: [
  { name: "alice", age: 30 },
  { name: "bob", age: 25 },
  { name: "charlie", age: 35 }
]

` :suppress
format(p): "{p.name}: age {p.age}"

directory: people
  filter(.age >= 30)
  map(format)

people:
- name: alice
  age: 30
- name: bob
  age: 25
- name: charlie
  age: 35
directory:
- 'alice: age 30'
- 'charlie: age 35'

Key Concepts

• Functions are first-class values
• All functions are curried: partial application is automatic
• Sections give partial application for operators: (+ 1), (> 3)
• Combinators like identity, const, compose (∘), forward-compose (;), and flip build new functions from existing ones
• Prefer named functions for anything complex; use partial application and sections for simple cases

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

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.

Nullary Operators

A nullary operator takes no operands — it is a constant written as a symbol:

(∅): '__SET.EMPTY'
result: ∅ set.to-list

result: []

The empty set ∅ is the only nullary operator in the standard prelude, but you can define your own:

(★): 42
answer: ★

Prefix and Postfix Operators

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

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:

Higher numbers bind more tightly:

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.

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

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

The Assertion Operators

Two special operators are provided for testing:

//= (assert equals)

Asserts that the left side equals the right side at runtime, and returns the value if true. Panics if false:

result: 2 + 2 //= 4

//=> (assert equals with metadata)

Like //= but also attaches the assertion as metadata:

checked: 2 + 2 //=> 4

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

The Metadata Operator //

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.

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

The Append Operator ++

Concatenate two lists:

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

- 1
- 2
- 3
- 4

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

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

⌈ x ⌉: x * 2

doubled: ⌈ 3 + 4 ⌉

doubled: 14

The declaration ⌈ x ⌉: body defines a function named ⌈⌉ that takes one argument. Using ⌈ expr ⌉ in an expression calls that function with expr.

Any of the built-in Unicode bracket pairs can be used:

(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

• 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

Anaphora (Implicit Parameters)

Eucalypt doesn't have a lambda syntax in itself and prefers to encourage other approaches in most cases where you would use a lambda.

• named functions
• function values from composites, combinators, partials
• anaphoric expressions, blocks or strings

However, through the combination of two Eucalypt features, namely block anaphora and generalised lookup, you can express arbitrary lambdas as we'll see below.

The various alternatives are considered one by one.

Named functions

Very likely, the clearest way to square a list of numbers is to map an explicitly named square function across it.

square(x): x * x
squares: [1, 2, 3] map(square) //=> [1, 4, 9]

The drawbacks of this are:

• polluting a namespace with a name that is needed only once
• arguably, a slightly tedious verbosity

The first can be dealt with as follows:

squares: { square(x): x * x }.([1, 2, 3] map(square)) //=> [1, 4, 9]

This exploits a feature called generalised lookup.

Why "generalised lookup"? In the simple case below, the dot signifies the "lookup" of key a in the block preceding the dot:

x: { a: 3 b: 4 }.a //=> 3

We can generalise this by allowing arbitrary expressions in place of the a by evaluating the expression after the dot in the context of the namespace introduced by the block to the left.

x: { a: 3 b: 4 }.(a + b) //=> 7

It works for any expression after the dot:

x: { a: 3 b: 4 }.[a, b] //=> [3, 4]
y: { a: 3 b: 4 }.{ c: a + b } //=> { c: 7 }
z: { a: 3 b: 4 }."{a} and {b}" //=> "3 and 4"

Warning: This is very effective for short and simple expressions but quickly gets very complicated and hard to understand if you use it too much. Nested or iterated generalised lookups are usually a bad idea.

In the squares example above, generalised lookup is used to restrict the scope in which square is visible right down to the only expression which needs it.

However in the case of a simple expression like the squaring example, a neater approach is to use expression anaphora.

Expression Anaphora

Any expression can become a function by referring to implicit parameters known as expression anaphora.

These parameters are called _0, _1 _2, and so on. There is also an unnumbered anaphor, _, which we'll come back to.

Just referring to these parameters is enough to turn an expression into a lambda.

So an expression that refers _0 and _1 actually defines a function accepting two parameters:

xs: zip-with(f, [1, 2, 3], [1, 2, 3]) //=> [3, 6, 9]

# or more succinctly
xs: zip-with(_0 + 2 * _1, [1, 2, 3], [1, 2, 3]) //=> [3, 6, 9]

Warning: Anaphora are intended for use in simple cases where they are readable and readily understood. The scope of the implicit parameters is not easy to work out in complicated contexts. (It does not extend past catenation or commas in lists or function application tuples.) Anaphoric expressions are not, and not intended to be, a fully general lambda syntax. Unlike explicit lambda constructions, you cannot nest anaphoric expressions.

squares: [1, 2, 3] map(_0 * _0) //=> [1, 4, 9]

In cases where the position of the anaphora in the expression matches the parameter positions in the function call, you can omit the numbers. So, for instance, _0 + _1 can simply be written _ + _, and _0 * _1 + x * _2 can be written _ * _ + x * _.

Each _ represents a different implicit parameter, which is why we had to write _0 * _0 in our squares example - it was important that the same parameter was referenced twice.

Sometimes you need explicit parentheses to clarify the scope of expression anaphora:

block: { a: 1 b: 2 }

x: block (_.a) //=> 1
y: block lookup(:a) //=> 1
#
# BUT NOT: block _.a
#

Sections

Even more conciseness is on offer in some cases where the anaphora can be entirely omitted. Eucalypt will automatically insert anaphora when it detects gaps in an expression based on its knowledge of an operator's type.

So it will automatically read (1 +) as (1 + _), for example, defining a function of one parameter. Or (*) as (_ * _), defining a function of two parameters. The parentheses may not even be necessary to delimit the expression:

x: foldl(+, 0, [1, 2, 3]) = 6

Again, use of sections is recommended only for short expressions or where the intention is obvious. This level of terseness can lead to baffling code if abused.

Block Anaphora

Expression anaphora are scoped by an expression which is roughly defined as something within parentheses or something which can be the right hand side of a declaration.

Sometimes however you would like to define a block-valued function. Imagine you wanted a two-parameter function which placed the parameters in a block with keys x and y:

f(x, y): {x: x y: y }

An attempt to define this using expression anaphora would fail. This defines a block with two identity functions:

f: {x: _ y: _ }

Instead, you can use block anaphora which are scoped by the block that contains them.

The block anaphora are named •0, •1, •2 with a special unnumbered anaphor •, playing the same role as _ does for expression anaphora.

• is the BULLET character (usually Option-8 on a Mac but you may find other convenient ways to type it). The slightly awkward character is chosen firstly because it looks like a hole and therefore makes sense as a placeholder, and secondly to discourage overuse of the feature...

The following defines the function we want:

f: { x: • y: • }

...and can, of course, be used:

x: [[1, 2], [3, 4], [5, 6]] map({ x: • y: • } uncurry)

Pseudo-lambdas

Astute observers may realise that by combining generalised lookup and block anaphora you end up with something that's not a million miles away from a lambda syntax:

f: { x: • y: • }.(x + y)

Indeed this does allow declaration of anonymous functions with named parameters and can occasionally be useful but it still falls short of a fully general lambda construction because it cannot (at least for now) be nested. It is to be regarded as a stylistic anti-pattern, use alternatives where available.

String Anaphora

Analogously, Eucalypt's string interpolation syntax allows the use of anaphora {0}, {1}, {2} and the unnumbered {} to define functions which return strings.

x: [1, 2, 3] map("#{}") //=> ["#1", "#2", "#3"]

Summary

There are lots of ways to define functions but the clearest is just defining them with names using function declarations and for anything even slightly complicated this should be the default. The only things you should be tempted to define on the spot are things that are simple enough that the various species of anaphora can handle them neatly.

Block Manipulation

In this chapter you will learn:

• How to merge blocks with catenation and merge
• How to inspect, transform, and restructure blocks
• Key prelude functions for working with blocks
• Patterns for building and modifying configuration data

Block Merge by Catenation

When two blocks appear next to each other, the result is a shallow merge. Later values override earlier ones:

eu -e '{ a: 1 } { b: 2 }'

a: 1
b: 2

eu -e '{ a: 1 } { a: 2 }'

a: 2

This is the same as calling the merge function:

eu -e 'merge({ a: 1 }, { b: 2 })'

a: 1
b: 2

Deep Merge

Use deep-merge or the << operator for recursive merging of nested blocks:

base: { server: { host: "localhost" port: 8080 } }
override: { server: { port: 9090 debug: true } }
config: base << override

base:
  server:
    host: localhost
    port: 8080
override:
  server:
    port: 9090
    debug: true
config:
  server:
    host: localhost
    port: 9090
    debug: true

Note that << merges nested blocks but replaces lists entirely.

Inspecting Blocks

elements

Break a block into its list of key-value pairs:

eu -e '{ a: 1 b: 2 } elements'

- - a
  - 1
- - b
  - 2

Each element is a two-element list: [key, value].

keys and values

eu -e '{ a: 1 b: 2 c: 3 } keys'

- a
- b
- c

eu -e '{ a: 1 b: 2 c: 3 } values'

- 1
- 2
- 3

has

Check whether a block contains a key:

eu -e '{ a: 1 b: 2 } has(:a)'

true

lookup and lookup-or

Look up a value by symbol key:

eu -e '{ a: 1 b: 2 } lookup(:b)'

2

With a default for missing keys:

eu -e '{ a: 1 } lookup-or(:z, 99)'

99

Reconstructing Blocks

block

Build a block from a list of key-value pairs:

eu -e '[[:a, 1], [:b, 2], [:c, 3]] block'

a: 1
b: 2
c: 3

zip-kv

Build a block from separate key and value lists:

eu -e 'zip-kv([:x, :y, :z], [1, 2, 3])'

x: 1
y: 2
z: 3

merge-all

Merge a list of blocks into one:

eu -e '[{a: 1}, {b: 2}, {c: 3}] merge-all'

a: 1
b: 2
c: 3

Transforming Blocks

map-values

Apply a function to every value, keeping keys:

eu -e '{ a: 1 b: 2 c: 3 } map-values(* 10)'

a: 10
b: 20
c: 30

map-keys

Transform the keys of a block:

eu -e '{ a: 1 b: 2 } map-keys(sym ∘ str.prefix("x-") ∘ str.of)'

x-a: 1
x-b: 2

filter-values

Return the list of values that satisfy a predicate (note: this returns a list, not a block):

eu -e '{ a: 1 b: 20 c: 3 d: 40 } filter-values(> 10)'

- 20
- 40

To keep matching entries as a block, use filter-items with by-value:

eu -e '{ a: 1 b: 20 c: 3 d: 40 } filter-items(by-value(> 10)) block'

b: 20
d: 40

map-kv

Apply a function to each key-value pair. The function receives two separate arguments (key, value) (it uses uncurry internally), and returns a transformed result:

eu -e '{ a: 1 b: 2 } map-kv("{}: {}")'

- 'a: 1'
- 'b: 2'

To produce a new block, combine with block:

eu -e '{ a: 1 b: 2 } map-kv(pair) block'

a: 1
b: 2

Modifying Individual Values

alter-value

Replace the value at a specific key:

config: { host: "localhost" port: 8080 }
updated: config alter-value(:port, 9090)

config:
  host: localhost
  port: 8080
updated:
  host: localhost
  port: 9090

update-value

Apply a function to the value at a specific key:

counters: { hits: 10 errors: 3 }
result: counters update-value(:hits, inc)

counters:
  hits: 10
  errors: 3
result:
  hits: 11
  errors: 3

set-value

Set a value, creating the key if it does not exist:

eu -e '{} set-value(:x, 42)'

x: 42

alter and update (nested)

Modify values deep in nested blocks using a key path:

config: { server: { db: { port: 5432 } } }
changed: config alter([:server, :db, :port], 3306)
bumped: config update([:server, :db, :port], inc)

config:
  server:
    db:
      port: 5432
changed:
  server:
    db:
      port: 3306
bumped:
  server:
    db:
      port: 5433

merge-at

Merge additional keys into a nested block:

config: { server: { db: { port: 5432 } } }
extended: config merge-at([:server, :db], { host: "10.0.0.1" })

config:
  server:
    db:
      port: 5432
extended:
  server:
    db:
      port: 5432
      host: 10.0.0.1

Patterns: Configuration Templating

A common pattern is to define a base configuration and layer environment-specific overrides on top:

base: {
  server: {
    host: "0.0.0.0"
    port: 8080
    workers: 4
  }
  logging: {
    level: "info"
    format: "json"
  }
}

production: base << {
  server: { workers: 16 }
  logging: { level: "warn" }
}

development: base << {
  server: { host: "localhost" }
  logging: { level: "debug" format: "text" }
}

Key Concepts

• Block catenation merges two blocks; later keys override earlier ones
• Deep merge (<<) recursively merges nested blocks
• elements, keys, values decompose blocks; block and zip-kv reconstruct them
• map-values, map-keys, filter-values transform blocks
• alter-value, update-value, set-value modify individual entries
• alter, update, merge-at modify deeply nested values

Imports and Modules

In this chapter you will learn:

• How to import other eucalypt files and data files
• How to scope imports to specific declarations
• How to use named imports for namespacing
• How git imports work for external dependencies

Basic Imports

Import another eucalypt file using the import key in declaration metadata:

{ import: "helpers.eu" }

# Names from helpers.eu are now available
result: helper-function(42)

When the metadata is at unit level (the first item in the file), the imported names are available throughout the entire file.

Scoped Imports

Imports can be scoped to a specific declaration, limiting where the imported names are visible:

` { import: "math.eu" }
calculations: {
  # Names from math.eu are available only within this block
  result: advanced-calculation(10)
}

# math.eu names are NOT available here

Named Imports

Give an import a name to access its contents under a namespace:

{ import: "cfg=config.eu" }

host: cfg.host
port: cfg.port

This is especially useful when importing data files that might contain names which clash with your own:

{ import: "prod=production.yaml" }

url: "https://{prod.host}:{prod.port}"

Importing Multiple Files

Supply a list to import several files at once:

{ import: ["helpers.eu", "config.eu"] }

result: helper(config-value)

Named and unnamed imports can be mixed:

{ import: ["helpers.eu", "cfg=config.eu"] }

result: helper(cfg.port)

Importing Data Files

Eucalypt can import files in any supported format. The format is inferred from the file extension:

{ import: "data=records.yaml" }

first-record: data head

You can override the format when the extension is misleading:

{ import: "data=yaml@records.txt" }

Formats That Return Lists

Some formats (CSV, JSON Lines, text) produce lists rather than blocks. These must be given a name:

{ import: "rows=transactions.csv" }

total: rows map(.amount num) foldl(+, 0)

Nested Imports

Imports can be placed at any level of nesting:

deep: {
  nested: {
    ` { import: "local-config.eu" }
    config: {
      value: local-setting
    }
  }
}

Import Resolution Order

When an import path is a relative string (e.g. "helpers.eu" rather than an absolute path or a git import), eucalypt resolves it by searching in this order:

1. Source-relative directory — the directory containing the file that contains the import declaration.
2. Global lib path — the directories supplied via -L flags and the current working directory, searched in the order they were specified.

If the file is found in the source-relative directory it is used immediately and the global lib path is not consulted.

Transitive resolution

Resolution is always relative to the importing file, not to the entry-point file passed on the command line. This means:

• main.eu imports "lib/utils.eu" → resolved as <dir-of-main>/lib/utils.eu
• lib/utils.eu imports "helpers/misc.eu" → resolved as <dir-of-main>/lib/helpers/misc.eu (relative to utils.eu, not to main.eu)
• lib/helpers/misc.eu imports "sub/detail.eu" → resolved as <dir-of-main>/lib/helpers/sub/detail.eu

Each file sees its own directory as the base for relative imports, no matter how deep the chain goes.

Practical example

Suppose your project is laid out as follows:

project/
  main.eu
  lib/
    utils.eu
    helpers/
      misc.eu

main.eu can import lib/utils.eu using a path relative to itself:

{ import: "lib/utils.eu" }

result: util-function(42)

lib/utils.eu can import from lib/helpers/misc.eu using a path relative to its own location:

{ import: "helpers/misc.eu" }

util-function(x): misc-helper(x)

No -L flags or absolute paths are needed. If a file is not found source-relatively, eucalypt falls back to the global lib path, so existing projects that rely on -L continue to work without modification.

Git Imports

Import eucalypt code directly from a git repository. This is useful for sharing libraries without manually managing local copies:

{ import: { git: "https://github.com/user/eu-lib"
            commit: "abc123def456"
            import: "lib/helpers.eu" } }

result: lib-function(42)

The commit field is mandatory and should be a full SHA. This ensures the import is repeatable and cacheable.

Multiple git imports can be listed alongside simple imports:

{ import: [
  "local.eu",
  { git: "https://github.com/user/lib"
    commit: "abc123"
    import: "helpers.eu" }
] }

Streaming Imports

For large files, streaming imports read data lazily:

{ import: "events=jsonl-stream@events.jsonl" }

recent: events take(100)

Available streaming formats:

Combining Imports with the Command Line

Imports in .eu files complement the command line input system. You can use both together:

eu data.yaml transform.eu

Here data.yaml is a command-line input and transform.eu can also have its own { import: ... } declarations for helpers or configuration.

See The Command Line for details on the input system.

Practical Example: Configuration Layering

# base.eu
defaults: {
  host: "0.0.0.0"
  port: 8080
  workers: 4
}

# deploy.eu
{ import: "base.eu" }

production: defaults << {
  workers: 16
  host: "prod.example.com"
}

staging: defaults << {
  host: "staging.example.com"
}

Running eu deploy.eu produces layered configuration with shared defaults.

Key Concepts

• Use { import: "file.eu" } in metadata to import files
• Named imports ("name=file") provide namespace isolation
• Imports can be scoped to individual declarations
• Data files (YAML, JSON, CSV, etc.) can be imported like code
• Relative paths resolve against the importing file's directory first, then the global lib path — no -L flags needed for co-located helpers
• Git imports pull code directly from repositories at a specific commit
• Streaming imports (jsonl-stream@, csv-stream@, text-stream@) handle large files lazily

Working with Data

In this chapter you will learn:

• How to process JSON, YAML, TOML, CSV, and XML data
• How to convert between formats on the command line
• Patterns for querying and transforming structured data
• How to combine multiple data sources

Format Conversion

The simplest use of eucalypt is converting between data formats. By default, output is YAML:

# JSON to YAML
eu data.json

# YAML to JSON
eu data.yaml -j

# JSON to TOML
eu data.json -x toml

Processing JSON

Pipe JSON from other tools into eucalypt:

curl -s https://api.example.com/users | eu -e 'map(.name)'

Or process a JSON file:

eu -e 'users filter(.active) map(.email)' data.json

Processing YAML

YAML files are read natively. All YAML features including anchors, aliases, and merge keys are supported:

# config.yaml
defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  debug: false

eu config.yaml -e 'production'

timeout: 30
retries: 3
debug: false

YAML Timestamps

YAML timestamps are automatically converted to date-time values:

created: 2024-03-15
updated: 2024-03-15T14:30:00Z

Quote the value to keep it as a string: created: "2024-03-15".

Processing TOML

eu config.toml -e 'database.port'

5432

Processing CSV

CSV files are imported as a list of blocks, where each row becomes a block with column headers as keys:

eu -e 'rows filter(_.age num > 30)' rows=people.csv

CSV values are always strings. Use num to convert to numbers when needed.

Processing XML

XML is imported as a nested list structure. Each element is represented as [tag, attributes, ...children]:

eu -e 'root' root=xml@data.xml

Use list functions to navigate the structure:

{ import: "root=xml@data.xml" }

# Get the tag name (first element)
tag: root first

# Get attributes (second element)
attrs: root second

# Get child elements (everything after the first two)
children: root drop(2)

Named Inputs

Use named inputs to make data available under a specific name:

eu users=users.json roles=roles.json -e 'users map(.name)'

Named inputs are essential for list-based formats (CSV, JSON Lines, text):

eu lines=text@log.txt -e 'lines filter(str.matches?("ERROR")) count'

Combining Multiple Sources

A powerful pattern is combining data from multiple sources:

eu users.yaml roles.yaml merge.eu

Where merge.eu contains logic that uses names from both inputs:

# merge.eu
summary: {
  user-count: users count
  role-count: roles count
}

Using Evaluands

The -e flag specifies an expression to evaluate against the loaded inputs:

# Select a nested value
eu config.yaml -e 'database.host'

# Transform and filter
eu data.json -e 'items filter(.price > 100) map(.name)'

# Aggregate
eu data.json -e 'items map(.price) foldl(+, 0)'

Collecting Inputs

The --collect-as (-c) flag gathers multiple files into a list:

eu -c configs *.yaml -e 'configs map(.name)'

Add --name-inputs (-N) to get a block keyed by filename:

eu -c configs -N *.yaml

configs:
  a.yaml:
    name: alpha
  b.yaml:
    name: beta

Output Formats

Control the output format:

The format can also be inferred from the output file:

eu data.yaml -o output.json

Practical Example: Data Pipeline

Suppose you have a CSV of sales data and want to generate a JSON summary:

eu sales=sales.csv -j -e '{
  total: sales map(.amount num) foldl(+, 0)
  count: sales count
  regions: sales map(.region) unique
}'

Or as a reusable eucalypt file:

# report.eu
{ import: "sales=sales.csv" }

` :suppress
amounts: sales map(.amount num)

report: {
  total: amounts foldl(+, 0)
  count: sales count
  average: report.total / report.count
}

eu report.eu -j -e report

Key Concepts

• Eucalypt reads JSON, YAML, TOML, CSV, XML, EDN, JSON Lines, and plain text
• Output defaults to YAML; use -j for JSON or -x for other formats
• Named inputs (name=file) give data a name for reference
• The -e flag evaluates expressions against loaded data
• --collect-as gathers multiple files into a list or block
• CSV values are strings; use num to convert to numbers
• Combine multiple sources with the command line input system or imports

The Command Line

In this chapter you will learn:

• The eu command structure and subcommands
• How to specify inputs, outputs, and evaluands
• How to use targets, arguments, and environment variables
• How to use the formatter and other tools

Command Structure

eu [GLOBAL_OPTIONS] [SUBCOMMAND] [SUBCOMMAND_OPTIONS] [FILES...]

When no subcommand is given, run is assumed:

eu file.eu          # same as: eu run file.eu

Subcommands

Inputs

File Inputs

Specify one or more files to process:

eu data.yaml transform.eu

Inputs are merged left to right. Names from earlier inputs are available to later ones. The final input determines what is rendered.

stdin

Use - to read from stdin, or simply pipe data when no files are specified:

curl -s https://api.example.com/data | eu -e 'items count'

Format Override

Override the assumed format with a format@ prefix:

eu yaml@data.txt json@-

Named Inputs

Prefix with name= to make the input available under a name:

eu config=settings.yaml app.eu

In app.eu, the YAML content is available as config:

port: config.port

Collecting Inputs

Gather multiple files into a named collection:

eu -c data *.json -e 'data map(.name)'

Add -N to key by filename:

eu -c data -N *.json

Outputs

Format

Output defaults to YAML. Common options:

eu file.eu            # YAML (default)
eu file.eu -j         # JSON (shortcut)
eu file.eu -x json    # JSON (explicit)
eu file.eu -x toml    # TOML
eu file.eu -x text    # Plain text

Output File

Write to a file (format inferred from extension):

eu data.eu -o output.json

Evaluands

The -e flag specifies an expression to evaluate:

eu -e '2 + 2'

4

When combined with file inputs, the evaluand has access to all loaded names:

eu data.yaml -e 'users filter(.active) count'

Multiple -e flags are allowed; the last one determines the output.

Quick Expressions

Use -e for quick data exploration:

# Inspect a value
eu config.yaml -e 'database'

# Count items
eu data.json -e 'items count'

# Extract and transform
eu data.json -e 'items map(.name) reverse'

Targets

Declarations annotated with :target metadata can be selected for rendering:

# multi-output.eu
` { target: :summary }
summary: { count: items count }

` { target: :detail }
detail: items

List available targets:

eu list-targets multi-output.eu

Select a target:

eu -t summary multi-output.eu

A target named main is rendered by default. If no :main target exists, the entire unit is the target.

Passing Arguments

Arguments after -- are available via io.args:

eu -e 'io.args' -- hello world

- hello
- world

Use in scripts:

# greet.eu
name: io.args head-or("World")
greeting: "Hello, {name}!"

eu greet.eu -e greeting -- Alice

Hello, Alice!

Arguments are strings. Use num to convert:

numbers: io.args map(num)
total: numbers foldl(+, 0)

Environment Variables

Access environment variables through io.env:

home: io.env lookup-or(:HOME, "/tmp")
path: io.env lookup(:PATH)

Random Seed

By default, random numbers use system entropy. Use --seed for reproducible output:

eu --seed 42 template.eu

The Formatter

Format eucalypt source files:

eu fmt file.eu              # print formatted to stdout
eu fmt --write file.eu      # format in place
eu fmt --check file.eu      # check (exit 1 if unformatted)
eu fmt --reformat file.eu   # full reformatting

Options:

• -w, --width <N> -- line width (default: 80)
• --indent <N> -- indent size (default: 2)

Debugging

Dumping Intermediate Representations

eu dump ast file.eu         # syntax tree
eu dump desugared file.eu   # core expression
eu dump stg file.eu         # compiled STG

Explaining Execution

eu explain file.eu          # show what would be executed

Statistics

eu -S file.eu               # print metrics to stderr

Batch Mode

Use -B for repeatable builds (disables ergonomic mode and ~/.eucalypt):

eu -B file.eu

Suppressing the Prelude

The standard prelude is loaded automatically. Suppress it with -Q:

eu -Q file.eu

Warning: Without the prelude, even true, false, if, and basic operators are unavailable.

Version Assertions

Ensure a minimum eu version in source files:

_ : eu.requires(">=0.3.0")

Check the current version:

eu version

LSP Server

Start a Language Server Protocol server for editor integration:

eu lsp

Provides syntax error diagnostics and formatting support.

Key Concepts

• eu defaults to run when no subcommand is given
• Inputs are merged left to right; the final input determines output
• Named inputs (name=file) provide namespace isolation
• -e evaluates an expression against loaded inputs
• -t selects a named target for rendering
• -- passes arguments available via io.args
• eu fmt formats source files; eu test runs tests; eu lsp starts the language server

YAML Embedding

Eucalypt can be embedded in YAML files via the following tags:

• eu
• eu::suppress
• eu::fn

The YAML embedding is not as capable as the native Eucalypt syntax but it is rich enough to be used for many YAML templating use cases, particularly when combined with the ability to specify several inputs on the command line.

Evaluating eucalypt expressions

As you would expect, YAML mappings correspond to Eucalypt blocks and bind names just as Eucalypt blocks do and YAML sequences correspond to Eucalypt lists.

YAML allows a wide variety of forms of expressing these (block styles and flow styles), to the extent that JSON is valid YAML.

Eucalypt expressions can be evaluated using the !eu tag and have access to all the names defined in the YAML unit and any others brought into scope by specifying inputs on the command line.

values:
  x: world
  y: hello

result: !eu "{values.y} {values.x}!"

...will render as:

values:
  x: world
  y: hello

result: Hello World!

Suppressing rendering

Items can be hidden using the eu::suppress tag. This is equivalent to :suppress metadata in the eucalypt syntax.

values: !eu::suppress
  x: world
  y: hello

result: !eu "{values.y} {values.x}!"

...will render as:

result: Hello World!

Defining functions

Functions can be defined using eu::fn and supplying an argument list:

values: !eu::suppress
  x: world
  y: hello
  greet: !eu::fn (h, w) "{h} {w}!"

result: !eu values.greet(values.y, values.x)

...will render as:

result: Hello World!

The escape hatch

Larger chunks of eucalypt syntax can be embedded using YAML's support for larger chunks of text, combined with !eu. Using this workaround you can access capabilities of eucalypt that are not yet available in the YAML embedding. (Although operators cannot be made available in YAML blocks because of the way that operator names are bound - see Operator Precedence Table.)

block: !eu |
  {
    x: 99
    (l ^^^ r): "{l} <_> {r}"
    f(n): n ^^^ x
  }

result: block.f(99)

Testing with Eucalypt

Eucalypt has a built-in test runner which can be used to run tests embedded in eucalypt files.

Test mode is invoked by the eu test subcommand and:

• analyses the file to build a test plan consisting of a list of test targets and validations to run
• executes the test plan and generates an evidence file
• applies validations against the evidence to generate a results file
• outputs results and generates an HTML report

Simple tests

By default eucalypt searches for targets beginning with test- and runs each to render a yaml output. The result is parsed read back in and eucalypt checks for the presence of a RESULT key. If it finds it and the value is PASS, the test passes. Anything else is considered a fail.

my-add(x, y): x + y

` { target: :test-add }
test: {
  RESULT: (2 + 2 = 4) then(:PASS, :FAIL)
}

Several test targets can be embedded in one file. Each is run as a separate test.

Test files

If your intention is not to embed tests in a eucalypt file but instead to write a test as a single file, then you can omit the test targets. Eucalypt will use a main target or run the entire file as usual and then validate the result (looking for a RESULT key, by default).

Other formats

In test mode, eucalypt processes the test subject to generate output and then parses that back to validate the result. This is to provide for validation of the rendered text and the parsing machinery.

By default YAML is generated and parsed back for each test target in the file but other formats can be selected in header metadata.

{
  test-targets: [:yaml, :json]
}

` { target: :test-add }
add: {
  RESULT: (2 + 2 = 4) then(:PASS, :FAIL)
}

` { target: :test-sub }
sub: {
  RESULT: (2 - 2 = 0) then(:PASS, :FAIL)
}

Running this file using eu test will result in four tests being run, two formats for each of the two targets.

Using the default validator, for all formats for which eucalypt provides import and export capability, it shouldn't make any difference which format is used. However, custom validators provide the ability to check the precise text that is rendered.

Custom validators

When a test runs, the execution generates an evidence block which has the following keys:

• exit the exit code (0 on success) of the eucalypt execution
• stdout text as a list of strings
• stderr text as a list of strings
• result (the stdout parsed back)
• stats some statistics from the run

Date, Time, and Random Numbers

Zoned Date-Time (ZDT) Values

Eucalypt has native support for date-time values through the ZDT (Zoned Date-Time) type. ZDT values represent a point in time with timezone information.

ZDT Literals

Use the t"..." prefix to write date-time literals directly in eucalypt source:

today: t"2024-03-15"
meeting: t"2024-03-15T14:30:00Z"
local: t"2024-03-15T14:30:00+01:00"

The t"..." syntax accepts ISO 8601 formats:

Parsing and Formatting

The cal namespace provides functions for working with date-time values:

# Parse from a string
d: cal.parse("2024-03-15T14:30:00Z")

# Format to a custom string
label: t"2024-03-15" cal.format("%Y-%m-%d")  # "2024-03-15"

Date-Time Arithmetic

ZDT values support comparison operators:

before: t"2024-01-01" < t"2024-12-31"   # true
same: t"2024-03-15" = t"2024-03-15"     # true

Sorting Date-Times

dates: [t"2024-12-25", t"2024-01-01", t"2024-07-04"]
sorted: dates sort-zdts  # [Jan 1, Jul 4, Dec 25]

YAML Timestamps

When importing YAML files, unquoted timestamp values are automatically converted to ZDT values:

created: 2024-03-15
updated: 2024-03-15T14:30:00Z

Quote the value to keep it as a string: created: "2024-03-15".

See Import Formats for full details.

Current Time

The io.epoch-time binding provides the current Unix epoch time in seconds:

now: io.epoch-time

Random Numbers

Eucalypt provides pseudo-random number generation via the random namespace, which is a state monad over a PRNG stream.

The random stream

A random stream is provided at startup as io.random. Each run produces different values unless you supply a seed:

eu --seed 42 example.eu

Single random values

For a single random value, pass io.random as the stream:

roll: random.int(6, io.random).value + 1
colour: random.choice(["red", "green", "blue"], io.random).value

Each operation returns a {value, rest} block — extract .value to get the result.

Multiple random values

When you need several random values, you must propagate the stream from each call to the next. Reusing io.random would give the same value each time:

# WRONG — both use the same stream, so d1 = d2
d1: random.int(6, io.random).value
d2: random.int(6, io.random).value

# RIGHT — thread the stream manually
r1: random.int(6, io.random)
r2: random.int(6, r1.rest)
total: r1.value + r2.value + 2

This manual threading is error-prone. The random monad can ease the overhead somewhat — use a { :random ... } monadic block or combinators like sequence and map-m:

# Monadic block — stream threads automatically
dice: { :random
  d6: random.int(6)
  d20: random.int(20)
}.[d6, d20]

result: dice(io.random).value  # e.g. [3, 14]

# Or use sequence for a list of actions
two-dice: random.sequence([random.int(6), random.int(6)], io.random).value

Other operations

shuffled: random.shuffle(["a", "b", "c", "d"], io.random).value
picked: random.sample(3, range(1, 50), io.random).value

See the Random Numbers reference for the full API and the Monads guide for details on the state monad pattern.

IO and Shell Commands

As of version 0.5.0 Eucalypt can execute IO by invoking shell commands, via the IO monad.

Eucalypt is not a scripting language, it is a small, lazy, dynamically typed, pure functional language for transformation and templating of semi-structured data formats and that remains its sweet spot. Do not get too ambitious.

However, prior to the IO monad, arranging the sources of data in and out of the program was limited to what could be named or streamed in from the shell, and piped to pre-planned destinations. Allowing more direct control over IO within the process (while staying within the functional paradigm) allows much more flexibility.

IO operations are sequenced strictly by the runtime and the monad idiom.

All IO operations require the --allow-io / -I flag.

The IO monad

This is not a monad tutorial. Suffice it to say than an IO action (which may have side effects) is represented by an object in Eucalypt. The monad and the runtime together, ensure that the action is run at the appropriate time and its output is safely incorporated into the computation without imperiling the referential transparency of non-IO code.

In initial versions of this functionality, the only IO capability available is running shell programs or binaries from eucalypt, and passing data in and out of them. Data passed into and out of the shelled program is not streamed incrementally, but buffered whole. This is not suitable for large data pipelines.

The monad provides several ways to create IO actions, and string them together. When you run a eucalypt program, if the value of the named target (or :main target) is an IO action, that is run.

Just embedding an IO action in a data structure is not sufficient to have it execute. It must either be the value of the top-level target of a program, or invoked in some way by that action.

The key monad functions bind and return are defined in the io namespace, along with several traditional monad combinators. This supports the use of { :io ... } monadic blocks to combine several monad actions into one. Monads and the monad() Utility explains Eucalypt's monad machinery in a little more detail.

A simple IO action that doesn't perform any IO at all but represents a constant value, can be created with io.return. e.g.

greeting: io.return("hello")

To create more interesting IO actions, read on.

Running a shell command

The simplest way to run a command is io.shell:

result: "echo hello" io.shell

This creates an IO action which runs the specified command via sh -c and returns a block:

stdout: "hello\n"
stderr: ""
exit-code: 0

To extract a specific field, either use generalised lookup syntax on an :io monad block...

{ :io r: io.shell("echo hello") }.(r.stdout)

... or use io.map to apply a section within the IO monad chain.

"echo hello" io.shell io.map(.stdout)

The { :io ... } monadic block

A block tagged :io desugars into nested io.bind calls. Each field is a bind step; the name becomes available in all subsequent steps. The .() expression after the closing brace is the return value.

{ :io
  r: io.shell("echo hello")
  _: io.check(r)
}.(r.stdout)

Important: unlike normal blocks, monadic blocks bind names sequentially — each step can only refer to names from earlier steps, not later ones. See Monads and the monad() Utility for full details on monadic block syntax, forms, and the sequential binding constraint.

Checking for errors

io.check inspects a command result. If the exit code is non-zero, it fails the IO monad with the stderr message. Otherwise it returns the result unchanged:

{ :io
  r: io.shell("grep pattern file.txt")
  _: io.check(r)
}.(r.stdout)

If grep finds no matches (exit code 1), this produces an io.fail error with whatever was on stderr.

Exec: running a binary directly

io.exec runs a binary without going via the shell. The argument is a list where the first element is the command and the rest are arguments:

{ :io
  r: io.exec(["git", "rev-parse", "HEAD"])
}.(r.stdout)

If the binary does not exist, io.exec returns a result block with exit-code 127 and the OS error in stderr, rather than failing outright.

Options: stdin, timeout

Both io.shell-with and io.exec-with accept an options block as the first argument. This is merged into the spec block, overriding defaults:

"cat" io.shell-with{stdin: "hello world", timeout: 60} io.map(.stdout)

Available options:

The pipeline style reads naturally: the command string flows into shell-with which receives the options.

Combining IO actions

Sequencing with bind

io.bind chains two actions. The continuation receives the result of the first action:

io.bind(io.shell("echo hello"),
  _(r): io.shell("echo got: {r.stdout}"))

The { :io ... } block is almost always preferable to explicit io.bind calls.

Mapping over a result

io.map applies a pure function to the result of an action without needing a new IO step. The function can, of course, be a composition of several functions:

` :main
result: "curl https://example.com/test.json" io.shell io.map((.stdout) ; parse-as(:json))

Failing explicitly

io.fail aborts the IO monad with an error message:

{ :io
  r: io.shell("some-command")
  _: (r.exit-code = 0) then(io.return(r), io.fail("command failed: {r.stderr}"))
}.(r.stdout)

This is what io.check does internally — it is a convenience wrapper around this pattern:

` :main
greeting: "echo hello world" io.shell io.check io.map(.stdout)

Practical examples

Git commit hash

` :main
hash: "git rev-parse --short HEAD" io.shell io.check io.map(.stdout)

Run a command and parse the output as JSON

` :main
data: "curl -s https://api.example.com/data" 
  io.shell 
  io.check 
  io.map((.stdout) ; parse-as(:json))

Pipe data through a command

` :main
text: { :io
  r: "jq '.name'" io.shell-with({stdin: render-as(:json, data)})
}.(r.stdout)

Multiple commands in sequence

` :main
main: { :io
  a: io.shell("date +%s")
  b: io.shell("hostname")
}.(
  { timestamp: a.stdout 
    host: b.stdout }
)

or, equivalently:

io.sequence[io.shell("date +%s") io.map(.stdout),
            io.shell("hostname") io.map(.stdout)] with-keys[:timestamp, :host]

Testing IO code

Test targets that use IO should include requires-io: true in their target metadata. The test runner (eu test) skips these tests gracefully when --allow-io is not set:

` { target: :test requires-io: true }
test:
  { :io r: io.exec(["echo", "hello"]) }.(
    if(r.stdout str.matches?("hello.*"),
      { RESULT: :PASS },
      { RESULT: :FAIL }))

Reference

For the full API table, see the IO prelude reference.

For the monadic programming model, monad() utility, and how to build your own monads, see Monads and the monad() Utility.

Monads and the monad() Utility

Eucalypt has first-class support for monadic programming. Two built-in namespaces — io and random — are monads, and the monad() utility lets you build additional ones from just bind and return.

What is a monad in eucalypt?

A monad is just two primitives, which are conventionally grouped in a namespace.

With these two primitives available an alternative interpretation of the block structure, monadic blocks can be used.

Other monadic functions — map, then, join, sequence, map-m, filter-m — are typically provided in the same namespace and can be derived automatically with the aid of the monad function.

Monads are required for performing IO from eucalypt code and may be used to simplify random number access. Users may define monads themselves and assign unicode brackets to them if they so wish.

Monadic blocks

Eucalypt provides syntactic sugar for chaining monadic actions. A block tagged with a monad namespace name desugars into nested bind calls automatically.

The most common form tags the block with :io:

{ :io
  r: io.shell("echo hello")
  _: io.check(r)
}.(r.stdout)

This desugars to:

io.bind(io.shell("echo hello"),
  λr. io.bind(io.check(r),
    λ_. io.return(r.stdout)))

Each field becomes a bind step. The bound name is available in all subsequent steps. The .() expression after the closing brace is the return expression, wrapped in the monad's return.

Key constraint: sequential binding

Unlike normal blocks, names in a monadic block can only refer to names bound in earlier steps. Normal eucalypt blocks are declarative — bindings can refer to each other in any order. Monadic blocks are sequential — each step can only see what came before it, because the desugaring nests each continuation inside the previous one.

# WRONG — b is not yet bound when a is evaluated
{ :io
  a: io.map(inc, b)
  b: io.shell("echo 1")
}.(a)

# RIGHT — b is bound before a uses it
{ :io
  b: io.shell("echo 1")
  a: io.map(inc, b)
}.(a)

Block metadata forms

Several syntax forms are available for monadic blocks:

Form 1 is the most common — { :io ... } tags a block with the io namespace. The desugarer looks up io.bind and io.return automatically.

Custom bracket pairs

You can define bracket pairs for monadic notation using the :monad metadata:

⟦{}⟧: { :monad bind: my-bind  return: my-return }

result: ⟦ x: some-action  y: other-action(x) ⟧.(x + y)

See the syntax reference for full details on bracket pair definitions.

The monad() utility

monad(m) takes a block with bind and return fields and returns a block of derived combinators:

my-monad: monad{bind: my-bind, return: my-return}

The returned block provides:

Building a monadic namespace

The typical pattern is to use monad() to produce the derived operations and then catenate (merge) domain-specific operations on top:

my-ns: monad{bind: my-bind, return: my-return} {
  some-extra-op(x): ...
}

Since monad() includes bind and return in its result, there is no need to repeat them in the right-hand block.

Why catenation (not <<)? Catenation is shallow merge — the right-hand block's fields override the left-hand block's fields at the top level. << is deep merge and is not appropriate here because the derived combinators are not nested blocks.

Overriding a derived combinator — put the specialised implementation in the right-hand block; it shadows the derived one:

my-ns: monad{bind: my-bind, return: my-return} {
  # override map with a more efficient implementation
  map(f, action): my-efficient-map(f, action)
}

The IO monad

The io namespace is a monad built around effect execution. IO operations cause side effects (shell commands, reads, writes). The eucalypt runtime sequences them strictly.

IO operations require --allow-io / -I at the command line.

Primitives

io.return(v)             # wrap a pure value; no side effects
io.bind(action, f)       # run action, pass result to f

Practical example

result: { :io
  r: io.shell("git rev-parse HEAD")
  _: io.check(r)
}.(r.stdout)

Extending the IO monad

You can derive additional combinators or extend with domain-specific operations via catenation:

app-io: monad{bind: io.bind, return: io.return} {
  read-file(path): io.shell("cat {path}")
  git-hash: io.shell("git rev-parse HEAD")
}

IO combinators reference

See IO and Shell Commands for practical usage and the IO reference for the full API.

The random state monad

The random namespace implements a state monad over a PRNG stream. A random stream is provided at startup as io.random (seeded from the system or from --seed). Each random operation consumes part of the stream and returns a {value, rest} block — value is the result and rest is the remaining stream for subsequent operations.

The pitfall: forgetting to propagate the stream

For a single random value, passing io.random directly is simple:

roll: random.int(6, io.random).value + 1

But when you need multiple random values, you must thread the .rest stream from each call into the next:

r1: random.int(6, io.random)
r2: random.int(6, r1.rest)       # must use r1.rest, not io.random!
total: r1.value + r2.value + 2

If you accidentally pass io.random to both calls, you get the same random value twice. This manual threading is error-prone and verbose — which is exactly what the random monad solves.

With the monad: automatic threading

A { :random ... } monadic block threads the stream automatically:

triple: { :random
  d6: random.int(6)
  d20: random.int(20)
  d100: random.int(100)
}.[d6, d20, d100]

result: triple(io.random).value  # e.g. [3, 14, 57]

Each step receives the stream left over from the previous step — no manual .rest threading needed. The return expression (.[d6, d20, d100]) collects the results into a list.

The monadic block produces an action — a function that takes a stream — so you run it by passing io.random and extracting .value.

For common patterns, sequence and map-m are even more concise:

# Sequence a list of actions
two-dice: random.sequence[random.int(6), random.int(6)]
result: two-dice(io.random).value  # list of two rolls

# Map an action over a list of die sizes
dice: random.map-m(random.int, [4, 6, 8, 10, 20])
rolls: dice(io.random).value   # e.g. [2, 4, 1, 7, 15]

Important: always extract .value before rendering — the .rest field is an infinite stream and will hang if you try to print it.

Deterministic seeds

For reproducible output (useful in tests), pass --seed on the command line or create a stream from a fixed seed:

rolls: random.map-m(random.int, [6, 6])(random.stream(42)).value
# always produces the same result for seed 42

How the state monad works

Under the hood, random.return and random.bind are:

# return: wrap a pure value as a do-nothing action
random-ret(v, stream): { value: v, rest: stream }

# bind: run m, pass result to f, run f's action with remaining stream
random-bind(m, f, stream): {
  r: m(stream)
  run: f(r.value)(r.rest)
  value: run.value
  rest: run.rest
}

random-bind(m, f) is a 3-arg function; calling it with only two arguments returns an action (function of stream). This is the curried partial application pattern used throughout eucalypt.

Random combinators reference

Derived combinators (map, then, join, sequence, map-m, filter-m) are also available — see Random Numbers reference.

Writing your own monad

Any pair of functions satisfying the monad laws can be wrapped with monad(). Here is a minimal example — the identity monad, where "wrapping" a value is a no-op:

` :suppress
id-bind(m, f): f(m)
` :suppress
id-return(a): a
` :suppress
id-monad: monad{bind: id-bind, return: id-return}

` { target: :example }
example: id-monad.map-m(inc, [1, 2, 3])
# => [2, 3, 4]

A more useful example — a "maybe" monad where null short-circuits the computation:

` :suppress
maybe-return(v): v

` :suppress
maybe-bind(m, f): if(m = null, null, f(m))

` :suppress
maybe: monad{bind: maybe-bind, return: maybe-return}

safe-head(xs): if(xs nil?, null, xs head)

# Chain operations that may return null — short-circuits on first null
result: maybe.bind(safe-head([]), inc)   # => null (list was empty)
ok:     maybe.bind(safe-head([42]), inc) # => 43

Key concepts

• monad(m) takes {bind, return} and returns a block with bind, return, and six derived combinators
• Use catenation (juxtaposition) to merge derived and specialised operations — NOT <<
• Monadic blocks ({ :io ... }, { :name ... }) desugar into nested bind calls — names are bound sequentially, not declaratively
• The random: namespace is a state monad — actions are functions of a stream, bind threads the stream automatically
• When running random actions, always extract .value before rendering; the .rest field is an infinite stream

Advanced Topics

In this chapter you will learn:

• How the metadata system works
• How to use sets for unique collections
• How to search deep structures with deep-find and deep-query
• Format specifiers and formatting techniques
• Type predicates and other utilities

The Metadata System

Every value in eucalypt can carry metadata: a block of additional information that does not appear in the rendered output but can be inspected and used programmatically.

Attaching Metadata

Use the // operator to attach metadata to a value:

answer: 42 // { note: "the answer to everything" }

The value 42 is rendered normally; the metadata is hidden:

answer: 42

Reading Metadata

Use meta to retrieve the metadata block:

answer: 42 // { note: "the answer to everything" }
note: meta(answer).note

answer: 42
note: the answer to everything

Deep Merge Metadata

Use //<< to deep-merge additional metadata onto existing metadata:

x: 1 // { a: 1 }
y: x //<< { b: 2 }
result: meta(y)

x: 1
y: 1
result:
  a: 1
  b: 2

Declaration Metadata

Declaration metadata (written with the backtick syntax) is separate from value metadata. It controls how eucalypt processes the declaration:

` { doc: "A helper" export: :suppress }
helper(x): x + 1

Key metadata properties:

• doc -- documentation string
• export: :suppress -- hide from output
• target -- mark as an export target
• import -- import other files
• associates / precedence -- operator fixity (see Operators for details)

YAML Tags

Metadata can carry a tag key which renders as a YAML tag:

ref: :my-resource // { tag: "!Ref" }

ref: !Ref my-resource

This is useful for generating CloudFormation, Kubernetes, and other tagged YAML formats.

Assertions with //= and //=>

The //= operator asserts equality at runtime:

result: 2 + 2 //= 4  # panics if not equal

The //=> operator additionally stores the assertion as metadata:

checked: 2 + 2 //=> 4
m: meta(checked)  # contains the assertion

Sets

Sets are unordered collections of unique values, provided by the set namespace.

Creating Sets

eu -e '[1, 2, 2, 3, 3, 3] set.from-list set.to-list'

- 1
- 2
- 3

Duplicates are removed and elements are sorted.

The empty set is written as ∅:

eu -e '∅ set.to-list'

[]

Membership and Size

eu -e '[1, 2, 3] set.from-list set.contains?(2)'

true

eu -e '[1, 2, 3] set.from-list set.size'

3

eu -e '∅ set.empty?'

true

Adding and Removing

eu -e '∅ set.add(1) set.add(2) set.add(1) set.to-list'

- 1
- 2

eu -e '[1, 2, 3] set.from-list set.remove(2) set.to-list'

- 1
- 3

Set Algebra

Union:

a: [1, 2] set.from-list
b: [2, 3] set.from-list
result: a set.union(b) set.to-list

result:
- 1
- 2
- 3

Intersection:

a: [1, 2, 3] set.from-list
b: [2, 3, 4] set.from-list
result: a set.intersect(b) set.to-list

result:
- 2
- 3

Difference:

a: [1, 2, 3] set.from-list
b: [2, 3] set.from-list
result: a set.diff(b) set.to-list

result:
- 1

Deep Find

deep-find recursively searches a nested block structure for all values associated with a given key name:

eu -e 'deep-find("host", { server: { host: "10.0.0.1" db: { host: "10.0.0.2" } } })'

- 10.0.0.1
- 10.0.0.2

deep-find-first

Return just the first match, or a default:

eu -e 'deep-find-first("host", "unknown", { server: { host: "10.0.0.1" } })'

10.0.0.1

deep-find-paths

Return the key paths to each match:

eu -e 'deep-find-paths("host", { server: { host: "a" db: { host: "b" } } })'

- - server
  - host
- - server
  - db
  - host

Deep Query

deep-query provides a more powerful pattern-based search using dot-separated patterns with wildcards.

Bare Key (Recursive Search)

A bare key name searches recursively (equivalent to **.key):

eu -e 'deep-query("port", { web: { port: 80 } db: { port: 5432 } })'

- 80
- 5432

Dotted Path

A dotted path matches a specific path:

eu -e 'deep-query("server.host", { server: { host: "10.0.0.1" port: 80 } })'

- 10.0.0.1

Wildcard *

* matches exactly one level:

eu -e 'deep-query("*.port", { web: { port: 80 } db: { port: 5432 } name: "app" })'

- 80
- 5432

Double Wildcard **

** matches any depth:

eu -e 'deep-query("config.**.port", { config: { port: 9090 nested: { deep: { port: 3000 } } } })'

- 9090
- 3000

Variants

• deep-query-first(pattern, default, block) -- first match or default
• deep-query-paths(pattern, block) -- key paths of matches

Type Predicates

Test the type of a value:

eu -e '{ a: 1 } block?'

true

eu -e '[1, 2] list?'

true

Sorting

qsort

Sort with a custom comparison:

eu -e '["banana", "apple", "cherry"] qsort(<)'

- apple
- banana
- cherry

Sort by a derived key. Here str.letters ; count is a forward composition (see Functions and Combinators) that extracts the letter count:

` :suppress
shorter(a, b): (a str.letters count) < (b str.letters count)

words: ["one", "two", "three", "four", "five", "six"]
by-length: words qsort(shorter)

words:
- one
- two
- three
- four
- five
- six
by-length:
- one
- two
- six
- four
- five
- three

The prelude also provides sort-by(key-fn, cmp) as a convenience for this pattern:

by-length: words sort-by(str.letters ; count, <)

sort-nums

Sort numbers in ascending order:

eu -e '[30, 10, 20] sort-nums'

- 10
- 20
- 30

Grouping

group-by

Group list elements by a key function:

items: [
  { type: "fruit" name: "apple" }
  { type: "veg" name: "carrot" }
  { type: "fruit" name: "banana" }
]

grouped: items group-by(.type)

items:
- type: fruit
  name: apple
- type: veg
  name: carrot
- type: fruit
  name: banana
grouped:
  fruit:
  - type: fruit
    name: apple
  - type: fruit
    name: banana
  veg:
  - type: veg
    name: carrot

Format Specifiers

Format specifiers in interpolation control output formatting. They use printf-style codes after a colon inside the interpolation braces.

results: {
  n: 42
  padded: "{n:%06d}"
  pi: 3.14159
  float: "{pi:%.2f}"
  h: 255
  hex: "{h:%x}"
}

results:
  padded: '000042'
  float: '3.14'
  hex: ff

Available Format Codes

Flags and Modifiers

• %- — left-align
• %+ — prepend + for positive numbers
• %0 — zero-padding (e.g. %06d)
• %# — alternate form (e.g. 0x prefix for hex)
• Width: %10s — minimum field width
• Precision: %.2f — decimal places for floats

See also the Strings and Text chapter for more on string interpolation.

Version Assertions

Assert a minimum version of eu:

_ : eu.requires(">=0.3.0")

Access build metadata:

info: {
  version: eu.build.version
  prelude: eu.prelude.version
}

Key Concepts

• Metadata (//) attaches hidden information to values; meta retrieves it
• Sets (set.*) provide unique collections with union, intersection, and difference
• Deep find recursively searches nested blocks by key name
• Deep query supports pattern-based search with * and ** wildcards
• Type predicates (block?, list?) test value types
• qsort sorts with custom comparators; format specifiers control numeric output
• eu.requires asserts a minimum version for compatibility

Language Syntax Reference

Eucalypt has a native syntax which emphasises the mappings-and-lists nature of its underlying data model but adds enhancements for functions and expressions. Eucalypt is written in .eu files.

While eu happily processes YAML inputs with embedded expressions, many features are not yet available in the YAML embedding and the embedded expressions are themselves in Eucalypt syntax, so it is necessary to have an overview of how the syntax works to do anything interesting with Eucalypt.

A few aspects are unorthodox and experimental.

Overview

Eucalypt syntax comes about by the overlapping of two sub-languages.

• the block DSL is how you write blocks and their declarations
• the expression DSL is how you write expressions

They are entwined in a fairly typical way: block literals (from the block DSL) can be used in expressions (from the expression DSL) and expressions (from the expression DSL) appear in declarations (from the block DSL).

Comments can be interspersed throughout. Eucalypt only has line level comments.

foo: bar # Line comments start with '#' and run till the end of the line

Note: If you feel you need a block comment, you can use an actual block or a string property within a block and mark it with annotation metadata :suppress to ensure it doesn't appear in output.

Eucalypt has two types of names:

• normal names, which are largely alphanumeric (e.g. f, blah, some-thing!, ॵ) and are used to name properties and functions
• operator names, which are largely symbolic (e.g. &&&, ∧, -+-|, ⊚) and are used to name operators

See Operator Precedence Table for more.

The block DSL

A block is surrounded by curly braces:

... { ... }

...and contains declarations...

... {
  a: 1
  b: 2
  c: 3
}

...which may themselves have blocks as values...

... {
  foo: {
    bar: {
      baz: "hello world"
    }
  }
}

The top-level block in a file (a unit) does not have braces:

a: 1
b: 2
c: 3

Blocks may also have a single expression, preceding its declarations which constitutes block metadata. This is optional.

So the block pattern is braces (except for the unit level) containing, optionally metadata, then any number of declarations.

{ «metadata expression»?  [«declaration»]* }

Both the metadata expression and the declarations may contain blocks. This recursive application of the block pattern defines the major structure of any eucalypt code.

So far all the declarations we have seen have been property declarations which contain a name and an expression, separated by a colon.

Commas are entirely optional for delimiting declarations. Line endings are not significant. The following is a top-level block of three property declarations.

a: 1 b: 2 c: 3

There are other types of declarations. By specifying a parameter list, you get a function declaration:

# A function declaration
f(x, y): x + y

two: f(1, 1)

Function parameters can be destructuring patterns as well as simple names. A block pattern extracts named fields from a block argument; a list pattern extracts positional elements from a list argument:

# Block destructuring — shorthand binds field name as variable name
sum-xy({x y}): x + y

# Block destructuring — rename binds field under a new variable name
product-ab({x: a  y: b}): a * b

# Mixed shorthand and rename
mixed({x  y: b}): x + b

# Fixed-length list destructuring
f-sum([a, b, c]): a + b + c
f-first([a, b]): a

# Head/tail list destructuring — colon separates fixed heads from tail
get-head([x : xs]): x
get-tail([x : xs]): xs
drop-two([a, b : rest]): rest

Juxtaposed call syntax passes a block or list literal as a single argument without parentheses. No space between the function name and the opening bracket:

# f{...} is sugar for f({...})
sum-xy{x: 10 y: 20}

# f[...] is sugar for f([...])
add-pair[1, 2]

Combined with block destructuring, this gives named arguments:

greet({name greeting}): "{greeting}, {name}!"
greet{name: "Alice" greeting: "Hello"}    # => "Hello, Alice!"

Juxtaposed syntax also works in definitions — the bracket or brace is written directly against the function name with no space. This is sugar for the parenthesised destructuring form:

# f[x, y]: ...  is sugar for  f([x, y]): ...
add-pair[a, b]: a + b

# f{x y}: ...   is sugar for  f({x y}): ...
add-block{x y}: x + y

# f[h : t]: ... is sugar for  f([h : t]): ...
my-head[h : t]: h

Destructuring patterns can be mixed with normal parameters:

f(n, [a, b]): n * (a + b)

The ‖ operator (U+2016, DOUBLE VERTICAL LINE) prepends an element to a list. It is right-associative:

1 ‖ [2, 3]        # => [1, 2, 3]
1 ‖ 2 ‖ [3]       # => [1, 2, 3]

See Functions and Combinators for more detail on destructuring.

...and using some brackets and suitable names, you can define operators too, either binary:

# A binary operator declaration
(x ^|^ y): "{x} v {y}"

...or prefix or postfix unary operators:

# A prefix operator declaration
(¬ x): not(x)

# A postfix operator declaration
(x ******): "maybe {x}"

Eucalypt should handle unicode gracefully and any unicode characters in the symbol or punctuation classes are fine for operators.

In addition to named operators, you can define idiot brackets — custom Unicode bracket pairs that wrap an expression and apply a function to it. The name is inspired by idiom brackets from applicative functor notation, but they are a general bracket overloading mechanism. A bracket pair declaration uses a Unicode bracket pair wrapping a single parameter directly (paren-free style):

# Ceiling brackets double
⌈ x ⌉: x * 2

# Floor brackets increment
⌊ x ⌋: x + 1

The older paren-wrapped style is still supported for backwards compatibility:

(⌈ x ⌉): x * 2    # paren style — still valid

Once declared, the bracket pair can be used as an expression:

doubled: ⌈ 3 + 4 ⌉    # => 14
bumped:  ⌊ 5 ⌋         # => 6

The declaration ⌈ x ⌉: body defines a function named ⌈⌉ (open then close bracket) that takes one argument x and returns body. Using ⌈ expr ⌉ in an expression calls that function with expr.

The following Unicode bracket pairs are built-in and can be used for idiot brackets without any registration:

Monadic blocks

Eucalypt supports monadic sequencing — analogous to Haskell do-notation — through two mechanisms: bracket pair definitions and block metadata.

Bracket pair definitions

A bracket pair gains a monad spec when declared with an empty block {} as its parameter and a body marked with :monad metadata, supplying bind and return function names:

# Explicit bind/return functions
⟦{}⟧: { :monad bind: my-bind  return: my-return }

# Namespace reference — delegates to a block with bind and return members
⟦{}⟧: { :monad namespace: my-monad }

A bracket expression whose inner content contains top-level colons is parsed as a bracket block — a sequence of name: monadic-action declarations. The closing bracket must be followed by a dot and a return expression:

result: ⟦ a: ma  b: mb ⟧.return_expr

Block metadata forms

Regular blocks can also be desugared monadically when the block carries monad metadata and is immediately followed by .return_expr in an expression. Five forms are accepted:

For namespace forms (1–3 and 5), the named value must be a block in scope with bind and return member functions. The desugarer emits name.bind(…) and name.return(…) lookup expressions.

Desugaring

All monadic block forms desugar to a right-to-left bind chain:

bind(ma, (a): bind(mb, (b): return(return_expr)))

All declarations are bind steps. Each bound name is in scope for later actions and for the return expression. The return expression may be any single element: a name (.r), a parenthesised expression (.(x + y)), a list, or a block.

Example — identity monad (bracket pair, explicit functions):

id-bind(ma, f): f(ma)
id-return(a): a

⟦{}⟧: { :monad bind: id-bind  return: id-return }

result: ⟦ x: 10  r: x + 5 ⟧.r     # => 15

Example — maybe monad (namespace reference via block metadata):

maybe: { bind(ma, f): if(ma = [], [], f(ma head))  return(a): [a] }

just:    { :maybe x: [1]  y: [2] }.(x + y)   # => [3]
nothing: { :maybe x: []   y: [2] }.(x + y)   # => []

Example — maybe monad (bracket pair with namespace reference):

maybe: { bind(ma, f): if(ma = [], [], f(ma head))  return(a): [a] }

⌈{}⌉: { :monad namespace: maybe }

just:    ⌈ x: [1]  y: [2] ⌉.(x + y)   # => [3]
nothing: ⌈ x: []   y: [2] ⌉.(x + y)   # => []

To control the precedence and associativity of user defined operators, you need metadata annotations.

Declaration annotations allow us to specify arbitrary metadata against declarations. These can be used for documentation and similar.

To attach an annotation to a declaration, squeeze it between a leading backtick and the declaration itself:

` { doc: "This is a"}
a: 1

` { doc: "This is b"}
b: 2

Some metadata activate special handling, such as the associates and precedence keys you can put on operator declarations:

` { doc: "`(f ∘ g)` - return composition of `f` and `g`"
    associates: :right
    precedence: 88 }
(f ∘ g): compose(f,g)

Look out for other uses like :target, :suppress, :main.

Finally, you can specify metadata at a unit level. If the first item in a unit is an expression, rather than a declaration, it is treated as metadata that is applied to the whole unit.

{ :doc "This is just an example unit" }
a: 1 b: 2 c: 3

The expression DSL

Everything that can appear to the right of the colon in a declaration is an expression and defined by the expression DSL.

Primitives

First there are primitives.

...numbers...

123

-123

123.333

...double quoted strings...

"a string"

...symbols, prefixed by a colon...

:key

...which are currently very like strings, but used in circumstances where their internal structure is generally not significant (i.e. keys in a block's internal representation).

Finally, booleans (true and false) are pre-defined constants. As is (null) which is a value which renders as YAML or JSON's version of null but is not used by Eucalypt itself.

Block literals

Block literals (in braces, as defined in the block DSL) are expressions and can be the values of declarations or passed as function arguments or operands in any of the contexts below:

foo: { a: 1 b: 2 c: 3}

List literals

List literals are enclosed in square brackets and contain a comma separated sequence of expressions:

list: [1, 2, :a, "boo"]

Names

Then there are names, which refer to the surrounding context. They might refer to properties:

x: 22
y: x

...or functions:

add-one(x): 1 + x
three: add-one(2)

...or operators:

(x &&& y): [x, x, x, y]
z: "da" &&& "dum"

Calling functions

Functions can be applied by suffixing an argument list in parens, with no intervening whitespace:

f(x, y): x + y
result: f(2, 2) # no whitespace

In the special case of applying a single argument, "catenation" can be used:

add-one(x): 1 + x
result: 2 add-one

...which allows succinct expressions of pipelines of operations.

In addition, functions are curried so can be partially applied:

add(x, y): x + y
increment: add(1)
result: 2 increment

...and placeholder underscores (or expression anaphora) can be used to define simple functions without the song and dance of a function declaration:

f: if(tuesday?, (_ * 32 / 12), (99 / _))
result: f(3)

In fact, in many cases the underscores can be omitted, leading to a construct very similar to Haskell's sections only even brackets aren't necessary.

Note: Eucalypt uses its knowledge of the fixity and associativity of each operator to find "gaps" and fills them with the unwritten underscores. This is great for simple cases but worth avoiding for complicated expressions.

increment: + 1
result: 2 increment (126 /)

Both styles of function application together with partial application and sectioning can all be applied together:

result: [1, 2, 3] map(+1) filter(odd?) //=> [3]

(//=> is an assertion operator which causes a panic if the left and right hand expressions aren't found to be equal at run time, but returns that value if they are.)

Note: There are no explicit lambda expressions in Eucalypt right now. For simple cases, expression or string anaphora should do the job. For more involved cases, you should use a named function declaration. See Anaphora for more.

Operators and Identifiers

Eucalypt distinguishes two different types of identifier, normal identifiers, like x, y, α, א, ziggety-zaggety, zoom?, and operator identifiers like *, @, &&, ∧, ∘, ⊙⊙⊙, <> and so on.

It is entirely a matter of the component characters which category an identifier falls into. Normal identifiers contain letters (including non-ASCII characters), numbers, "-", "?", "$". Operator identifiers contain the usual suspects and anything identified as an operator or symbol in unicode. Neither can contain ":" or "," or brackets which are special in eucalypt.

Any sequence of characters at all can be treated as a normal identifier by surrounding them in single quotes. This is the only use of single quotes in eucalypt. This can be useful when you want to use file paths or other external identifiers as block keys for instance:

home: {
  '.bashrc': false
  '.emacs.d': false
  'notes.txt': true
}

z: home.'notes.txt'

Normal identifiers

Normal identifiers are brought into scope by declarations and can be referred to without qualification in their own block or in more nested blocks:

x: {
  z: 99
  foo: z //=> 99
  bar: {
    y: z //=> 99
  }
}

They can be accessed from within other blocks using the lookup operator:

x: {
  z: 99
}

y: x.z //=> 99

They can be overridden using generalised lookup:

z: 99
y: { z: 100 }."z is {z}" //=> "z is 100"

They can be shadowed:

z: 99
y: { z: 100 r: z //=> 100 }

But beware trying to access the outer value:

name: "foo"
x: { name: name } //=> infinite recursion

Accessing shadowed values is not yet easily possible unless you can refer to an enclosing block and use a lookup.

Prefix operators

Some operators are defined as prefix (unary) operators rather than infix (binary) operators. These bind tightly to the expression that follows.

For example, the ↑ operator is a tight-binding prefix form of head:

xs: [1, 2, 3]
first: ↑xs  //=> 1

Because it binds tightly (precedence 95), it works naturally in pipelines without parentheses:

xs: [[1, 2], [3, 4]]
result: xs map(↑)  # map head over list of lists

Other prefix operators include ! and ¬ for boolean negation, and ∸ for numeric negation.

Operator identifiers

Operator identifiers are more limited than normal identifiers.

They are brought into scope by operator declarations and available without qualification in their own block and more nested blocks:

( l -->> r): "{l} shoots arrow at {r}"

x: {
  y: 2 -->> 3 //=> "2 shoots arrow at 3"
}

...and can be shadowed:

(l !!! r): l + r

y: {
  (l !!! r): l - r
  z: 100 !!! 1 //=> 99
}

But:

• they cannot be accessed by lookup, so there is no way of forming a qualified name to access an operator
• they cannot be overridden by generalised lookup

Prelude Reference

The eucalypt prelude is a standard library of functions, operators, and constants that is automatically loaded before your code runs.

You can suppress the prelude with -Q if needed, though this leaves a very bare environment (even true, false, and if are defined in the prelude).

Categories

• Lists -- list construction, transformation, folding, sorting (64 entries)
• Blocks -- block construction, access, merging, transformation (52 entries)
• Strings -- string manipulation, regex, formatting (26 entries)
• Numbers and Arithmetic -- numeric operations and predicates (14 entries)
• Booleans and Comparison -- boolean logic and comparison operators (13 entries)
• Combinators -- function composition, application, utilities (12 entries)
• Calendar -- date and time functions (5 entries)
• Sets -- set operations (11 entries)
• Random Numbers -- random number generation, monadic random: namespace (20 entries)
• Metadata -- metadata and assertion functions (7 entries)
• IO -- environment, time, argument access, and monad utility (16 entries)

240 documented entries in total.

Lists

Basic Operations

List Construction

Transformations

Combining Lists

Splitting Lists

Folds and Scans

Predicates

Sorting

Sorting Examples

nums: [3, 1, 4, 1, 5] sort-nums          # [1, 1, 3, 4, 5]
words: ["banana", "apple", "cherry"] sort-strs  # ["apple", "banana", "cherry"]

people: [{name: "Zara" age: 30}, {name: "Alice" age: 25}]
by-name: people sort-by-str(.name)       # sorted by name
by-age: people sort-by-num(.age)         # sorted by age

Other

Blocks

Block Construction and Merging

Block Utilities

Block Alteration

Deep Find and Query

Deep Find

Searches for a key at any nesting level:

config: {
  server: { host: "localhost" port: 8080 }
  db: { host: "db.local" port: 5432 }
}

hosts: config deep-find(:host)  # ["localhost", "db.local"]
first-host: config deep-find-first(:host, "unknown")  # "localhost"

Deep Query

Queries using dot-separated patterns with wildcards:

• Bare name foo is sugar for **.foo (find at any depth)
• * matches one level
• ** matches any depth

data: {
  us: { config: { host: "us.example.com" } }
  eu: { config: { host: "eu.example.com" } }
}

# Find all hosts under any config
hosts: data deep-query("config.host")  # ["us.example.com", "eu.example.com"]

# Wildcard: any key at one level, then host
hosts: data deep-query("*.config.host")

Persistent Blocks (Experimental)

The pb: namespace provides persistent (immutable, structurally-shared) blocks backed by im::OrdMap. These offer O(log n) lookup and merge operations with structural sharing. This feature is experimental and is not included in generated documentation exports.

# Round-trip a standard block through a persistent block
p: {a: 1, b: 2} pb.from-block
v: p pb.lookup(:a, 0)           # 1
l: p pb.to-list block           # {a: 1, b: 2}

# Merge two persistent blocks (left wins on conflict)
merged: ({a: 1} pb.from-block) pb.merge({a: 99, b: 2} pb.from-block)
# pb.lookup(:a, 0) merged => 1

Strings

String Processing

Character Constants

The ch namespace provides special characters:

• ch.n -- Newline
• ch.t -- Tab
• ch.dq -- Double quote

Encoding and Hashing Examples

encoded: "hello" str.base64-encode    # "aGVsbG8="
decoded: "aGVsbG8=" str.base64-decode # "hello"
hash: "hello" str.sha256              # "2cf24dba5fb0a30e..."

Serialisation

Serialise eucalypt values to strings using a named output format. These are pure functions — no IO is required.

Supported formats for fmt: :yaml, :json, :toml, :text, :edn, :html.

Serialisation Examples

yaml-str: render({a: 1, b: 2})           # "a: 1\nb: 2\n"
json-str: render-as(:json, {a: 1, b: 2}) # "{\"a\":1,\"b\":2}"

These functions are backed by the RENDER_TO_STRING intrinsic, which traverses the evaluated heap value and serialises it using the same emitter pipeline as normal output.

Parsing

Parse a string of structured data back into eucalypt data. This is the inverse of render-as and is a pure function — no IO is required.

Supported formats for fmt: :json, :yaml, :toml, :csv, :xml, :edn, :jsonl.

:json and :yaml share the same parser.

Safety: parse-as always uses data-only mode. YAML !eu tags and other embedded-code constructs are returned as plain string values and never evaluated. It is safe to parse untrusted input (e.g. shell command output) with this function.

Parsing Examples

# Parse JSON
data: "{\"x\": 1}" parse-as(:json)
data.x  # 1

# Round-trip
original: {x: 1, y: 2}
recovered: render-as(:json, original) parse-as(:json)
recovered.x  # 1

# Pipeline style (parse-as with first arg partially applied)
{ :io r: io.shell("kubectl get configmap foo -o json") }.r.stdout
  parse-as(:json)

parse-as is backed by the PARSE_STRING intrinsic.

Numbers and Arithmetic

Arithmetic Operators

The binary arithmetic operators +, -, *, and / are polymorphic: when either operand is an n-dimensional array, the operation is performed element-wise. One operand may be a scalar number. For purely numeric operands, the operators behave as before (/ performs floor division for numbers, but element-wise float division for arrays).

Numeric Functions

Booleans and Comparison

Essentials

Error and Debug Support

Boolean Logic

Combinators

Combinators

Utilities

Calendar

Date and Time Functions

Sets

Set Operations

s: set.from-list([1, 2, 3, 2, 1])
# s contains {1, 2, 3} (duplicates removed)

Set Algebra

a: set.from-list([1, 2, 3])
b: set.from-list([2, 3, 4])
u: set.union(a, b) set.to-list       # [1, 2, 3, 4]
i: set.intersect(a, b) set.to-list   # [2, 3]
d: set.diff(a, b) set.to-list        # [1]

Random Numbers

The random namespace provides pseudo-random number generation as a state monad over a PRNG stream.

The random stream

A random stream is provided at startup as io.random, seeded from system entropy. Each run produces different values unless you supply a fixed seed with --seed:

eu --seed 42 example.eu

You can also create a deterministic stream directly:

stream: random.stream(12345)

Using random operations

Each random operation takes a stream and returns a {value, rest} block. For a single value, pass io.random:

roll: random.int(6, io.random).value + 1

For multiple values, you must propagate .rest into the next call — reusing io.random gives the same value each time. Use a { :random ... } monadic block or combinators like sequence to handle this automatically:

dice: { :random
  a: random.int(6)
  b: random.int(6)
}.[a + b + 2]

result: dice(io.random).value

Always extract .value before rendering — the .rest field is an infinite stream.

Reference

Metadata

Metadata is a powerful mechanism for attaching auxiliary information to any eucalypt expression. It is used for documentation, export control, import declarations, operator definitions, and testing assertions.

Attaching and Reading Metadata

Metadata Basics

Documentation Metadata

The backtick (`) before a declaration attaches metadata. When the value is a string, it sets the doc key:

` "Add two numbers together"
add(a, b): a + b

This is equivalent to:

` { doc: "Add two numbers together" }
add(a, b): a + b

For richer metadata, use a block:

` { doc: "Infix addition operator"
    precedence: :sum
    associates: :left }
(a + b): __ADD(a, b)

Common Metadata Keys

IO

Prelude Versioning

Runtime IO Values

IO Monad

The io namespace is a monad. Blocks tagged with :io are desugared into monadic bind chains automatically:

result: { :io
  r: io.shell("ls -la")
  _: io.check(r)
}.r.stdout

...desugars to io.bind(io.shell("ls -la"), λr. io.bind(io.check(r), λ_. io.return(r.stdout))).

IO operations require the --allow-io / -I flag at the command line.

Monad primitives

Shell execution

Default timeout is 30 seconds. Override with {timeout: N} in opts. Optional {stdin: s} pipes string s to the command's standard input.

Combinators

The combinators map, then, join, sequence, map-m, and filter-m are derived automatically via monad(). See the Monads guide for details on the derivation pattern and the IO guide for practical usage.

Other

N-Dimensional Arrays

Eucalypt provides a native n-dimensional array type (also called tensors) backed by a flat contiguous store with shape metadata. Arrays enable efficient grid and matrix operations, in particular for Advent of Code-style grid simulations where list-based approaches are too slow.

Arrays are an immutable, purely functional data structure. All mutation operations return new arrays.

Construction

The shape argument is always a list of integers, e.g. [3] for a 1D array of 3 elements or [2, 3] for a 2×3 matrix.

Access and Query

The coords argument to arr.get and arr.set is a list of integers, one per dimension, e.g. [row, col] for a 2D array.

The !! Operator

The indexing operator !! is overloaded for arrays. When the left operand is an array, !! delegates to arr.get:

my-2d-array !! [row, col]   # same as arr.get(my-2d-array, [row, col])
my-1d-array !! [idx]        # same as arr.get(my-1d-array, [idx])

For plain lists, !! retains its original list-index behaviour:

[10, 20, 30] !! 1   # => 20

Transformations

Arithmetic

Array-specific arithmetic (explicit namespace):

The standard arithmetic operators +, -, *, / are polymorphic: when either operand is an array, the operation is applied element-wise.

a: arr.from-flat([3], [1, 2, 3])
b: arr.from-flat([3], [10, 20, 30])
c: a + b          # element-wise: [11, 22, 33]
d: a * 2          # scalar broadcast: [2, 4, 6]

Note: / on arrays performs element-wise float division (not floor division as it does for plain integers).

Higher-order Operations

arr.indices returns coordinates as lists; for a 2D array of shape [rows, cols], each entry is [row, col].

arr.neighbours silently skips any out-of-bounds coordinates, so it is safe to call on border elements without special-casing.

# Double every element of a 1D array
a: arr.from-flat([3], [1, 2, 3])
b: arr.map((_ * 2), a)   # => [2, 4, 6] (same shape)

# Sum all elements
total: arr.fold((+), 0, a)   # => 6

# List all coordinates of a 2×2 array
coords: arr.from-flat([2, 2], [0, 0, 0, 0]) arr.indices
# => [[0, 0], [0, 1], [1, 0], [1, 1]]

# Neighbours of centre cell in a 3×3 grid (4-connected)
grid: arr.from-flat([3, 3], [1, 2, 3, 4, 5, 6, 7, 8, 9])
ns: arr.neighbours(grid, [1, 1], [[-1, 0], [1, 0], [0, -1], [0, 1]])
# => [2, 8, 4, 6]

Example

# 3×3 grid initialised to zero
grid: arr.zeros([3, 3])

# Set a value at row 1, col 2
grid2: grid arr.set([1, 2], 42)

# Read back the value
val: grid2 arr.get([1, 2])    # => 42
val2: grid2 !! [1, 2]         # same thing via !! operator

# Compute element-wise sum of two grids
a: arr.from-flat([2, 2], [1, 2, 3, 4])
b: arr.from-flat([2, 2], [5, 6, 7, 8])
c: a + b   # => [[6, 8], [10, 12]] (as flat list: [6, 8, 10, 12])

CLI Reference

Eucalypt is available as a command line tool, eu, which reads inputs and writes outputs.

Everything it does in between is purely functional and there is no mutable state.

It is intended to be simple to use in unix pipelines.

eu --version # shows the current eu version
eu --help # lists command line options

Command Structure

The eu command uses a subcommand structure for clarity and extensibility:

eu [GLOBAL_OPTIONS] [SUBCOMMAND] [SUBCOMMAND_OPTIONS] [FILES...]

Subcommands

• run (default) - Evaluate eucalypt code
• test - Run tests
• dump - Dump intermediate representations
• version - Show version information
• explain - Explain what would be executed
• list-targets - List targets defined in the source
• fmt - Format eucalypt source files
• lsp - Start the Language Server Protocol server

When no subcommand is specified, run is used by default, so these are equivalent:

eu file.eu
eu run file.eu

Inputs

Files / stdin

eu can read several inputs, specified by command line arguments.

Inputs specify text data from:

• files
• stdin
• internal resources (ignored for now)
• (in future) HTTPS URLs or Git refs

...of which the first two are the common case. In the simplest case, file inputs are specified by file name, stdin is specified by -.

So

eu a.yaml - b.eu

...will read input from a.yaml, stdin and b.eu. Each will be read into eucalypt's core representation and merged before output is rendered.

Input format

Inputs must be one of the formats that eucalypt supports, which at present, are:

• yaml
• json
• jsonl (JSON Lines)
• toml
• edn
• xml
• csv
• text

Of these yaml, json, toml, edn and xml return blocks; jsonl, csv and text return lists. Inputs that return lists frequently need to be named (see below) to allow them to be used.

Usually the format is inferred from file extension but it can be overridden on an input by input basis using a format@ prefix.

For instance:

eu yaml@a.txt json@- yaml@b.txt

...will read YAML from a.txt, JSON from stdin and YAML from b.txt.

Named inputs

Finally inputs can be named using a name= prefix. This alters the way that data is merged by making the contents of an input available in a block or list with the specified name, instead of at the top level.

Suppose we have two inputs:

foo: bar

x: 42

then

eu a.yaml b.eu

would generate:

foo: bar
x: 42

but

eu data=a.yaml b.eu

would generate:

data:
  foo: bar

x: 42

This can be useful for various reasons, particularly when:

• the form of the input's content is not known in advance
• the input's content is a list rather than a block

Full input syntax

The full input syntax is therefore:

[name=][format@][URL/file]

This applies at the command line and also when specifying imports in .eu files.

stdin defaulting

When no inputs are specified and eu is being used in a pipeline, it will accept input from stdin by default, making it easy to pipe JSON or YAML from other tools into eu.

For example, this takes JSON from the aws CLI and formats it as YAML to stdout.

aws s3-api list-buckets | eu

How inputs are merged

When several inputs are listed, names from earlier inputs become available to later inputs, but the content that will be rendered is that of the final input.

So for instance:

a.eu

x: 4
y: 8

b.eu

z: x + y

eu a.eu b.eu

will output

z: 12

The common use cases are:

• a final input containing logic to inspect or process data provided by previous inputs
• a final input which uses functions defined in earlier inputs to process data provided in previous inputs

If you want to render contents of earlier inputs, you need a named input to provide a name for that content which you can then use.

For instance:

eu r=a.eu b.eu -e r

will render:

x: 4
y: 8

--collect-as and --name-inputs

Occasionally it is useful to aggregate data from an arbitrary number of sources files, typically specified by shell wildcards. To refer to this data we need to introduce a name for the collection of data.

This is what the command line switch --collect-as / -c is for.

eu --collect-as inputs *.eu

...will render:

inputs:
  - x: 4
    y: 8
  - z: 12

It is common to use -e to select an item to render:

eu -c inputs *.eu -e 'inputs head'

...renders:

x: 4
y: 8

If you are likely to need to refer to inputs by name, you can add --name-inputs / -N to pass inputs as a block instead of a list:

eu --collect-as inputs --name-inputs *.eu

...renders:

inputs:
  a.eu:
    x: 4
    y: 8
  b.eu:
    z: 12

This makes it easier to invoke specific functions from named inputs although you will need single-quote name syntax to use the generated names which contain .s.

Outputs

In the current version, eu can only generate one output.

Output format

Output is rendered as YAML by default. Other formats can be specified using the -x command line option:

eu -x json # for JSON
eu -x text # for plain text

JSON is such a common case that there is a shortcut: -j.

Output targets

By default, eucalypt renders all the content of the final input to output.

There are various ways to override this. First, :target metadata can be specified in the final input to identify different parts for potential export.

To list the targets found in the specified inputs, use the list-targets subcommand.

eu list-targets file.eu

...and a particular target can be selected for render using -t.

eu -t my-target

If there is a target called "main" it will be used by default unless another target is specified.

Evaluands

In addition to inputs, an evaluand can be specified at the command line. This is a eucalypt expression which has access to all names defined in the inputs and replaces the input body or targets as the data to export.

It can be used to select content or derive values from data in the inputs:

$ aws s3api list-buckets | eu -e 'Buckets map(lookup(:CreationDate)) head'
2016-12-25T14:22:30.000Z

...or just to test out short expressions or command line features:

$ eu -e '{a: 1 b: 2 * 2}' -j
{"a": 1, "b": 4}

Passing Arguments to Programs

You can pass command-line arguments to your eucalypt program using the -- separator. Arguments after -- are available via io.args:

$ eu -e 'io.args' -- foo bar baz
---
- foo
- bar
- baz

This is useful for writing eucalypt scripts that accept parameters:

# greet.eu
name: io.args head-or("World")
greeting: "Hello, {name}!"

$ eu greet.eu -e greeting -- Alice
---
Hello, Alice!

Arguments are passed as strings. Use num to convert numeric arguments:

# sum.eu
total: io.args map(num) foldl((+), 0)

$ eu sum.eu -e total -- 1 2 3 4 5
---
15

When no arguments are passed, io.args is an empty list:

$ eu -e 'io.args nil?'
---
true

Random Seed

By default, random numbers are seeded from system entropy and produce different results on each run. Use --seed for reproducible output:

eu --seed 42 template.eu

This sets io.RANDOM_SEED and seeds the io.random stream. See Random Numbers for the full random API.

IO Monad Operations

By default, eucalypt is a pure functional language with no side effects. To enable IO monad operations — specifically shell command execution — you must pass the --allow-io / -I flag:

eu -I script.eu
eu --allow-io script.eu

Without this flag, any program that attempts to execute an IO action will fail with an error:

IO operations require the --allow-io (-I) flag

Why this flag exists

The flag is a deliberate security measure. Eucalypt files are often used as configuration or data templates, and it would be unsafe for arbitrary .eu files loaded from the filesystem or network to execute shell commands without explicit consent. The --allow-io flag is your explicit acknowledgement that the program you are running may perform shell execution.

Usage with IO targets

IO programmes typically use the :io monadic block syntax and are run with a named target:

eu -I --target main script.eu
eu -I -t main script.eu

See the IO monad design documentation for full details of the IO API.

Suppressing prelude

A standard prelude containing many functions and operators is automatically prepended to the input list.

This can be suppressed using -Q if it is not required or if you would like to provide an alternative.

Warning: Many very basic facilities -- like the definition of true and false and if -- are provided by the prelude so suppressing it leaves a very bare environment.

Debugging

eu has a variety of command line switches for dumping out internal representations or tracing execution. The dump subcommand provides access to intermediate representations:

eu dump ast file.eu          # Parse and dump syntax tree
eu dump desugared file.eu    # Dump core expression
eu dump stg file.eu          # Dump compiled STG syntax
eu list-targets file.eu      # List available targets

Use eu --help and eu <subcommand> --help for complete option lists.

Formatting Source Files

The fmt subcommand formats eucalypt source files for consistent style:

eu fmt file.eu              # Print formatted output to stdout
eu fmt --write file.eu      # Format in place
eu fmt --check file.eu      # Check formatting (exit 1 if not formatted)
eu fmt *.eu --write         # Format multiple files in place

Options

• -w, --width <WIDTH> - Line width for formatting (default: 80)
• --write - Modify files in place
• --check - Check if files are formatted (exit 1 if not)
• --reformat - Full reformatting mode (instead of conservative)
• --indent <INDENT> - Indent size in spaces (default: 2)

The formatter has two modes:

• Conservative mode (default) - Preserves original formatting choices where possible, only reformatting where necessary
• Reformat mode (--reformat) - Full reformatting that applies consistent style throughout

Language Server Protocol

The lsp subcommand starts an LSP server for use with editors that support the Language Server Protocol (e.g., VS Code, Neovim):

eu lsp

The LSP server provides:

• Syntax error diagnostics
• Formatting support (via textDocument/formatting)

Configure your editor to use eu lsp as the language server command for .eu files. A VS Code extension is available in the editors/vscode/ directory of the repository.

Version Assertions

The eu.requires function allows eucalypt source files to assert a minimum version of the eucalypt executable:

{ import: [] }  # unit-level metadata not required for eu.requires

# Assert that eu version satisfies semver constraint
_ : eu.requires(">=0.3.0")

If the running version of eu does not satisfy the constraint, an error is raised immediately. This is useful for library code that depends on features introduced in a particular version.

The eu namespace also provides build metadata:

version: eu.build.version    # e.g., "0.3.0"

Backward Compatibility

All existing command patterns continue to work unchanged:

eu file.eu                   # Still works (uses run subcommand)
eu -e "expression"           # Still works (uses run subcommand)
eu -j file.eu                # Still works (JSON output)
eu -S -Q file.eu             # Still works (statistics, no prelude)

Import Formats

Eucalypt supports importing content from other units in a variety of ways.

Imported names can be scoped to specific declarations, they may be made accessible under a specific namespace, and they may be imported from disk or direct from git repositories.

Import scopes

Imports are specified in declaration metadata and make the names in the imported unit available within the declaration that is annotated.

{ import: "config.eu" }
data: {
  # names from config are available here
  x: config-value
}

As described in Syntax Reference, declaration metadata can be applied at a unit level simply by including a metadata block as the very first thing in a eucalypt file:

{ import: "config.eu" }

# names from config are available here

x: config-value

Import syntax

Imports are specified using the key import in a declaration metadata block. The value may be a single import specification:

{ import: "dep-a.eu"}

or a list of import specifications:

{ import: ["dep-a.eu", "dep-b.eu"]}

The import specification itself can be either a simple import or a git import.

Simple imports

Simple imports are specified in exactly the same way as inputs are specified at the command line (see CLI Reference).

So you can override the format of the imported file when the file extension is misleading:

{ import: "yaml@dep.txt" }

...and provide a name under which the imported names will be available:

{ import: "cfg=config.eu" }

# names in config.eu are available by lookup in cfg:

x: cfg.x

In cases where the import format delivers a list rather than a block ("text", "csv", "jsonl", ...) a name is mandatory:

{ import: "txns=transactions.csv" }

Simple imports support exactly the same inputs as the command line, with the proviso that the stdin input ("-") will not be consumable if it has already been specified in the command line or another unit.

Git imports

Git imports allow you to import eucalypt direct from a git repository at a specified commit, combining the convenience of not having to explicitly manage a git working copy and a library path with the repeatability of a git SHA. A git import is specified as a block with the keys "git", "commit" and "import", all of which are mandatory:

{ import: { git: "https://github.com/gmorpheme/eu.aws"
            commit: "0140232cf882a922bdd67b520ed56f0cddbd0637"
            import: "aws/cloudformation.eu" } }

The git URL may be any format that the git command line expects.

commit is required and should be a SHA. It is intended to ensure the import is repeatable and cacheable.

import identifies the file within the repository to import.

Just as with simple imports, several git imports may be listed:

{ import: [{ git: ... }, { git: ... }]}

...and simple imports and git imports may be freely mixed.

YAML import features

When importing YAML files, eucalypt supports several YAML features that help reduce repetition and express data more naturally.

Anchors and aliases

YAML anchors (&name) and aliases (*name) allow you to define a value once and reference it multiple times. When eucalypt imports a YAML file with anchors and aliases, the aliased values are resolved to copies of the anchored expression.

# config.yaml
defaults: &defaults
  timeout: 30
  retries: 3

development:
  <<: *defaults
  debug: true

production:
  <<: *defaults
  debug: false

Anchors can be applied to any YAML value: scalars, lists, or mappings.

# Anchor on a scalar
name: &author "Alice"
books:
  - title: "First Book"
    author: *author
  - title: "Second Book"
    author: *author

# Anchor on a list
colours: &primary [red, green, blue]
palette:
  primary: *primary
  secondary: [yellow, cyan, magenta]

# Anchor on a mapping (block)
base: &base
  x: 1
  y: 2
ref: *base  # ref now has { x: 1, y: 2 }

Nested anchors are supported -- an anchored structure can itself contain anchored values:

outer: &outer
  inner: &inner 42
ref_outer: *outer   # { inner: 42 }
ref_inner: *inner   # 42

If you reference an undefined alias, eucalypt reports an error:

# This will fail: *undefined is not defined
value: *undefined

Merge keys

The YAML merge key (<<) allows you to merge entries from one or more mappings into another. This is useful for creating configuration variations that share a common base.

Single merge:

base: &base
  host: localhost
  port: 8080

server:
  <<: *base
  name: main
# server = { host: localhost, port: 8080, name: main }

Multiple merge:

When merging multiple mappings, later ones override earlier ones:

defaults: &defaults
  timeout: 30
  retries: 3

overrides: &overrides
  timeout: 60

config:
  <<: [*defaults, *overrides]
  name: myapp
# config = { timeout: 60, retries: 3, name: myapp }

Explicit keys override merged values:

Keys defined explicitly in the mapping (before or after the merge) always take precedence over merged values:

base: &base
  x: 1
  y: 2

derived:
  <<: *base
  y: 99
# derived = { x: 1, y: 99 }

Inline merge:

You can also merge an inline mapping directly:

config:
  <<: { timeout: 30, retries: 3 }
  name: myapp

The merge key value must be a mapping (or list of mappings). Attempting to merge a non-mapping value (e.g., <<: 42) results in an error.

Timestamps

Eucalypt automatically converts YAML timestamps to ZDT (zoned date-time) expressions. Plain scalar values matching timestamp patterns are parsed and converted; quoted strings are left as strings.

Supported formats:

Examples:

# These are converted to ZDT expressions:
created: 2023-01-15
updated: 2023-01-15T10:30:00Z
scheduled: 2023-06-01 09:00:00

# This remains a string (quoted):
date_string: "2023-01-15T10:30:00Z"

Invalid timestamps fall back to strings:

If a value looks like a timestamp but has invalid date components (e.g., month 13 or day 45), it remains a string:

invalid: 2023-13-45  # Remains string "2023-13-45"

To keep timestamps as strings:

If you need to preserve a timestamp-like value as a string rather than converting it to a ZDT, quote it:

# As ZDT:
actual_date: 2023-01-15

# As string:
date_label: "2023-01-15"

Streaming imports

For large files, eucalypt supports streaming import formats that read data lazily without loading the entire file into memory. Streaming formats produce a lazy list of records.

Streaming formats are specified using the format@path syntax:

# Stream a JSONL file
eu -e 'data take(10)' data=jsonl-stream@events.jsonl

# Stream a large CSV
eu -e 'data filter(.age > 30) count' data=csv-stream@people.csv

# Stream lines of text
eu -e 'data filter(str.matches?("ERROR"))' log=text-stream@app.log

Streaming imports can also be used via the import syntax in eucalypt source files:

{ import: "events=jsonl-stream@events.jsonl" }

recent: events take(100)

Note: Streaming imports require a name binding (e.g., data=) because they produce a list, not a block.

Note: text-stream supports reading from stdin using - as the path: eu -e 'data count' data=text-stream@-

Export Formats

Detailed export format documentation is under construction.

Eucalypt can export to the following formats:

The output format can also be inferred from the output file extension when using -o:

eu input.eu -o output.json  # infers JSON format
eu input.eu -o output.toml  # infers TOML format

Error Messages Guide

This reference is under construction. It will provide a guide to understanding eucalypt error messages with examples and solutions.

Agent Reference

Dense, example-heavy reference for AI coding agents working with Eucalypt. All content verified against source. See the guide chapters for narrative explanations.

1. Syntax Reference

1.1 Primitives

String escape sequences (c-strings only): \n newline, \t tab, \r carriage return, \\ backslash, \" quote, \{ \} literal braces, \xHH hex byte, \uHHHH unicode, \UHHHHHHHH extended unicode.

String interpolation (all string types except t-strings): embed expressions with {expr}. Literal braces via {{ and }}. Format specifiers: {value:%.2f}, {n:%06d}.

Raw strings treat backslashes literally but still support {} interpolation.

1.2 Collections

# List (commas required)
[1, 2, 3]
[]
[1, "two", :three, true]

# Block (commas optional)
{ a: 1 b: 2 c: 3 }
{ a: 1, b: 2, c: 3 }

1.3 Declarations

Top-level unit: the file itself is an implicit block without braces.

1.4 Comments

# Line comment (to end of line)
x: 42  # inline comment

1.5 Metadata Annotations

Placed between a leading backtick and the declaration:

# Documentation shorthand (string = doc metadata)
` "Adds two numbers"
add(x, y): x + y

# Structured metadata
` { doc: "Deep merge operator"
    associates: :left
    precedence: :append }
(l << r): deep-merge(l, r)

# Suppress from output
` :suppress
helper(x): x + 1

# Export target
` { target: :my-output }
output: { result: 42 }

# Mark as main (default) target
` :main
main: { result: 42 }

Unit-level metadata: if the first item in a file is an expression (not a declaration), it becomes metadata for the entire unit:

{ import: "helpers.eu" }
result: helper(42)

1.6 Function Application

# Standard call (NO whitespace before paren)
f(x, y)

# Catenation / pipeline (single argument, becomes LAST param)
x f                    # = f(x)
x f g h                # = h(g(f(x)))
[1,2,3] map(inc)       # map(inc, [1,2,3])

# Partial application (all functions are curried)
add(1)                 # returns a function that adds 1
[1,2,3] map(+ 10)     # section: adds 10 to each

# Sections (operator with gaps filled by implicit params)
(+ 1)                  # function: _ + 1
(* 2)                  # function: _ * 2
(> 3)                  # function: _ > 3
(/)                    # function: _ / _ (two params)

1.7 Lookup and Generalised Lookup

# Simple property lookup (dot, precedence 90)
block.key
config.db.host

# Generalised lookup (evaluate RHS in block scope)
{ a: 3 b: 4 }.(a + b)        # 7
{ a: 3 b: 4 }.[a, b]         # [3, 4]
{ a: 3 b: 4 }."{a} and {b}"  # "3 and 4"

Warning: . binds very tightly (precedence 90). list head.name parses as list (head.name), not (list head).name. Use parentheses: (list head).name.

1.8 Anaphora (Implicit Parameters)

# Expression anaphora
[1,2,3] map(_0 * _0)          # square: [1,4,9]
[1,2,3] filter(_ > 1)         # [2,3]

# Block anaphora (• = bullet, Option-8 on Mac)
{ x: • y: • }                 # two-param function returning block
[[1,2],[3,4]] map({ x: • y: • } uncurry)

# Pseudo-lambda via block anaphora + generalised lookup
{ x: • y: • }.(x + y)         # anonymous two-param function

# String anaphora
[1,2,3] map("item: {}")       # ["item: 1", "item: 2", "item: 3"]
"{1},{0}"                      # two-param function, reversed order

Important: anaphora cannot be nested. For complex cases, use named functions.

1.9 Imports

# Unit-level import (available everywhere in file)
{ import: "lib.eu" }

# Named import (access as namespace)
{ import: "cfg=config.yaml" }
host: cfg.host

# Multiple imports
{ import: ["helpers.eu", "cfg=config.eu"] }

# Format override
{ import: "data=yaml@records.txt" }

# Scoped import (on specific declaration)
` { import: "math.eu" }
calculations: { result: advanced-calc(10) }

# Git import
{ import: { git: "https://github.com/user/lib"
            commit: "abc123def456"
            import: "helpers.eu" } }

# Streaming imports (lazy, for large files)
{ import: "events=jsonl-stream@events.jsonl" }
{ import: "rows=csv-stream@big.csv" }
{ import: "lines=text-stream@log.txt" }

Import resolution order: relative paths are resolved by searching:

1. The directory containing the importing .eu file (source-relative)
2. The directories on the lib path (-L flags and CWD)

This means a file at lib/utils.eu that imports "helpers/misc.eu" will find lib/helpers/misc.eu without needing -L lib on the command line. This works transitively, so lib/helpers/misc.eu can in turn import "sub/detail.eu" and it will resolve as lib/helpers/sub/detail.eu.

1.10 Quoted Identifiers

Single quotes turn any character sequence into a normal identifier:

home: {
  '.bashrc': false
  'notes.txt': true
}
z: home.'notes.txt'

2. Operator Precedence Table

All values verified against src/core/metadata.rs (named_precedence) and lib/prelude.eu operator metadata.

From highest (tightest) to lowest binding: