Done

class Done<out A>(val value: A) : Program<A> (source)

A finished program holding its final value; it performs no effects.

Constructors

Link copied to clipboard
constructor(value: A)

Properties

Link copied to clipboard
val value: A

Functions

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

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

Link copied to clipboard
fun <A, B> Program<A>.flatMap(f: (A) -> Program<B>): Program<B>

Sequence f after this program. Evaluation timing follows the receiver: on a Program.Done value, f runs immediately at construction; on a suspended or deferred program it is queued and runs during interpretation.

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
inline fun <E : Effect<*>, A> Program<A>.handle(noinline rule: suspend ProgramScope.(E) -> Any?): Program<A>

Interpret with auto-resume: the block's return value is the effect's response. For an effect that returns Unit, do the work; for one that returns a value, return it. The block may bind other programs, which run in place of the effect as in a program block, so a rule that translates its effect into I/O binds a performIO { }. The block is a one-shot coroutine: under a multi-shot handler such as collectAll, a block that binds the choice fails when resumed a second time, while one that returns without suspending is fine.

Link copied to clipboard
inline fun <E : Effect<*>, S, A> Program<A>.handleS(initialState: S, noinline rule: suspend ProgramScope.(S, E) -> Pair<S, Any?>): Program<A>

Stateful handle: the block receives the current state and returns newState to response. Mind the pair order when the state and the response share a type — response to newState is equally well-typed and silently swaps the two. The state is threaded by value, so each interpretation starts from initialState and shares nothing with another; a rule that mutates the initial state in place instead of returning a new one shares it between every interpretation of the program.

Link copied to clipboard
inline fun <E : Effect<*>, A> Program<A>.intercept(noinline rule: suspend ProgramScope.(effect: E, proceed: suspend ProgramScope.() -> Any?) -> Any?): Program<A>

Middleware: observe an effect without consuming it. proceed() re-emits the effect to the handler downstream and returns its response, so the rule decides where the effect executes and may inspect, rewrite or replace the result; a rule that answers without calling proceed() consumes the effect. Effects the rule performs itself are seen only by the handlers applied after this one, so a middleware that logs needs the log handler downstream of it.

Link copied to clipboard
inline fun <E : Effect<*>, A> Program<A>.interpret(noinline rule: (E, (Any?) -> Program<A>) -> Program<A>): Program<A>

Handle and remove every effect of family E. rule receives the effect and a resume continuation: resume(response) is the rest of the program with response as the effect's result, as a program that nothing has run yet. Return it to continue, transform it with flatMap or map or bind it in a program { } block to work on the rest's result, call it more than once to resume the same continuation more than once, or leave it uncalled to cut the program short. Every form runs on a constant stack. Applied lazily, when the program is run.

inline fun <E : Effect<*>, A, B> Program<A>.interpret(noinline transformDone: (A) -> Program<B>, noinline rule: (E, (Any?) -> Program<B>) -> Program<B>): Program<B>

Handle and remove every effect of family E, mapping the final value with transformDone. rule receives the effect and a resume continuation: resume(response) is the rest of the program with response as the effect's result, as a program that nothing has run yet. Return it to continue, transform it with flatMap or map or bind it in a program { } block to work on the rest's result, call it more than once to resume the same continuation more than once, or leave it uncalled to cut the program short. Every form runs on a constant stack. Applied lazily, when the program is run.

Link copied to clipboard
inline fun <E : Effect<*>, S, A> Program<A>.interpretS(initialState: S, noinline rule: (S, E, (S, Any?) -> Program<A>) -> Program<A>): Program<A>

Handle and remove every effect of family E, threading state S from initialState; resume takes the next state and the response, and is the rest of the program as in interpret, with the same forms and the same lazy application.

inline fun <E : Effect<*>, S, A, B> Program<A>.interpretS(initialState: S, noinline transformDone: (S, A) -> Program<B>, noinline rule: (S, E, (S, Any?) -> Program<B>) -> Program<B>): Program<B>

Handle and remove every effect of family E, threading state S from initialState through every step; transformDone sees the final state and value. resume takes the next state and the response, and is the rest of the program as in interpret, with the same forms and the same lazy application.

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 <A, B> Program<A>.map(f: (A) -> B): Program<B>

Transform this program's final value with f. Like flatMap, f runs immediately on a Program.Done value and during interpretation otherwise.

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> 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 <A> Program<A>.run(): Result<A>

Run a fully handled program, capturing the outcome as a Result: the final value on success, or an IllegalStateException naming the unhandled effect on failure.

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

Extract the final value of a fully handled program, or throw naming the unhandled effect.

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
open override fun toString(): String
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.