Class Output<T>Abstract

Non-blocking token stream writer. Output enables incremental, interruptible writing of network protocols and data formats.

Output tokens

Output tokens are modeled as primitive numbers, commonly representing Unicode code points, or raw octets; each Output implementation specifies the semantic type of its tokens.

Output states

An Output writer is always in one of three states: _cont_​inue, full, or done. The cont state indicates that the stream is ready to write a single token; the full state indicates that the stream is unable to write additional tokens at this time, but that the stream may logically resume at some point in the future; and the done state indicates that the stream has terminated, and that [[bind]] will return the output result. [[isCont]] returns true when in the cont state; [[isFull]] returns true when in the full state; and [[isDone]] returns true when in the done state.

Output results

An Output writer yields a value of type T, obtained via the [[bind]] method, representing some implementation defined result of writing the output. For example, an Output<string> implementation may–but is not required to–yield a string containing all code points written to the output.

Non-blocking behavior

Output writers never block. An Output writer that would otherwise block writing additional output instead enters the full state, signaling the output generator to back off producing the output, but to remain prepared to produce additional output in the future. An Output writer enters the done state when it encounters the final end of its output, signaling to the output generator to stop producing.

Output settings

An output generator may alter the tokens it produces based on its Output writer's [[settings]]. Uses include pretty printing and styling generated output. [[OutputSettings]] subclasses can provide additional parameters understood by specialized output producers.

Cloning

An Output writer may be [[clone cloned]] to branch the token stream in an implementation specified manner. Not all Output implementations support cloning.

See

  • [[OutputSettings]]
  • [[Writer]]

Type Parameters

  • T = unknown

Hierarchy

Constructors

constructor

Properties

settings

Methods

asPart bind clone debug display flush isCont isDone isError isFull isPart push trap withSettings write writeln done error full

Constructors

constructor

  • Type Parameters

    • T = unknown

    Returns Output<T>

Properties

Abstract Readonly settings

settings: OutputSettings

The OutputSettings used to configure the behavior of output producers that write to this Output.

Methods

Abstract asPart

  • Returns a partial Output equivalent to this Output, if part is true; returns a final Output equivalent to this Output if part is false. The caller's reference to this Output should be replaced by the returned Output.

    Parameters

    • part: boolean

    Returns Output<T>

Abstract bind

  • Returns the implementation-defined result of writing the output.

    Returns T

clone

  • Returns an implementation-defined branch of the token stream.

    Returns Output<T>

    Throws

    Error if this Output writer cannot be cloned.

debug

  • Writes the code points of the developer-readable [[Debug]] string of the given object. Assumes this is a Unicode Output writer with sufficient capacity.

    Parameters

    • object: unknown

    Returns Output<T>

    the continuation of the output.

    Throws

    [[OutputException]] if this Output exits the cont state before the full debug string has been written.

display

  • Writes the code points of the human-readable [[Display]] string of the given object. Assumes this is a Unicode Output writer with sufficient capacity.

    Parameters

    • object: unknown

    Returns Output<T>

    the continuation of the output.

    Throws

    [[OutputException]] if this Output exits the cont state before the full display string has been written.

flush

  • Writes any internally buffered state to the underlying output stream.

    Returns Output<T>

Abstract isCont

  • Returns true when the next [[write write(number)]] will succeed. i.e. this Output is in the cont state.

    Returns boolean

Abstract isDone

  • Returns true when no write will ever again succeed. i.e. this Output is in the done state.

    Returns boolean

Abstract isError

  • Returns true when an immediate write will fail due to an error with the token stream. i.e. this Output is in the error state. When true, trap() will return the output error.

    Returns boolean

Abstract isFull

  • Returns true when an immediate write will fail, but writes may succeed at some point in the future, i.e. this Output is in the full state.

    Returns boolean

Abstract isPart

  • Returns true if this is a partial Output that will enter the full state when it is unable to write additional tokens.

    Returns boolean

push

  • Parameters

    • Rest ...tokens: number[]

    Returns void

trap

  • Returns the output error. Only guaranteed to return an error when in the error state.

    Returns Error

    Throws

    OutputException if this Output is not in the error state.

Abstract withSettings

  • Updates the settings associated with this Output.

    Parameters

    Returns Output<T>

    this

Abstract write

  • Writes a single token to the stream, if this Output is in the cont state.

    Parameters

    • token: number

    Returns Output<T>

    this

    Throws

    [[OutputException]] if this Output is not in the cont state.

  • Writes the code points of the given string. Assumes this is a Unicode Output writer with sufficient capacity.

    Parameters

    • string: string

    Returns Output<T>

    this

    Throws

    [[OutputException]] if this Output exits the cont state before the full string has been written.

writeln

  • Writes the code points of the given string, followed by the code points of the settings' [[OutputSettings.lineSeparator line separator]. Assumes this is a Unicode Output writer with sufficient capacity.

    Parameters

    • Optional string: string

    Returns Output<T>

    this

    Throws

    [[OutputException]] if this Output exits the cont state before the full string and line separator has been written.

Static done

  • Returns an Output in the done state.

    Returns Output<never>

Static error

  • Return an Output in the error state that traps the given error.

    Parameters

    • error: Error

    Returns Output<never>

Static full

  • Return an Output in the full state.

    Returns Output<never>

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc