Input tokens are modeled as primitive numbers, commonly representing Unicode
code points, or raw octets; each Input implementation specifies the
semantic type of its tokens. The [[head]] method peeks at the lookahead
token, without consuming it, and the [[step]] method advances the input to
the next token.
An Input reader is always in one of three states: _cont_inue, empty, or
done. 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 at some
point in the future; and the done state indicates that the stream has
terminated. [[isCont]] returns true when in the cont state; [[isEmpty]]
returns true when in the empty state; and [[isDone]] returns true when
in the done state.
Input readers never block. An Input reader that would otherwise block
awaiting additional input 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 reader enters the done
state when it encounters the final end of its input, signaling the input
consumer to stop processing. [[Input.empty]] returns an Input reader in
the empty state. [[Input.done]] returns an Input reader in the done
state.
The logical position of the 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.
An Input reader may be [[clone cloned]] to provide an indepently mutable
position into a shared token stream. Not all Input implementations
support cloning.
Returns a partial Input equivalent to this Input, if part is true;
returns a final Input equivalent to this Input if part is false.
The caller's reference to this Input should be replaced by the returned
Input
Returns the current lookahead token, if this Input is in the
cont state.
Returns number
Throws
[[InputException]] if this Input is not in the cont state.
AbstractisCont
isCont(): boolean
Returns true when a [[head lookahead]] token is immediately available.
i.e. this Input is in the cont state.
Returns boolean
AbstractisDone
isDone(): boolean
Returns true when no lookahead token is currently available, and no
additional input will ever become available, i.e. this Input is in
the done state.
Returns boolean
AbstractisEmpty
isEmpty(): boolean
Returns true when no lookahead token is currently available, but
additional input may be available at some point in the future, i.e. this
Input is in the empty state.
Returns boolean
AbstractisError
isError(): boolean
Returns true when no lookahead token is currently available due to an
error with the token stream. i.e. this Input is in the error state.
When true, trap() will return the input error
Returns boolean
AbstractisPart
isPart(): boolean
Returns true if this is a partial Input will that enter the empty
state after it consumes the last available input token.
Returns an Input equivalent to this Input, but logically identified
by the given–possibly undefined–id. The caller's reference to this
Input should be replaced by the returned Input.
Returns an Input equivalent to this Input, but logically positioned
at the given mark. The physical position in the input stream is not
modified. The caller's reference to this Input should be replaced by
the returned Input.
Non-blocking token stream reader, with single token lookahead.
Inputenables incremental, interruptible parsing of network protocols and data formats.Input tokens
Input tokens are modeled as primitive numbers, commonly representing Unicode code points, or raw octets; each
Inputimplementation specifies the semantic type of its tokens. The [[head]] method peeks at the lookahead token, without consuming it, and the [[step]] method advances the input to the next token.Input states
An
Inputreader is always in one of three states: _cont_inue, empty, or done. 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 at some point in the future; and the done state indicates that the stream has terminated. [[isCont]] returnstruewhen in the cont state; [[isEmpty]] returnstruewhen in the empty state; and [[isDone]] returnstruewhen in the done state.Non-blocking behavior
Inputreaders never block. AnInputreader that would otherwise block awaiting additional input 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. AnInputreader enters the done state when it encounters the final end of its input, signaling the input consumer to stop processing. [[Input.empty]] returns anInputreader in the empty state. [[Input.done]] returns anInputreader in the done state.Position tracking
The logical position of the 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
Inputreader may be [[clone cloned]] to provide an indepently mutable position into a shared token stream. Not allInputimplementations support cloning.See