Module swim.codec
Package swim.codec

Class Input

java.lang.Object
swim.codec.Input
Direct Known Subclasses:
InputBuffer
public abstract class Input extends Object
Non-blocking token stream reader, with single token lookahead. Input enable incremental, interruptible parsing of network protocols and data formats.

Input tokens

Input tokens are modeled as primitive ints, 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

    Constructors
    Constructor
    Description
    Input()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract Input
    clone()
    Returns an independently positioned view into the token stream, initialized with identical state to this Input.
    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 an Input in the done state.
    static Input
    done(Object id, Mark mark)
    Returns an Input in the done state, at the mark position of a token stream logically identified by id.
    static Input
    done(Object id, Mark mark, InputSettings settings)
    Returns an Input in the done state, at the mark position of a token stream logically identified by id, with the given settings.
    static Input
    done(InputSettings settings)
    Returns an Input in the done state, with the given settings.
    static Input
    empty()
    Returns an Input in the empty state.
    static Input
    empty(Object id, Mark mark)
    Returns an Input in the empty state, at the mark position of a token stream logically identified by id.
    static Input
    empty(Object id, Mark mark, InputSettings settings)
    Returns an Input in the empty state, at the mark position of a token stream logically identified by id, with the given settings.
    static Input
    empty(InputSettings settings)
    Returns an Input in the empty state, with the given settings.
    static Input
    error(Throwable error)
    Returns an Input in the error state, with the given input error.
    static Input
    error(Throwable error, Object id, Mark mark)
    Returns an Input in the error state, with the given input error, at the mark position of a token stream logically identified by id.
    static Input
    error(Throwable error, Object id, Mark mark, InputSettings settings)
    Returns an Input in the error state, with the given input error, at the mark position of a token stream logically identified by id, with the given settings.
    static Input
    error(Throwable error, InputSettings settings)
    Returns an Input in the error state, with the given input error and settings.
    Input
    fork(Object condition)
    Returns an Input equivalent to this Input, but whose behavior may be altered by the given out-of-band condition.
    abstract int
    head()
    Returns the current lookahead token, if this Input is in the cont state.
    abstract Object
    id()
    Returns an object that identifies the token stream, or null if the stream is unidentified.
    abstract Input
    id(Object id)
    Returns an Input equivalent to this Input, but logically identified by the given–possibly null–id.
    abstract boolean
    isCont()
    Returns true when a lookeahead token is immediately available.
    abstract boolean
    isDone()
    Returns true when no lookahead token is currently available, and no additional input will ever become available.
    abstract boolean
    isEmpty()
    Returns true when no lookahead token is currently available, but additional input may be available in the future.
    abstract boolean
    isError()
    Returns true when no lookahead token is currently available due to an error with the token stream.
    abstract boolean
    isPart()
    Returns true if this is a partial Input will that enter the empty state after it consumes the last available input token.
    abstract Input
    isPart(boolean isPart)
    Returns a partial Input equivalent to this Input, if isPart is true; returns a final Input equivalent to this Input if isPart is false.
    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
    mark(Mark mark)
    Returns an Input equivalent to this Input, but logically positioned at the given mark.
    long
    offset()
    Returns the byte offset of the current lookahead token, relative to the start of the stream.
    abstract Input
    seek(Mark mark)
    Returns an Input equivalent to this Input, but repositioned to the given mark.
    abstract InputSettings
    settings()
    Returns the InputSettings used to configure the behavior of input consumers that read from this Input.
    abstract Input
    settings(InputSettings settings)
    Returns an Input equivalent to this Input, but with the given input settings.
    abstract Input
    step()
    Returns an Input equivalent to this Input, but advanced to the next token.
    Throwable
    trap()
    Returns the input error.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Input

      public Input()

  • Method Details

    • isCont

      public abstract boolean isCont()
      Returns true when a lookeahead token is immediately available. i.e. this Input is in the cont state.

    • isEmpty

      public abstract boolean isEmpty()
      Returns true when no lookahead token is currently available, but additional input may be available in the future. i.e. this Input is in the empty state.

    • isDone

      public abstract boolean isDone()
      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.

    • isError

      public abstract boolean isError()
      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.

    • isPart

      public abstract boolean isPart()
      Returns true if this is a partial Input will that enter the empty state after it consumes the last available input token.

    • isPart

      public abstract Input isPart(boolean isPart)
      Returns a partial Input equivalent to this Input, if isPart is true; returns a final Input equivalent to this Input if isPart is false. The caller's reference to this Input should be replaced by the returned Input.

    • head

      public abstract int head()
      Returns the current lookahead token, if this Input is in the cont state.
      Throws:
      InputException - if this Input is not in the cont state.

    • step

      public abstract Input step()
      Returns an Input equivalent to this Input, but advanced to the next token. Returns an Input in the error state if this Input is not in the cont state. The caller's reference to this Input should be replaced by the returned Input.

    • seek

      public abstract Input seek(Mark mark)
      Returns an Input equivalent to this Input, but repositioned to the given mark. Returns an Input in the error state if this Input does not support seeking, or if this Input is unable to reposition to the given mark. The caller's reference to this Input should be replaced by the returned Input.

    • fork

      public Input fork(Object condition)
      Returns an Input equivalent to this Input, but whose behavior may be altered by the given out-of-band condition. The caller's reference to this Input should be replaced by the returned Input.

    • trap

      public Throwable trap()
      Returns the input error. Only guaranteed to return an error when in the error state.
      Throws:
      InputException - if this Input is not in the error state.

    • id

      public abstract Object id()
      Returns an object that identifies the token stream, or null if the stream is unidentified.

    • id

      public abstract Input id(Object id)
      Returns an Input equivalent to this Input, but logically identified by the given–possibly null–id. The caller's reference to this Input should be replaced by the returned Input.

    • mark

      public abstract Mark mark()
      Returns the position of the current lookahead token, relative to the start of the stream.

    • mark

      public abstract Input mark(Mark mark)
      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.

    • 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

      public abstract InputSettings settings()
      Returns the InputSettings used to configure the behavior of input consumers that read from this Input.

    • settings

      public abstract Input settings(InputSettings settings)
      Returns an Input equivalent to this Input, but with the given input settings. The caller's reference to this Input should be replaced by the returned Input.

    • clone

      public abstract Input clone()
      Returns an independently positioned view into the token stream, initialized with identical state to this Input.
      Overrides:
      clone in class Object
      Throws:
      UnsupportedOperationException - if this Input cannot be cloned.

    • empty

      public static Input empty()
      Returns an Input in the empty state.

    • empty

      public static Input empty(InputSettings settings)
      Returns an Input in the empty state, with the given settings.

    • empty

      public static Input empty(Object id, Mark mark)
      Returns an Input in the empty state, at the mark position of a token stream logically identified by id.

    • empty

      public static Input empty(Object id, Mark mark, InputSettings settings)
      Returns an Input in the empty state, at the mark position of a token stream logically identified by id, with the given settings.

    • done

      public static Input done()
      Returns an Input in the done state.

    • done

      public static Input done(InputSettings settings)
      Returns an Input in the done state, with the given settings.

    • done

      public static Input done(Object id, Mark mark)
      Returns an Input in the done state, at the mark position of a token stream logically identified by id.

    • done

      public static Input done(Object id, Mark mark, InputSettings settings)
      Returns an Input in the done state, at the mark position of a token stream logically identified by id, with the given settings.

    • error

      public static Input error(Throwable error)
      Returns an Input in the error state, with the given input error.

    • error

      public static Input error(Throwable error, InputSettings settings)
      Returns an Input in the error state, with the given input error and settings.

    • error

      public static Input error(Throwable error, Object id, Mark mark)
      Returns an Input in the error state, with the given input error, at the mark position of a token stream logically identified by id.

    • error

      public static Input error(Throwable error, Object id, Mark mark, InputSettings settings)
      Returns an Input in the error state, with the given input error, at the mark position of a token stream logically identified by id, with the given settings.