Skip to content
eucalypt
v0.15.0

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

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.

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

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

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 (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 (still visible to importers)
  • export: :internal – hide from output AND importers (unit-private)
  • target – mark as an export target
  • import – import other files
  • associates / precedence – operator fixity (see Operators for details)

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.

The //= operator tests equality and returns a boolean, emitting a diagnostic to stderr on failure:

result: 2 + 2 //= 4 # returns true; on failure, returns false and prints to stderr

The //=> operator asserts equality and panics on failure, also storing the assertion as metadata:

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

The //! operator tests that a value is true, returning a boolean and emitting a diagnostic to stderr on failure:

result: (2 > 1) //! # returns true; on failure, returns false and prints to stderr

Use ▶ (U+25B6) to print any value to stderr and return it transparently:

x + ▶y # debug y inline, return y unchanged
data map(f) ▶head # debug head in a pipeline

For labelled output or pipeline use, prefer dbg:

value dbg{} # prints: ▶ <repr>
value dbg{label: "here"} # prints: ▶ here: <repr>

Both ▶ and dbg return the value unchanged, so they can be inserted anywhere without affecting the result.

▶ is intentionally prominent — the Unicode triangle is hard to overlook in a code review.

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

Terminal window
eu -e '[1, 2, 2, 3, 3, 3] set.of set.to-list'
- 1
- 2
- 3

Duplicates are removed and elements are sorted. set.from-list is an alias of set.of — the same function, pairing with set.to-list.

The empty set is written as ∅:

Terminal window
eu -e '∅ set.to-list'
[]
Terminal window
eu -e '[1, 2, 3] set.from-list set.contains?(2)'
true
Terminal window
eu -e '[1, 2, 3] set.from-list set.size'
3
Terminal window
eu -e '∅ set.empty?'
true
Terminal window
eu -e '∅ set.add(1) set.add(2) set.add(1) set.to-list'
- 1
- 2
Terminal window
eu -e '[1, 2, 3] set.from-list set.remove(2) set.to-list'
- 1
- 3

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 recursively searches a nested block structure for all values associated with a given key name:

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

Return just the first match, or a default:

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

Return the key paths to each match:

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

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

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

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

A dotted path matches a specific path:

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

* matches exactly one level:

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

** matches any depth:

Terminal window
eu -e 'deep-query("config.**.port", { config: { port: 9090 nested: { deep: { port: 3000 } } } })'
- 9090
- 3000
  • deep-query-first(pattern, default, block) – first match or default
  • deep-query-paths(pattern, block) – key paths of matches

Test the type of a value:

Terminal window
eu -e '{ a: 1 } block?'
true
Terminal window
eu -e '[1, 2] list?'
true

Sort with a custom comparison:

Terminal window
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 numbers in ascending order:

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

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 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
Code Description Example
%d, %i Signed decimal integer {42:%d} → 42
%u Unsigned decimal integer {42:%u} → 42
%o Octal {255:%o} → 377
%x, %X Hexadecimal (lower/upper) {255:%x} → ff
%f, %F Decimal notation {3.14:%.1f} → 3.1
%e, %E Scientific notation {1000:%e} → 1e3
%g, %G Auto (decimal or scientific) {0.001:%g} → 0.001
%s String {:hello:%s} → hello
  • %- — 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.

Assert a minimum version of eu:

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

Access build metadata:

info: {
version: eu.build.version
prelude: eu.prelude.version
}
  • 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