Class Parser<O>Abstract

Continuation of how to parse subsequent [[Input]] tokens from a stream. Parser enables efficient, interruptible parsing of network protocols and data formats, without intermediate buffering.

Input tokens

A Parser reads tokens from an Input reader. Input tokens are modeled as primitive numbers, commonly representing Unicode code points, or raw octets. Each Parser implementation specifies the semantic type of input tokens it consumes.

Parser states

A Parser is always in one of three states: _cont_​inue, done, or error. The cont state indicates that [[feed]] is ready to consume Input; the done state indicates that parsing terminated successfully, and that [[bind]] will return the parsed result; the error state indicates that parsing terminated in failure, and that [[trap]] will return the parse error. Parser subclasses default to the cont state.

Feeding input

The [[feed]] method incrementally parses as much Input as it can, before returning another Parser that represents the continuation of how to parse additional Input. The Input passed to feed is only guaranteed to be valid for the duration of the method call; references to the provided Input instance must not be stored.

Parser results

A Parser produces a parsed 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 Parser provides a parse error via the [[trap]] method. trap is only guaranteed to return an error when in the error state.

Continuations

A Parser instance represents a continuation of how to parse remaining Input. Rather than parsing a complete input in one go, a Parser takes an Input chunk and returns another Parser instance that knows how to parse subsequent Input chunks. This enables non-blocking, incremental parsing that can be interrupted whenever an Input reader runs out of immediately available data. A Parser terminates by returning a continuation in either the done state, or the error state. [[Parser.done]] returns a Parser in the done state. [[Parser.error]] returns a Parser in the error state.

Iteratees

Parser is an Iteratee. Though unlike strictly functional iteratees, a Parser statefully iterates over its Input, rather than allocating an object for each incremental input continutaion. This internal mutability minimizes garbage collector memory pressure, without violating the functional Iteratee abstraction, provided that feed logically takes exclusive ownership of its Input when invoked, and logically returns ownership of the Input in a state that's consistent with the returned Parser continuation.

Immutability

A Parser should be immutable. Specifically, an invocation of feed should not alter the behavior of future calls to feed on the same Parser instance. A Parser should only mutate its internal state if it's essential to do so, such as for critical path performance reasons.

Backtracking

feed can internally [[Input.clone clone]] its Input, if it might need to backtrack. Keep in mind that, because Input is only valid for the duration of a call to feed, input must be internally buffered if it needs to be preserved between feed invocations.

Forking

The [[fork]] method passes an out-of-band condition to a Parser, yielding a Parser continuation whose behavior may be altered by the given condition. For example, an HTML Parser might fork an inner text parser to directly parse an embedded micro format out of an HTML element, based on some out-of-band schema information. The types of conditions accepted by fork, and their intended semantics, are implementation defined.