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?
Section titled “What is a monad in eucalypt?”A monad is just two primitives, which are conventionally grouped in a namespace.
| Primitive | Role |
|---|---|
return(v) |
Wrap a pure value as a monadic action |
bind(action, f) |
Run an action, pass its result to f, return a new action |
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
Section titled “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 (pseudocode — λ is not real eucalypt syntax;
eucalypt has no lambda expressions):
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
Section titled “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
Section titled “Block metadata forms”Several syntax forms are available for monadic blocks:
| Form | Syntax | Monad source |
|---|---|---|
| 1 | { :name decls }.expr |
Namespace name in scope |
| 2 | { { monad: name } decls }.expr |
Namespace name in scope |
| 3 | { { :monad namespace: name } decls }.expr |
Namespace name in scope |
| 4 | { { :monad bind: f return: r } decls }.expr |
Explicit f/r functions |
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
Section titled “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)Restrictions: monad brackets cannot be empty (at least one declaration is required), and cannot contain block metadata — the monad tag goes on the outer block or in the bracket pair definition.
See the syntax reference for full details on bracket pair definitions.
Monadic blocks and generalised lookup
Section titled “Monadic blocks and generalised lookup”A monadic block can appear as the RHS of a generalised lookup, inheriting bindings from the LHS:
{ x: 1, y: 2 }.{ :let z: x + y }# z sees x and y from the LHS block# implicit return: { z: 3 }In lookup position, the monadic block always uses implicit return.
Any . after it is a separate lookup on the result — not a return
expression:
{ x: 1 }.{ :let y: x + 10 }.y # => 11 (simple lookup on result){ x: 1 }.{ :let y: x + 10 }.(y) # => 11 (gen lookup on result)This follows from left-associativity: A.B.C is always (A.B).C.
To use an explicit return with a monadic block in lookup position, wrap in parentheses:
{ x: 1 }.(({ :let y: x + 10 }.(y + 100))) # => 111The monad() utility
Section titled “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:
| Combinator | Description |
|---|---|
bind(action, f) |
Passed through from m.bind |
return(v) |
Passed through from m.return |
map(f, action) |
Apply pure function f to the result of an action (fmap) |
then(b, a) |
Sequence two actions, discarding the result of the first. Pipeline: a m.then(b) |
join(mm) |
Flatten a nested monadic value |
sequence(ms) |
Run a list of actions in order, collecting results |
map-m(f, xs) |
Apply f to each element of xs, then sequence |
filter-m(p, xs) |
Monadic filter: keep elements where p returns a truthy action |
Building a monadic namespace
Section titled “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
Section titled “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
Section titled “Primitives”io.return(v) # wrap a pure value; no side effectsio.bind(action, f) # run action, pass result to fPractical example
Section titled “Practical example”result: { :io r: io.shell("git rev-parse HEAD") _: io.check(r)}.(r.stdout)Extending the IO monad
Section titled “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
Section titled “IO combinators reference”| Function | Description |
|---|---|
io.return(a) |
Wrap a pure value in the IO monad |
io.bind(action, f) |
Sequence two IO actions |
io.map(f, action) |
Apply pure function f to the result of an IO action |
io.check(result) |
Fail if exit-code is non-zero; otherwise return result |
See IO and Shell Commands for practical usage and the IO reference for the full API.
The random state monad
Section titled “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
Section titled “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 + 1But 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 + 2If 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
Section titled “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 actionstwo-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 sizesdice: 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
Section titled “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 42How the state monad works
Section titled “How the state monad works”Under the hood, random.return and random.bind are:
# return: wrap a pure value as a do-nothing actionrandom-ret(v, stream): { value: v, rest: stream }
# bind: run m, pass result to f, run f's action with remaining streamrandom-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
Section titled “Random combinators reference”| Function | Description |
|---|---|
random.bind(m, f) |
State monad bind |
random.return(v) |
State monad return |
random.run(action, stream) |
Run action on stream; returns value/rest block |
random.eval(action, stream) |
Run action, return only the value |
random.exec(action, stream) |
Deprecated — use random.run(action, stream).rest. Run action, return only the remaining stream |
random.float |
Action: random float in [0,1) |
random.int(n) |
Action: random integer in [0,n) |
random.choice(list) |
Action: random element from list |
random.shuffle(list) |
Action: shuffled copy of list |
random.sample(n, list) |
Action: n elements sampled without replacement |
Derived combinators (map, then, join, sequence, map-m,
filter-m) are also available — see
Random Numbers reference.
The combined effect monad (do)
Section titled “The combined effect monad (do)”The io, state and random monads each solve one problem in
isolation, but a realistic pipeline often needs all three at once — a
stateful, seeded computation that also runs shell commands. Threading a
(state, seed) context by hand through every IO step is exactly the
verbose plumbing the monads were meant to remove.
The do monad (from lib/do.eu) combines them. It threads a
{ state, seed } context alongside IO, so one { :do ... } block can
use every capability as a native do.* action. Import it with:
{ import: "do.eu" }A do action
Section titled “A do action”A do action is a function from a context to an IO action producing a
{ value, ctx } pair, where ctx is { state: <block>, seed: <stream> }.
IO carries the context on its value channel, so io.bind handles the
delicate effect sequencing and do only threads the context on top. It
is a small, fixed state-and-seed layer over IO — not a general
transformer stack.
The only new code is bind/return plus three lift functions; every
effect stays in io/state/random, and all derived combinators
(map, then, and-then, join, sequence, map-m, filter-m)
come from monad(do).
Worked example
Section titled “Worked example”{ import: "do.eu" }
gather: { :do files: do.shell("ls") # io capability pick: do.choice(files.stdout lines) # random capability _: do.modify(:seen, (+ 1)) # state capability}.(pick)
` :mainmain: do.eval(gather, { state: { seen: 0 }, seed: random.stream(42) })One block, one monad, all three capabilities threaded automatically —
no hand-rolled (state, seed) plumbing and no mixed block metadata.
Running a do pipeline
Section titled “Running a do pipeline”A do block evaluates to an action; run it with a runner and an initial
context:
| Runner | Result |
|---|---|
do.run(action, ctx0) |
IO({value, ctx}) — value and final context |
do.eval(action, ctx0) |
IO(value) — value only (the usual entry point) |
The niche “final context only” result is do.run projected with .ctx.
Capability surface
Section titled “Capability surface”Each member lifts an existing io/state/random action into the
do monad:
| Member | Delegates to |
|---|---|
do.shell(cmd) / do.shell-with(opts, cmd) |
io.shell / io.shell-with |
do.exec(args) / do.exec-with(opts, args) |
io.exec / io.exec-with |
do.get / do.put(k, v) / do.modify(k, f) / do.query(f) |
state.* |
do.float / do.int(n) / do.choice(xs) |
random.* |
do.pure(v) |
do.return — a pure value, no effect |
do.st(action) |
lift any state action (terse) |
do.rnd(action) |
lift any random action (terse) |
do.lift-io(action) |
lift any IO action |
State lens operators inside do
Section titled “State lens operators inside do”The state monad’s lens operators =! (set) and %! (modify) produce
state actions, so they work inside a do block through the terse lift —
no new operators:
{ :do _: do.st(:count =! 0) _: do.st(:total %! (+ 1))}:let and :for compose by nesting
Section titled “:let and :for compose by nesting”A do block never carries foreign block metadata. For a pure
intermediate value use n: do.pure(expr); for pure comprehension embed
an ordinary { :for ... } block as a sub-expression; for effectful
traversal use the derived do.map-m(f, xs) / do.sequence(actions).
The list monad (list comprehensions)
Section titled “The list monad (list comprehensions)”The for namespace is a list monad — it turns { :for ... } blocks
into list comprehensions. Each binding draws elements from a list,
and subsequent bindings can depend on earlier ones. The result is a
flat list of all the combinations.
Mapping
Section titled “Mapping”The simplest use — apply an expression to each element of a list:
{ :for x: [1, 2, 3] }.(x * 2) # => [2, 4, 6]This is equivalent to [1, 2, 3] map(* 2) but the monadic block
form scales better when the transformation involves multiple steps.
Cartesian products
Section titled “Cartesian products”Multiple bindings produce all combinations:
{ :for x: [1, 2], y: [10, 20] }.(x + y)# => [11, 21, 12, 22]Dependent bindings
Section titled “Dependent bindings”Later bindings can depend on earlier ones:
{ :for x: [1, 2, 3], y: [x, x * 10] }.(y)# => [1, 10, 2, 20, 3, 30]Filtering
Section titled “Filtering”Bind to a filtered singleton list — [x] filter(pred?) returns
[x] when the predicate holds (continue) or [] when it doesn’t
(eliminate that branch):
{ :for x: [1, 2, 3, 4, 5], _: [x] filter(> 3) }.(x)# => [4, 5]Filter and rebind in one step:
{ :for x: [1, "two", 3], n: [x] filter(number?) }.(n * 10)# => [10, 30]Implicit return
Section titled “Implicit return”Without an explicit return expression, the block synthesises a list of blocks from the non-underscore bindings:
{ :for x: [:a, :b], y: [1, 2] }# => [{x: :a, y: 1}, {x: :a, y: 2}, {x: :b, y: 1}, {x: :b, y: 2}]How it works
Section titled “How it works”The list monad’s bind is mapcat (flatMap) and return wraps a
value in a singleton list:
for.bind(m, f): m mapcat(f)for.return(v): [v]for.sequence produces cartesian products of lists:
for.sequence[[1, 2], [3, 4]]# => [[1, 3], [1, 4], [2, 3], [2, 4]]Writing your own monad
Section titled “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:
` :suppressid-bind(m, f): f(m)` :suppressid-return(a): a` :suppressid-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:
` :suppressmaybe-return(v): v
` :suppressmaybe-bind(m, f): if(m = null, null, f(m))
` :suppressmaybe: 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 nullresult: maybe.bind(safe-head([]), inc) # => null (list was empty)ok: maybe.bind(safe-head([42]), inc) # => 43Type checking in monadic blocks
Section titled “Type checking in monadic blocks”eu check understands monadic blocks. When a namespace has a known
element type (e.g. io uses IO(a), for uses [a]), the checker
infers the types of bound variables automatically and warns if a binding
RHS has the wrong type.
eu check file.eu # reports type warnings in monadic blockseu check file.eu --strict # treats type warnings as errorsSee Type Checking — Monadic block binding types for examples and a full explanation.
Key concepts
Section titled “Key concepts”monad(m)takes{bind, return}and returns a block withbind,return, and six derived combinators- Use catenation (juxtaposition) to merge derived and specialised
operations — NOT
<< - Monadic blocks (
{ :io ... },{ :name ... }) desugar into nestedbindcalls — names are bound sequentially, not declaratively - The
randomnamespace is a state monad — actions are functions of a stream,bindthreads the stream automatically - When running random actions, always extract
.valuebefore rendering; the.restfield is an infinite stream - The
statenamespace (fromlib/state.eu) is a state monad over blocks — see The State Monad for details - The
fornamespace is a list monad —{ :for ... }blocks are list comprehensions with filtering via[x] filter(pred?) - The
letnamespace is the identity monad —{ :let ... }blocks give sequential bindings without block self-reference - The
donamespace (fromlib/do.eu) is the combined effect monad —{ :do ... }blocks thread a{ state, seed }context over IO soio,stateandrandomcapabilities compose in one block