Class Writer<I, O>

Output tokens

A Writer writes tokens to an Output writer. Output tokens are modeled as primitive numbers, commonly representing Unicode code points, or raw octets. Each Writer implementation specifies the semantic type of output tokens it produces.

Writer states

A Writer is always in one of three states: cont_​inue, _done, or error. The cont state indicates that pull is ready to produce Output; the done state indicates that writing terminated successfully, and that bind will return the written result; the error state indicates that writing terminated in failure, and that trap will return the write error. Writer subclasses default to the cont state.

Feeding input

The feed method returns a Writer that represents the continuation of how to write the given input object to subsequent Output writers. feed can be used to specify an initial object to write, or to change the object to be written.

Pulling output

The pull method incrementally writes as much Output as it can, before returning another Writer that represents the continuation of how to write additional Output. The Output passed to pull is only guaranteed to be valid for the duration of the method call; references to the provided Output instance must not be stored.

Writer results

A Writer produces a written result of type O, obtained via the bind method. bind is only guaranteed to return a result when in the done state; though bind may optionally make available partial results in other states. A failed Writer provides a write error via the trap method. trap is only guaranteed to return an error when in the error state.

Continuations

A Writer instance represents a continuation of how to write remaining Output. Rather than writing a complete output in one go, a Writer takes an Output chunk and returns another Writer instance that knows how to write subsequent Output chunks. This enables non-blocking, incremental writing that can be interrupted whenever an Output writer runs out of space. A Writer terminates by returning a continuation in either the done state, or the error state. Writer.done returns a Writer in the done state. Writer.error returns a Writer in the error state.

Forking

The fork method passes an out-of-band condition to a Writer, yielding a Writer continuation whose behavior may be altered by the given condition. For example, a console Writer might support a fork condition that changes the color and style of printed text. The types of conditions accepted by fork, and their intended semantics, are implementation defined.