Continuation of how to write subsequent [[Output]] tokens to a stream.
Writer enables efficient, interruptible writing of network protocols and
data formats, without intermediate buffering.
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.
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.
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.
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.
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.
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.
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.
Incrementally writes as much output as possible, and returns another
Writer that represents the continuation of how to write additional
Output. If output enters the done state, pullmust return a
terminated Writer, i.e. a Writer in the done state, or in the
error state. The given output is only guaranteed to be valid for the
duration of the method call; references to output must not be stored.
Continuation of how to write subsequent [[Output]] tokens to a stream.
Writerenables efficient, interruptible writing of network protocols and data formats, without intermediate buffering.Output tokens
A
Writerwrites tokens to anOutputwriter. Output tokens are modeled as primitive numbers, commonly representing Unicode code points, or raw octets. EachWriterimplementation specifies the semantic type of output tokens it produces.Writer states
A
Writeris always in one of three states: _cont_​inue, done, or error. The cont state indicates that [[pull]] is ready to produceOutput; 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.Writersubclasses default to the cont state.Feeding input
The [[feed]] method returns a
Writerthat represents the continuation of how to write the given input object to subsequentOutputwriters.feedcan 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
Outputas it can, before returning anotherWriterthat represents the continuation of how to write additionalOutput. TheOutputpassed topullis only guaranteed to be valid for the duration of the method call; references to the providedOutputinstance must not be stored.Writer results
A
Writerproduces a written result of typeO, obtained via the [[bind]] method.bindis only guaranteed to return a result when in the done state; thoughbindmay optionally make available partial results in other states. A failedWriterprovides a write error via the [[trap]] method.trapis only guaranteed to return an error when in the error state.Continuations
A
Writerinstance represents a continuation of how to write remainingOutput. Rather than writing a complete output in one go, aWritertakes anOutputchunk and returns anotherWriterinstance that knows how to write subsequentOutputchunks. This enables non-blocking, incremental writing that can be interrupted whenever anOutputwriter runs out of space. AWriterterminates by returning a continuation in either the done state, or the error state. [[Writer.done]] returns aWriterin the done state. [[Writer.error]] returns aWriterin the error state.Forking
The [[fork]] method passes an out-of-band condition to a
Writer, yielding aWritercontinuation whose behavior may be altered by the given condition. For example, a consoleWritermight support aforkcondition that changes the color and style of printed text. The types of conditions accepted byfork, and their intended semantics, are implementation defined.