Package-level declarations

Types

Link copied to clipboard
data class Answer(val effect: Effect<*>, val response: Any?)

An effect with the response it received.

Link copied to clipboard
data class Branch(val response: Any?, val subtree: Tree)

One response to an effect and the subtree under it.

Link copied to clipboard
class Call

An effect's stay in one participant of a Trace.

Link copied to clipboard
class Described(val className: String, val text: String) : Effect<Any?>

A stand-in, in a trace read from text, for an effect or a response the text only describes: the simple name of its class and its description. It draws and compares as the original did. It cannot be handed to a program, so a response read from text replays only when the text kept it typed: null, Unit, a Boolean, an Int, a Long, a Float, a Double or a String.

Link copied to clipboard
data class Path(val answers: List<Answer>, val end: Tree.Leaf)

One path through a Tree: the effects performed with their responses, and the leaf it ends in.

Link copied to clipboard

The responses to unfold an effect under when its response type has no finite set of values. ofEffect names them for an effect family and wins over everything else; otherwise a finite response type supplies its own values, and ofType names them for an infinite one, including a type parameter of the effect class when a property of the effect witnesses it, as a default value of the response type does. Every representative is checked against the response type.

Link copied to clipboard
class Trace(val last: String)

The operational trace of one run under one handler stack: what each layer asked the layer below it and what came back. A program is a value whose effects are answered by whichever handlers are applied to it, so the trace shows what one stack did with it on one run, not what the program could do; the latter is its Tree.

Link copied to clipboard
sealed interface Tree

The tree of a program under finite response sets. A program is a value: a tree whose nodes are the effects it performs and whose edges are the responses it may receive, with a return value at every leaf. Nothing in the value says what an effect does; the handlers applied to it decide that when it runs, and one run under one stack is a Trace. The tree is the program itself, unfolded: an effect whose response type is finite (Boolean, an enum, a sealed hierarchy of objects, Unit) under every response, an effect whose response type is infinite under the Representatives the caller names, and an effect that can have no response at all, such as a failure, as a leaf. tree builds it.

Link copied to clipboard
sealed interface Wire

What crossed one wire of a handler stack: an effect on its way down, or its response on the way up.

Functions

Link copied to clipboard
fun describe(value: Any?): String

value as text: its toString, unless that is the default identity form, in which case its class name and its properties, as a data class would print them.

Link copied to clipboard
fun <A> Program<A>.observed(layer: String, trace: Trace): Program<A>

Observe the wire between this program (or handler) and the next handler applied to it, as the participant named layer of trace. An observer over the root family Effect<*> sees every effect of every family, so the same observer fits between any two layers.

Link copied to clipboard

What a leaf says: the value returned, or the effect that ended the path.

Link copied to clipboard

The trace toText wrote. Its effects are Described stand-ins, and its responses are the values the literals keep typed, or stand-ins too.

Link copied to clipboard

Every path of the tree, in the order the branches were given.

Link copied to clipboard

The responses that opened no path of their own: at an effect, a response whose subtree has the shape of an earlier response's, the shape of a subtree being its effects by class and its leaves by outcome, with responses and effect arguments ignored. Such a response adds no effect and no outcome a reader could not reach through its sibling. The representatives of an infinite response type are well chosen when none of them is listed here.

Link copied to clipboard
fun <A> Program<A>.replay(path: Path): Program<A>

This program answered from one path of its tree, as replay of a trace: the path's answers in order, a failure the path stops at passed on unanswered, and the value the path returns checked against the program's.

fun <A> Program<A>.replay(trace: Trace): Program<A>

This program answered from a recorded run: the effects the trace's program performed, with the responses they got, in order, and nothing else handled. The program's own code computes the result from the responses, so the handlers of the recorded run are not needed, and what they did on the side, the log lines and the writes, does not happen. The first effect that differs from the recording fails, naming both, as does a program that finishes before the recording does or performs an effect the recording has no answer for. The effect the recording left unanswered, because its handler ended the run, is passed on unanswered here too, to whatever handler is applied next. A trace read from text answers with the literals the text keeps typed and fails on a response it only describes.

Link copied to clipboard
fun responses(effect: Effect<*>): List<Any?>?

Every value of the response type of effect when that type is finite: false and true, the constants of an enum, the objects of a sealed hierarchy, Unit, or no value at all for an effect declared to respond with Nothing. Null when the type is infinite, or unknown because it is a type parameter of the effect class that no property witnesses.

Link copied to clipboard

The trace as text, one wire per line, for a golden file or for Trace.parse. After a header naming the format, the last participant and the layers, an effect on its way down is layer -> Class: description and a response on its way up is layer <- literal, where a literal is null, kotlin.Unit, a Boolean, a number (a Long with an L, a Float with an f), a quoted String, or {Class} description for anything else. Backslashes, line breaks and, in a String, double quotes are escaped with a backslash, so every wire is one line.

Link copied to clipboard
fun <A> Program<A>.tree(representatives: Representatives.() -> Unit = {}): Tree

Every path through this program, as its Tree. No handler is applied: a stand-in over the root family answers every effect from its Representatives or its finite response type, an effect with no response ends the path, and the program is replayed from the start once per path, with the answers of the path so far and the next alternative at the branch point. Replaying is what makes this work for program blocks, whose continuations cannot be resumed twice, and it demands that the program be a function of its answers: a replay that meets a different effect than the one recorded at the same position fails, naming both. The program must also finish under every answer.