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

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

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'

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

Eucalypt