```
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

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
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 `bind`s a `null` parsed result.
`static <O> Parser<O>`	`done(O output)`	Returns a `Parser` in the done state that `bind`s the given parsed `output`.
`static <O> Parser<O>`	`error(Throwable error)`	Returns a `Parser` in the error state that `trap`s the given parse `error`.
`static <O> Parser<O>`	`error(Diagnostic diagnostic)`	Returns a `Parser` in the error state that `trap`s 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 Detail
  - Parser
```
public Parser()
```
- Method Detail
  - 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.

Class Parser<O>

Input tokens

Parser states

Feeding input

Parser results

Continuations

Iteratees

Immutability

Backtracking

Forking

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Parser

Method Detail

isCont

isDone

isError

feed

feed

fork

bind

trap

asError

done

done

error

error