Module swim.codec
Package swim.codec

Class Parser<O>

java.lang.Object
swim.codec.Decoder<O>
swim.codec.Parser<O>
Direct Known Subclasses:
CookieHeaderParser
public abstract class Parser<O> extends Decoder<O>
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 ints, 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: continue, 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(Input) 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. done(Object) returns a Parser in the done state. error(Throwable) 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 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(Object) 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.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Parser()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    <O2> Parser<O2>
    asError()
    Casts an errored Parser to a different output type.
    O
    bind()
    Returns the parsed result.
    static <O> Parser<O>
    done()
    Returns a Parser in the done state that binds a null parsed result.
    static <O> Parser<O>
    done(O output)
    Returns a Parser in the done state that binds the given parsed output.
    static <O> Parser<O>
    error(Throwable error)
    Returns a Parser in the error state that traps the given parse error.
    static <O> Parser<O>
    error(Diagnostic diagnostic)
    Returns a Parser in the error state that traps a ParserException with the given diagnostic.
    abstract Parser<O>
    feed(Input input)
    Incrementally parses as much input as possible, and returns another Parser that represents the continuation of how to parse additional Input.
    Parser<O>
    feed(InputBuffer input)
    Incrementally decodes as much input buffer data as possible, and returns another Decoder that represents the continuation of how to decode additional buffer data.
    Parser<O>
    fork(Object condition)
    Returns a Parser continuation whose behavior may be altered by the given out-of-band condition.
    boolean
    isCont()
    Returns true when feed is able to consume Input.
    boolean
    isDone()
    Returns true when parsing has terminated successfully, and bind will return the parsed result.
    boolean
    isError()
    Returns true when parsing has terminated in failure, and trap will return the parse error.
    Throwable
    trap()
    Returns the parse error.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Parser

      public Parser()

  • Method Details

    • isCont

      public boolean isCont()
      Returns true when feed is able to consume Input. i.e. this Parser is in the cont state.
      Overrides:
      isCont in class Decoder<O>

    • isDone

      public boolean isDone()
      Returns true when parsing has terminated successfully, and bind will return the parsed result. i.e. this Parser is in the done state.
      Overrides:
      isDone in class Decoder<O>

    • isError

      public boolean isError()
      Returns true when parsing has terminated in failure, and trap will return the parse error. i.e. this Parser is in the error state.
      Overrides:
      isError in class Decoder<O>

    • feed

      public abstract Parser<O> feed(Input input)
      Incrementally parses as much input as possible, and returns another Parser that represents the continuation of how to parse additional Input. If input enters the done state, feed must return a terminated Parser, i.e. a Parser in the done state, or in the error state. The given input is only guaranteed to be valid for the duration of the method call; references to input must not be stored.

    • feed

      public Parser<O> feed(InputBuffer input)
      Description copied from class: Decoder
      Incrementally decodes as much input buffer data as possible, and returns another Decoder that represents the continuation of how to decode additional buffer data. If isLast is true, then feed must return a terminated Decoder, i.e. a Decoder in the done state, or in the error state. The given input buffer is only guaranteed to be valid for the duration of the method call; references to input must not be stored.
      Specified by:
      feed in class Decoder<O>

    • fork

      public Parser<O> fork(Object condition)
      Returns a Parser continuation whose behavior may be altered by the given out-of-band condition.
      Overrides:
      fork in class Decoder<O>

    • bind

      public O bind()
      Returns the parsed result. Only guaranteed to return a result when in the done state.
      Overrides:
      bind in class Decoder<O>
      Throws:
      IllegalStateException - if this Parser is not in the done state.

    • trap

      public Throwable trap()
      Returns the parse error. Only guaranteed to return an error when in the error state.
      Overrides:
      trap in class Decoder<O>
      Throws:
      IllegalStateException - if this Parser is not in the error state.

    • asError

      public <O2> Parser<O2> asError()
      Casts an errored Parser to a different output type. A Parser in the error state can have any output type.
      Overrides:
      asError in class Decoder<O>
      Throws:
      IllegalStateException - if this Parser is not in the error state.

    • done

      public static <O> Parser<O> done()
      Returns a Parser in the done state that binds a null parsed result.

    • done

      public static <O> Parser<O> done(O output)
      Returns a Parser in the done state that binds the given parsed output.

    • error

      public static <O> Parser<O> error(Throwable error)
      Returns a Parser in the error state that traps the given parse error.

    • error

      public static <O> Parser<O> error(Diagnostic diagnostic)
      Returns a Parser in the error state that traps a ParserException with the given diagnostic.