Package-level declarations

Types

Link copied to clipboard
sealed interface Emit<out R> : Effect<R>

Generator output: yieldValue performs a Yield, and the generator handler reifies the continuation as data. The program becomes a Generator value: Generator.Finished with the result, or Generator.Yielded holding the value and the rest of the program as a callable continuation. The driver decides when, and whether, to resume; in between, the suspended program is just data:

Link copied to clipboard
sealed interface Failure<out R> : Effect<R>

Failure as an effect: raise performs a Raise, attempt materializes the outcome as a Result, and recover replaces the failed program with a fallback. The names follow Arrow's for the same operations.

Link copied to clipboard
sealed class Generator<out T, out A>

One step of a generator run by generator: either Finished or Yielded.

Link copied to clipboard
sealed interface IO<out R> : Effect<R>

Real, possibly asynchronous, I/O. A handler that needs it translates its effects into performIO binds, and one suspend runner at the edge, io or on the JVM ioBlocking(), runs them all:

Link copied to clipboard
sealed interface NonDet<out R> : Effect<R>

Nondeterminism: multi-shot continuations. choose suspends on a Choose effect, and the collectAll handler resumes the same captured continuation once per option and concatenates the results. Resuming a continuation more than once is impossible with one-shot suspend coroutines; it works here because the continuation is an immutable value that can be replayed. guard prunes a branch, orElse is a binary choice, and msplit, once and ifte give committed choice: the first answer with the rest of the search as a program, the first answer only, and a soft cut.

Link copied to clipboard
sealed interface Reader<out R> : Effect<R>

A read-only environment: ask reads it, runReader supplies it, local overrides it for one sub-program.

Link copied to clipboard
sealed interface State<out R> : Effect<R>

A single mutable cell: read with getState, written with putState and modifyState, handled by runState or runStateWithFinal, and scoped by transactional.

Functions

Link copied to clipboard
fun <E> ask(): Program<E>

Read the environment. The environment type is erased, so this is unchecked: E must be the type the nearest runReader (or local) supplies.

Link copied to clipboard

Handle Failure as a Result: success with the final value, or failure carrying the Failure.Raise reason, in which case the rest of the program is abandoned.

Link copied to clipboard
fun <T> choose(options: List<T>): Program<T>

Branch on every one of options. The continuation is resumed once per option, so do not bind a choice directly inside a program { } block: its continuation is single-shot. Build the branch with flatMap, or a fresh block inside the flatMap.

Link copied to clipboard

Run every branch to completion and collect all results in order.

Link copied to clipboard

Run this program as a generator: every Emit.Yield pauses it as a Generator.Yielded holding the rest of the program, and completion gives Generator.Finished. The yielded type is erased, so one generator() should see one yielded type T.

Link copied to clipboard
fun <S> getState(): Program<S>

Read the current state. Unchecked: S must be the type the handler holds.

Link copied to clipboard
fun guard(condition: Boolean): Program<Unit>

Prune this branch unless condition holds.

Link copied to clipboard
fun <A, B> ifte(condition: Program<A>, then: (A) -> Program<B>, otherwise: Program<B>): Program<B>

Soft cut: if condition has any answer, run then over every one of its answers; run otherwise only when it has none.

Link copied to clipboard
suspend fun <A> Program<A>.io(): A

Terminal suspend runner, available on every target: runs every IO thunk and returns the program's final value. Call it from a coroutine, after all other handlers, so that only IO effects remain; any other effect left fails naming itself. Thunk resumptions re-enter through the calling context's ContinuationInterceptor, so under a coroutine dispatcher interpretation stays on that dispatcher; in an interceptor-free context (a plain suspend main) the first thunk that resumes on another thread moves the rest of interpretation there, which is what ioBlocking() avoids on the JVM.

Link copied to clipboard
fun <A> Program<A>.ioBlocking(): A

JVM-only blocking edge runner for interceptor-free contexts (a plain main, a thread you own): runs every IO thunk and returns the final value, blocking the caller while a thunk is suspended. Every interpretation step stays on the calling thread; a thunk may hop threads internally, but its result is handed back before interpretation continues, so handler state needs no synchronization. Apply it after all other handlers, so that only IO effects remain; any other effect left fails naming itself.

Link copied to clipboard
fun <E, A> Program<A>.local(transform: (E) -> E): Program<A>

Run this sub-program with the environment transformed; the override ends with it.

Link copied to clipboard
fun <S> modifyState(f: (S) -> S): Program<Unit>

Replace the current state with f applied to it: a getState followed by a putState.

Link copied to clipboard

Split the search: null if it has no answers, otherwise the first answer paired with the rest of the search as a replayable program. The rest is built in O(1): the first answer's own rest, then one choice over the options not yet tried — each of those is resumed only if the rest is run and reaches it. Splitting a rest again nests one more msplit interpreter around the search, so enumerating by repeated splits costs stack and time proportional to the number of prior splits — a bound set by handler nesting, not by the number of options.

Link copied to clipboard
fun <A> once(search: Program<A>): Program<A>

Committed choice: the first answer only; the rest of the search is never explored.

Link copied to clipboard
fun <A> orElse(first: Program<A>, second: Program<A>): Program<A>

Binary choice: the answers of first, then those of second.

Link copied to clipboard
fun <R> performIO(block: suspend () -> R): Program<R>

A program that runs block when interpreted by io and produces its result.

Link copied to clipboard
fun <S> putState(value: S): Program<Unit>

Replace the current state with value.

Link copied to clipboard
fun raise(reason: String): Program<Nothing>

Fail with reason: performs Failure.Raise.

Link copied to clipboard
fun <A> Program<A>.recover(fallback: (String) -> Program<A>): Program<A>

Recover from a failure: on Failure.Raise, the rest of the failed program is abandoned (there is nothing to resume into) and fallback replaces it. A failure raised inside fallback is not caught here — it propagates to the next outer recover or attempt.

Link copied to clipboard
fun <E, A> Program<A>.runReader(env: E): Program<A>

Answer every Reader.Ask with env. A handler stack carries one environment type: this handler consumes every Ask above it, whatever type it was meant for.

Link copied to clipboard
fun <S, A> Program<A>.runState(initial: S): Program<A>

Handle every State operation with a state seeded from initial.

Link copied to clipboard
fun <S, A> Program<A>.runStateWithFinal(initial: S): Program<Pair<A, S>>

Like runState, but also returns the final state alongside the result.

Link copied to clipboard

Run this program as a transaction: its State effects hit a local copy of the state, seeded by reading the downstream handler, and the final local state is committed downstream only if the program completes. If it fails part-way (e.g. a Failure.Raise handled outside), the commit is part of the abandoned continuation and never runs — the downstream state stays untouched. Built from flatMap alone, so it is safe under a multi-shot handler such as collectAll: each branch reads, runs and commits independently.

Link copied to clipboard
fun <T> yieldValue(value: T): Program<Unit>

Yield value to the driver of the enclosing generator and pause until resumed.