Module swim.codec
Package swim.codec

Class 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:
    InputSettings, Parser
    • Constructor Summary

      Constructors 
      Constructor Description
      Input()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      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 nullid.
      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.
    • Constructor Detail

      • Input

        public Input()
    • Method Detail

      • 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 nullid. 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.