Package software.amazon.smithy.utils

Class SimpleParser

  • public class SimpleParser
extends java.lang.Object
    A simple expression parser that can be extended to implement parsers for small domain-specific languages.

    This parser internally consumes characters of a CharSequence while tracking the current 0-based position, 1-based line, and 1-based column. Expectations can be made on the parser to require specific characters, and when those expectations are not met, a syntax exception is thrown.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static char EOF  

    • Constructor Summary

      Constructors 
      Constructor Description
      SimpleParser​(java.lang.CharSequence expression)
      Creates a new SimpleParser and sets the expression to parse.
      SimpleParser​(java.lang.CharSequence input, int maxNestingLevel)
      Creates a new SimpleParser and sets the expression to parse.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      java.lang.CharSequence borrowSliceFrom​(int start)
      Gets a zero-copy slice of the expression starting from the given 0-based character position, read all the way through to the current position of the parser.
      java.lang.CharSequence borrowSliceFrom​(int start, int removeRight)
      Gets a zero-copy slice of the expression starting from the given 0-based character position, read all the way through to the current position of the parser minus removeRight.
      void br()
      Skips spaces then expects that the next character is either the end of the expression or a line break (\n, \r\n, or \r).
      int column()
      Gets the current 1-based column number of the parser.
      void consumeRemainingCharactersOnLine()
      Skips over the remaining characters on a line but does not consume the newline character (\n or \r\n).
      int consumeUntilNoLongerMatches​(java.util.function.Predicate<java.lang.Character> predicate)
      Deprecated.
      int consumeWhile​(java.util.function.IntPredicate predicate)
      Reads a lexeme from the expression while the given predicate matches each peeked character.
      void decreaseNestingLevel()
      Decreases the current nesting level of the parser.
      boolean eof()
      Checks if the parser has reached the end of the expression.
      char expect​(char token)
      Expects that the next character is the given character and consumes it.
      char expect​(char... tokens)
      Expects that the next character is one of a fixed set of possible characters.
      java.lang.String expression()
      Deprecated.
      void increaseNestingLevel()
      Increases the current nesting level of the parser.
      java.lang.CharSequence input()
      Gets the input being parsed as a CharSequence.
      int line()
      Gets the current 1-based line number of the parser.
      int nestingLevel()
      Gets the current 0-based nesting level of the parser.
      char peek()
      Returns the current character of the expression, but does not consume it.
      char peek​(int offset)
      Returns the current character of the expression + offset characters, but does not consume it.
      java.lang.String peekSingleCharForMessage()
      Peeks the next character and returns [EOF] if the next character is past the end of the expression.
      int position()
      Gets the current 0-based position of the parser.
      void rewind​(int position, int line, int column)  
      void skip()
      Skips a single character while tracking lines and columns.
      java.lang.String sliceFrom​(int start)
      Copies a slice of the expression into a string, starting from the given 0-based character position, read all the way through to the current position of the parser.
      void sp()
      Skip 0 or more spaces (that is, ' ' and '\t').
      java.lang.RuntimeException syntax​(java.lang.String message)
      Creates a syntax error that adds some context to the given message.
      void ws()
      Skip 0 or more whitespace characters (that is, ' ', '\t', '\r', and '\n').

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SimpleParser

        public SimpleParser​(java.lang.CharSequence expression)
        Creates a new SimpleParser and sets the expression to parse.
        Parameters:
        expression - Expression to parser.

      • SimpleParser

        public SimpleParser​(java.lang.CharSequence input,
                    int maxNestingLevel)
        Creates a new SimpleParser and sets the expression to parse.

        By default, no maximum parsing level is enforced. Setting the maxParsingLevel to 0 disables the enforcement of a maximum parsing level.

        Parameters:
        input - Input to parse that must not be null.
        maxNestingLevel - The maximum allowed nesting level of the parser.

    • Method Detail

      • input

        public final java.lang.CharSequence input()
        Gets the input being parsed as a CharSequence.
        Returns:
        Returns the input being parsed.

      • expression

        @Deprecated
public final java.lang.String expression()
        Deprecated.

      • position

        public final int position()
        Gets the current 0-based position of the parser.
        Returns:
        Returns the parser character position.

      • line

        public final int line()
        Gets the current 1-based line number of the parser.
        Returns:
        Returns the current line number.

      • column

        public final int column()
        Gets the current 1-based column number of the parser.
        Returns:
        Returns the current column number.

      • rewind

        public final void rewind​(int position,
                         int line,
                         int column)

      • eof

        public final boolean eof()
        Checks if the parser has reached the end of the expression.
        Returns:
        Returns true if the parser has reached the end.

      • peek

        public final char peek()
        Returns the current character of the expression, but does not consume it.
        Returns:
        Returns the peeked character.

      • peek

        public final char peek​(int offset)
        Returns the current character of the expression + offset characters, but does not consume it.

        If the end of the expression is reached or if the peeked offset is calculated to be less than 0, Character.MIN_VALUE is returned (that is, '\0').

        Parameters:
        offset - The number of characters to peek ahead (positive or negative).
        Returns:
        Returns the peeked character.

      • expect

        public final char expect​(char token)
        Expects that the next character is the given character and consumes it.
        Parameters:
        token - The character to expect.
        Returns:
        Returns the expected character.

      • peekSingleCharForMessage

        public final java.lang.String peekSingleCharForMessage()
        Peeks the next character and returns [EOF] if the next character is past the end of the expression.
        Returns:
        Returns the peeked next character.

      • expect

        public final char expect​(char... tokens)
        Expects that the next character is one of a fixed set of possible characters.
        Parameters:
        tokens - Characters to expect.
        Returns:
        Returns the consumed character.

      • syntax

        public java.lang.RuntimeException syntax​(java.lang.String message)
        Creates a syntax error that adds some context to the given message.
        Parameters:
        message - Message for why the error occurred.
        Returns:
        Returns the created syntax error.

      • ws

        public void ws()
        Skip 0 or more whitespace characters (that is, ' ', '\t', '\r', and '\n').

      • sp

        public void sp()
        Skip 0 or more spaces (that is, ' ' and '\t').

      • br

        public void br()
        Skips spaces then expects that the next character is either the end of the expression or a line break (\n, \r\n, or \r).
        Throws:
        java.lang.RuntimeException - if the next non-space character is not EOF or a line break.

      • skip

        public void skip()
        Skips a single character while tracking lines and columns.

      • consumeRemainingCharactersOnLine

        public void consumeRemainingCharactersOnLine()
        Skips over the remaining characters on a line but does not consume the newline character (\n or \r\n).

        This method will also terminate when the end of the expression is encountered.

        This method is useful, for example, for skipping the text of a commented out line in an expression. If the contents of the skipped line are required, then store the current position before invoking this method using position(), then call this method, then get the contents of the skipped characters using sliceFrom(int).

      • sliceFrom

        public final java.lang.String sliceFrom​(int start)
        Copies a slice of the expression into a string, starting from the given 0-based character position, read all the way through to the current position of the parser.
        Parameters:
        start - Position to slice from, ending at the current position.
        Returns:
        Returns the copied slice of the expression from start to position.

      • borrowSliceFrom

        public final java.lang.CharSequence borrowSliceFrom​(int start)
        Gets a zero-copy slice of the expression starting from the given 0-based character position, read all the way through to the current position of the parser.
        Parameters:
        start - Position to slice from, ending at the current position.
        Returns:
        Returns the zero-copy slice of the expression from start to position.

      • borrowSliceFrom

        public final java.lang.CharSequence borrowSliceFrom​(int start,
                                                    int removeRight)
        Gets a zero-copy slice of the expression starting from the given 0-based character position, read all the way through to the current position of the parser minus removeRight.
        Parameters:
        start - Position to slice from, ending at the current position.
        removeRight - Number of characters to omit before the current position.
        Returns:
        Returns the zero-copy slice of the expression from start to position.

      • consumeUntilNoLongerMatches

        @Deprecated
public final int consumeUntilNoLongerMatches​(java.util.function.Predicate<java.lang.Character> predicate)
        Deprecated.

      • consumeWhile

        public final int consumeWhile​(java.util.function.IntPredicate predicate)
        Reads a lexeme from the expression while the given predicate matches each peeked character.
        Parameters:
        predicate - Predicate that filters characters.
        Returns:
        Returns the consumed lexeme (or an empty string on no matches).

      • increaseNestingLevel

        public final void increaseNestingLevel()
        Increases the current nesting level of the parser.

        This method can be manually invoked when parsing in order to prevent parsing too deeply using recursive descent parsers.

        Throws:
        java.lang.RuntimeException - if the nesting level is deeper than the max allowed nesting.

      • decreaseNestingLevel

        public final void decreaseNestingLevel()
        Decreases the current nesting level of the parser.

      • nestingLevel

        public int nestingLevel()
        Gets the current 0-based nesting level of the parser.
        Returns:
        Returns the current nesting level.