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 consumes characters of an in-memory string 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.

    • Constructor Summary

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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)
      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()
      Gets the expression being parsed.
      void increaseNestingLevel()
      Increases the current nesting level of the parser.
      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 skip()
      Skips a single character while tracking lines and columns.
      java.lang.String sliceFrom​(int start)
      Gets a slice of the expression 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.String expression)
        Creates a new SimpleParser and sets the expression to parse.
        Parameters:
        expression - Expression to parser.

      • SimpleParser

        public SimpleParser​(java.lang.String expression,
                    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:
        expression - Expression to parse that must not be null.
        maxNestingLevel - The maximum allowed nesting level of the parser.

    • Method Detail

      • expression

        public final java.lang.String expression()
        Gets the expression being parsed.
        Returns:
        Returns the expression being parsed.

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

      • 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)
        Gets a 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 slice of the expression from start to position.

      • consumeUntilNoLongerMatches

        public final int consumeUntilNoLongerMatches​(java.util.function.Predicate<java.lang.Character> 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.