Class SimpleParser

java.lang.Object
software.amazon.smithy.utils.SimpleParser

public class SimpleParser extends 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 final char
     
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a new SimpleParser and sets the expression to parse.
    SimpleParser(CharSequence input, int maxNestingLevel)
    Creates a new SimpleParser and sets the expression to parse.
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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).
    final int
    Gets the current 1-based column number of the parser.
    void
    Skips over the remaining characters on a line but does not consume the newline character (\n or \r\n).
    final int
    Deprecated.
    final int
    Reads a lexeme from the expression while the given predicate matches each peeked character.
    final void
    Decreases the current nesting level of the parser.
    final boolean
    eof()
    Checks if the parser has reached the end of the expression.
    final char
    expect(char token)
    Expects that the next character is the given character and consumes it.
    final char
    expect(char... tokens)
    Expects that the next character is one of a fixed set of possible characters.
    final String
    Deprecated.
    final void
    Increases the current nesting level of the parser.
    Gets the input being parsed as a CharSequence.
    final int
    Gets the current 1-based line number of the parser.
    int
    Gets the current 0-based nesting level of the parser.
    final char
    Returns the current character of the expression, but does not consume it.
    final char
    peek(int offset)
    Returns the current character of the expression + offset characters, but does not consume it.
    final String
    Peeks the next character and returns [EOF] if the next character is past the end of the expression.
    final int
    Gets the current 0-based position of the parser.
    final void
    rewind(int position, int line, int column)
     
    void
    Skips a single character while tracking lines and columns.
    final 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').
    syntax(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
  • Field Details

  • Constructor Details

    • SimpleParser

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

      public SimpleParser(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 Details

    • input

      public final CharSequence input()
      Gets the input being parsed as a CharSequence.
      Returns:
      Returns the input being parsed.
    • expression

      @Deprecated public final 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 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 RuntimeException syntax(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:
      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 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 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 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(Predicate<Character> predicate)
      Deprecated.
    • consumeWhile

      public final int consumeWhile(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:
      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.