- Direct Known Subclasses:
InputBuffer
Input
enable incremental, interruptible parsing of network protocols
and data formats.
Input tokens
Input tokens are modeled as primitive int
s, commonly representing
Unicode code points, or raw octets; each Input
implementation
specifies the semantic type of its tokens. The head()
method
peeks at the current lookahead token, without consuming it, and the step()
method advances the input to the next token.
Input states
Input
is always in one of four states: continue,
empty, done, or error. The cont state
indicates that a lookahead token is immediately available; the empty
state indicates that no additional tokens are available at this time, but
that the stream may logically resume in the future; the done state
indicates that the stream has terminated nominally; and the error
state indicates that the stream has terminated abnormally.
isCont()
returns true
when in the cont state;
isEmpty()
returns true
when in the empty state;
isDone()
returns true
when in the done state; and
isError()
returns true
when in the error state.
Non-blocking semantics
Input
never blocks. An Input
that would otherwise block
awaiting additional tokens instead enters the empty state,
signaling the input consumer to back off processing the input, but to remain
prepared to process additional input in the future. An Input
enters
the done state when it encounters the final end of its input stream,
signaling the input consumer to terminate processing.
isPart()
returns true
if the Input
will enter
the empty state after it consumes the last immediately available
token; it returns false
if the Input
will enter the
done state after it consumes the last immediately available token.
empty()
returns an Input
in the empty
state. done()
returns an Input
in the done
state.
Position tracking
The logical position of the current lookahead token is made available via
the mark()
method, with optimized callouts for the byte offset
, one-based line
number, and one-based
column
in the current line. The id()
method
returns a diagnostic identifier for the token stream.
Cloning
An Input
may be cloned
to provide an indepently
mutable position into a shared token stream. Not all Input
implementations support cloning.
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract Input
clone()
Returns an independently positioned view into the token stream, initialized with identical state to thisInput
.int
column()
Returns the one-based column number of the current lookahead token, relative to the current line in the stream.static Input
done()
Returns anInput
in the done state.static Input
Returns anInput
in the done state, at themark
position of a token stream logically identified byid
.static Input
done
(Object id, Mark mark, InputSettings settings) Returns anInput
in the done state, at themark
position of a token stream logically identified byid
, with the givensettings
.static Input
done
(InputSettings settings) Returns anInput
in the done state, with the givensettings
.static Input
empty()
Returns anInput
in the empty state.static Input
Returns anInput
in the empty state, at themark
position of a token stream logically identified byid
.static Input
empty
(Object id, Mark mark, InputSettings settings) Returns anInput
in the empty state, at themark
position of a token stream logically identified byid
, with the givensettings
.static Input
empty
(InputSettings settings) Returns anInput
in the empty state, with the givensettings
.static Input
Returns anInput
in the error state, with the given inputerror
.static Input
Returns anInput
in the error state, with the given inputerror
, at themark
position of a token stream logically identified byid
.static Input
error
(Throwable error, Object id, Mark mark, InputSettings settings) Returns anInput
in the error state, with the given inputerror
, at themark
position of a token stream logically identified byid
, with the givensettings
.static Input
error
(Throwable error, InputSettings settings) Returns anInput
in the error state, with the given inputerror
andsettings
.Returns anInput
equivalent to thisInput
, but whose behavior may be altered by the given out-of-bandcondition
.abstract int
head()
Returns the current lookahead token, if thisInput
is in the cont state.abstract Object
id()
Returns an object that identifies the token stream, ornull
if the stream is unidentified.abstract Input
Returns anInput
equivalent to thisInput
, but logically identified by the given–possiblynull
–id
.abstract boolean
isCont()
Returnstrue
when alookeahead
token is immediately available.abstract boolean
isDone()
Returnstrue
when no lookahead token is currently available, and no additional input will ever become available.abstract boolean
isEmpty()
Returnstrue
when no lookahead token is currently available, but additional input may be available in the future.abstract boolean
isError()
Returnstrue
when no lookahead token is currently available due to an error with the token stream.abstract boolean
isPart()
Returnstrue
if this is a partialInput
will that enter the empty state after it consumes the last available input token.abstract Input
isPart
(boolean isPart) Returns a partialInput
equivalent to thisInput
, ifisPart
istrue
; returns a finalInput
equivalent to thisInput
ifisPart
isfalse
.int
line()
Returns the one-based line number of the current lookahead token, relative to the start of the stream.abstract Mark
mark()
Returns the position of the current lookahead token, relative to the start of the stream.abstract Input
Returns anInput
equivalent to thisInput
, but logically positioned at the givenmark
.long
offset()
Returns the byte offset of the current lookahead token, relative to the start of the stream.abstract Input
Returns anInput
equivalent to thisInput
, but repositioned to the givenmark
.abstract InputSettings
settings()
Returns theInputSettings
used to configure the behavior of input consumers that read from thisInput
.abstract Input
settings
(InputSettings settings) Returns anInput
equivalent to thisInput
, but with the given inputsettings
.abstract Input
step()
Returns anInput
equivalent to thisInput
, but advanced to the next token.trap()
Returns the input error.
-
Constructor Details
-
Input
public Input()
-
-
Method Details
-
isCont
public abstract boolean isCont()Returnstrue
when alookeahead
token is immediately available. i.e. thisInput
is in the cont state. -
isEmpty
public abstract boolean isEmpty()Returnstrue
when no lookahead token is currently available, but additional input may be available in the future. i.e. thisInput
is in the empty state. -
isDone
public abstract boolean isDone()Returnstrue
when no lookahead token is currently available, and no additional input will ever become available. i.e. thisInput
is in the done state. -
isError
public abstract boolean isError()Returnstrue
when no lookahead token is currently available due to an error with the token stream. i.e. thisInput
is in the error state. Whentrue
,trap()
will return the input error. -
isPart
public abstract boolean isPart()Returnstrue
if this is a partialInput
will that enter the empty state after it consumes the last available input token. -
isPart
Returns a partialInput
equivalent to thisInput
, ifisPart
istrue
; returns a finalInput
equivalent to thisInput
ifisPart
isfalse
. The caller's reference tothis
Input
should be replaced by the returnedInput
. -
head
public abstract int head()Returns the current lookahead token, if thisInput
is in the cont state.- Throws:
InputException
- if thisInput
is not in the cont state.
-
step
Returns anInput
equivalent to thisInput
, but advanced to the next token. Returns anInput
in the error state if thisInput
is not in the cont state. The caller's reference tothis
Input
should be replaced by the returnedInput
. -
seek
Returns anInput
equivalent to thisInput
, but repositioned to the givenmark
. Returns anInput
in the error state if thisInput
does not support seeking, or if thisInput
is unable to reposition to the givenmark
. The caller's reference tothis
Input
should be replaced by the returnedInput
. -
fork
Returns anInput
equivalent to thisInput
, but whose behavior may be altered by the given out-of-bandcondition
. The caller's reference tothis
Input
should be replaced by the returnedInput
. -
trap
Returns the input error. Only guaranteed to return an error when in the error state.- Throws:
InputException
- if thisInput
is not in the error state.
-
id
Returns an object that identifies the token stream, ornull
if the stream is unidentified. -
id
Returns anInput
equivalent to thisInput
, but logically identified by the given–possiblynull
–id
. The caller's reference tothis
Input
should be replaced by the returnedInput
. -
mark
Returns the position of the current lookahead token, relative to the start of the stream. -
mark
Returns anInput
equivalent to thisInput
, but logically positioned at the givenmark
. The physical position in the input stream is not modified. The caller's reference tothis
Input
should be replaced by the returnedInput
. -
offset
public long offset()Returns the byte offset of the current lookahead token, relative to the start of the stream. -
line
public int line()Returns the one-based line number of the current lookahead token, relative to the start of the stream. -
column
public int column()Returns the one-based column number of the current lookahead token, relative to the current line in the stream. -
settings
Returns theInputSettings
used to configure the behavior of input consumers that read from thisInput
. -
settings
Returns anInput
equivalent to thisInput
, but with the given inputsettings
. The caller's reference tothis
Input
should be replaced by the returnedInput
. -
clone
Returns an independently positioned view into the token stream, initialized with identical state to thisInput
.- Overrides:
clone
in classObject
- Throws:
UnsupportedOperationException
- if thisInput
cannot be cloned.
-
empty
Returns anInput
in the empty state. -
empty
Returns anInput
in the empty state, with the givensettings
. -
empty
Returns anInput
in the empty state, at themark
position of a token stream logically identified byid
. -
empty
Returns anInput
in the empty state, at themark
position of a token stream logically identified byid
, with the givensettings
. -
done
Returns anInput
in the done state. -
done
Returns anInput
in the done state, with the givensettings
. -
done
Returns anInput
in the done state, at themark
position of a token stream logically identified byid
. -
done
Returns anInput
in the done state, at themark
position of a token stream logically identified byid
, with the givensettings
. -
error
Returns anInput
in the error state, with the given inputerror
. -
error
Returns anInput
in the error state, with the given inputerror
andsettings
. -
error
Returns anInput
in the error state, with the given inputerror
, at themark
position of a token stream logically identified byid
. -
error
Returns anInput
in the error state, with the given inputerror
, at themark
position of a token stream logically identified byid
, with the givensettings
.
-