- Direct Known Subclasses:
CookieHeaderParser
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 int
s, 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 -
Method Summary
Modifier and TypeMethodDescription<O2> Parser<O2>
asError()
Casts an erroredParser
to a different output type.bind()
Returns the parsed result.static <O> Parser<O>
done()
Returns aParser
in the done state thatbind
s anull
parsed result.static <O> Parser<O>
done
(O output) Returns aParser
in the done state thatbind
s the given parsedoutput
.static <O> Parser<O>
Returns aParser
in the error state thattrap
s the given parseerror
.static <O> Parser<O>
error
(Diagnostic diagnostic) Incrementally parses as muchinput
as possible, and returns anotherParser
that represents the continuation of how to parse additionalInput
.feed
(InputBuffer input) Incrementally decodes as muchinput
buffer data as possible, and returns anotherDecoder
that represents the continuation of how to decode additional buffer data.Returns aParser
continuation whose behavior may be altered by the given out-of-bandcondition
.boolean
isCont()
boolean
isDone()
Returnstrue
when parsing has terminated successfully, andbind
will return the parsed result.boolean
isError()
Returnstrue
when parsing has terminated in failure, andtrap
will return the parse error.trap()
Returns the parse error.
-
Constructor Details
-
Parser
public Parser()
-
-
Method Details
-
isCont
public boolean isCont() -
isDone
public boolean isDone()Returnstrue
when parsing has terminated successfully, andbind
will return the parsed result. i.e. thisParser
is in the done state. -
isError
public boolean isError()Returnstrue
when parsing has terminated in failure, andtrap
will return the parse error. i.e. thisParser
is in the error state. -
feed
Incrementally parses as muchinput
as possible, and returns anotherParser
that represents the continuation of how to parse additionalInput
. Ifinput
enters the done state,feed
must return a terminatedParser
, i.e. aParser
in the done state, or in the error state. The giveninput
is only guaranteed to be valid for the duration of the method call; references toinput
must not be stored. -
feed
Description copied from class:Decoder
Incrementally decodes as muchinput
buffer data as possible, and returns anotherDecoder
that represents the continuation of how to decode additional buffer data. IfisLast
istrue
, thenfeed
must return a terminatedDecoder
, i.e. aDecoder
in the done state, or in the error state. The giveninput
buffer is only guaranteed to be valid for the duration of the method call; references toinput
must not be stored. -
fork
Returns aParser
continuation whose behavior may be altered by the given out-of-bandcondition
. -
bind
Returns the parsed result. Only guaranteed to return a result when in the done state.- Overrides:
bind
in classDecoder<O>
- Throws:
IllegalStateException
- if thisParser
is not in the done state.
-
trap
Returns the parse error. Only guaranteed to return an error when in the error state.- Overrides:
trap
in classDecoder<O>
- Throws:
IllegalStateException
- if thisParser
is not in the error state.
-
asError
Casts an erroredParser
to a different output type. AParser
in the error state can have any output type.- Overrides:
asError
in classDecoder<O>
- Throws:
IllegalStateException
- if thisParser
is not in the error state.
-
done
Returns aParser
in the done state thatbind
s anull
parsed result. -
done
Returns aParser
in the done state thatbind
s the given parsedoutput
. -
error
Returns aParser
in the error state thattrap
s the given parseerror
. -
error
-