Module swim.codec

Package swim.codec

Incremental I/O; functional parsers and writers; display, debug, and diagnostic formatters; and Unicode and binary codecs. swim.codec enables efficient, interruptible transcoding of network protocols and data formats, without blocking or intermediate buffering.

Inputs and Outputs

An Input reader abstracts over a non-blocking token input stream, with single token lookahead. An Output writer abstracts over a non-blocking token output stream.

Parsers and Writers

A Parser incrementally reads from a sequence of Input chunks to produce a parsed result. A Writer incrementally writes to a sequence of Output chunks.

Decoders and Encoders

A Decoder incrementally decodes a sequence of input buffers to produce a decoded result. An Encoder incrementally encodes a value into a sequence of output buffers.

Binary codecs

The Binary factory has methods to create Input readers that read bytes out of byte buffers, and methods to create Output writers that write bytes into byte buffers.

Text codecs

The Unicode factory has methods to create Input readers that read Unicode code points out of strings, and methods to create Output writers that write Unicode code points into strings.

The Utf8 factory has methods to create Input readers that decode Unicode code points out of UTF-8 encoded byte buffers, and methods to create Output writers that encode Unicode code points into UTF-8 encoded byte buffers.

Binary-Text codecs

The Base10 factory has methods to create Parsers that incrementally parse decimal formatted integers, and methods to create Writers that incrementally write decimal formatted integers.

The Base16 factory has methods to create Parsers that incrementally decode hexadecimal encoded text input into byte buffers, and methods to create Writers that incrementally encode byte buffers to hexadecimal encoded text output.

The Base64 factory has methods to create Parsers that incrementally decode base-64 encoded text input into byte buffers, and methods to create Writers that incrementally encode byte buffers to base-64 encoded text output.

Formatters

The Display interface provides a standard way for implementing classes to directly output human readable display strings. Similarly, the Debug interface provides a standard way for implementing classes to directly output developer readable debug strings.

Format provides extension methods to output display and debug strings for all types, including builtin Java types. OutputStyle provides helper functions to conditionally emit ASCII escape codes to stylize text for console output.

Diagnostics

A Tag abstracts over a source input location. A Mark describes a source input position, and a Span describes a source input range. A Diagnostic attaches an informational message to a source input location, and supports displaying the diagnostic as an annotated snippet of the relevant source input.

Interface Summary

Interface	Description
Debug	Type that can output a developer readable debug string.
Display	Type that can output a human readable display string.

Class Summary

Class	Description
Base10	Base-10 (decimal) encoding Parser/Writer factory.
Base16	Base-16 (hexadecimal) encoding Parser/Writer factory.
Base64	Base-64 (7-bit ASCII) encoding Parser/Writer factory.
Binary	Byte Input/Output factory.
Decoder<O>	Continuation of how to decode subsequent input buffers from a byte stream.
Detect
Diagnostic	Informational message attached to an input location.
DynamicDecoder<O>	Dynamically generated Decoder continuation.
DynamicEncoder<I,O>	Dynamically generated Encoder continuation.
Encoder<I,O>	Continuation of how encode subsequent output buffers for a byte stream.
Format	Text format utility functions.
Input	Non-blocking token stream reader, with single token lookahead.
InputBuffer	Non-blocking token stream buffer.
InputSettings	Input consumption parameters.
Mark	Description of a source position, identified by byte offset, line, and column number, with an optional note.
Output<T>	Non-blocking token stream writer.
OutputBuffer<T>	Non-blocking token stream buffer.
OutputSettings	Output production parameters.
OutputStyle	Stylized text output utility functions.
Parser<O>	Continuation of how to parse subsequent Input tokens from a stream.
Span	Description of a source range, identified by a closed interval between start and end marks.
Tag	Description of a source location.
Unicode	Unicode code point Input/Output/Writer factory.
Utf8	UTF-8 Input/Output factory.
UtfErrorMode	Unicode transformation format error handling mode.
Writer<I,O>	Continuation of how to write subsequent Output tokens to a stream.

Exception Summary

Exception	Description
DecoderException	Thrown when a Decoder decodes invalid data.
EncoderException	Thrown when an Encoder encodes invalid data.
InputException	Thrown when reading invalid Input.
OutputException	Thrown when writing invalid Output.
ParserException	Thrown when a Parser parses invdalid syntax.
WriterException	Thrown when a Writer attempts to write invalid syntax.