Skip to content
eucalypt
v0.15.0

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
Terminal window
eu [GLOBAL_OPTIONS] [SUBCOMMAND] [SUBCOMMAND_OPTIONS] [FILES...]

When no subcommand is given, run is assumed:

Terminal window
eu file.eu # same as: eu run file.eu
Command Description
run Evaluate and render (default)
test Run embedded tests
dump Dump intermediate representations
version Show version information
explain Show what would be executed
list-targets List export targets
fmt Format source files
lsp Start the Language Server Protocol server
check Check type annotations without evaluating
doc Extract documentation from source

Specify one or more files to process:

Terminal window
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.

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

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

Override the assumed format with a format@ prefix:

Terminal window
eu yaml@data.txt json@-

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

Terminal window
eu config=settings.yaml app.eu

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

port: config.port

Gather multiple files into a named collection:

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

Add -N to key by filename:

Terminal window
eu -c data -N *.json

Output defaults to YAML. Common options:

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

Write to a file (format inferred from extension):

Terminal window
eu data.eu -o output.json

The -e flag specifies an expression to evaluate:

Terminal window
eu -e '2 + 2'
4

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

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

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

Use -e for quick data exploration:

Terminal window
# 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'

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:

Terminal window
eu list-targets multi-output.eu

Select a target:

Terminal window
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.

Arguments after -- are available via io.args:

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

Use in scripts:

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

Arguments are strings. Use num to convert:

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

Access environment variables through io.env:

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

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

Terminal window
eu --seed 42 template.eu

Programs that use the IO monad (io.shell, io.exec, and friends) must be run with -I/--allow-io, or evaluation fails with a permission error before any shell command runs:

Terminal window
eu -I deploy.eu
eu --allow-io deploy.eu

This is a safety gate — code that shells out is not allowed to run by accident. See IO and Shell Commands for the full IO monad guide.

Format eucalypt source files:

Terminal window
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)
Terminal window
eu dump ast file.eu # syntax tree
eu dump desugared file.eu # core expression
eu dump stg file.eu # compiled STG
Terminal window
eu explain file.eu # show what would be executed
Terminal window
eu -S file.eu # print metrics to stderr

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

Terminal window
eu -Q file.eu

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

Ensure a minimum eu version in source files:

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

Check the current version:

Terminal window
eu version

Start a Language Server Protocol server for editor integration:

Terminal window
eu lsp

Provides syntax error diagnostics and formatting support.

  • 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