Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Writer<I, O>

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.

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.

Type parameters

  • I

  • O

Hierarchy

Index

Methods

andThen

asDone

  • Casts a done Writer to a different input type. A Writer in the done state can have any input type.

    throws

    Error if this Writer is not in the done state.

    Type parameters

    • I2

    Returns Writer<I2, O>

asError

  • asError<I2, O2>(): Writer<I2, O2>
  • Casts an errored Writer to different input and output types. A Writer in the error state can have any input type, and any output type.

    throws

    Error if this Writer is not in the error state.

    Type parameters

    • I2

    • O2

    Returns Writer<I2, O2>

bind

  • bind(): O

feed

  • feed(input: I): Writer<I, O>
  • Returns a Writer that represents the continuation of how to write the given input object.

    throws

    Error if this Writer does not know how to write the given input object.

    Parameters

    • input: I

    Returns Writer<I, O>

fork

  • fork(condition: unknown): Writer<I, O>

isCont

  • isCont(): boolean

isDone

  • isDone(): boolean

isError

  • isError(): boolean

Abstract pull

  • 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, pull must 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.

    Parameters

    Returns Writer<I, O>

trap

  • trap(): Error

Static done

  • done<I, O>(): Writer<I, O>
  • done<I, O>(output: O): Writer<I, O>

Static error

  • error<I, O>(error: Error): Writer<I, O>