Package org.parboiled

Class MatcherContext<V>

java.lang.Object
org.parboiled.MatcherContext<V>
All Implemented Interfaces:
Context<V>
public class MatcherContext<V> extends Object implements Context<V>

The Context implementation orchestrating most of the matching process.

The parsing process works as following: After the rule tree (which is in fact a directed and potentially even cyclic graph of Matcher instances) has been created a root MatcherContext is instantiated for the root rule (Matcher). A subsequent call to runMatcher() starts the parsing process.

The MatcherContext delegates to a given MatchHandler to call Matcher.match(MatcherContext), passing itself to the Matcher which executes its logic, potentially calling sub matchers. For each sub matcher the matcher creates/initializes a subcontext with Matcher.getSubContext(MatcherContext) and then calls runMatcher() on it.

This basically creates a stack of MatcherContexts, each corresponding to their rule matchers. The MatcherContext instances serve as companion objects to the matchers, providing them with support for building the parse tree nodes, keeping track of input locations and error recovery.

At each point during the parsing process the matchers and action expressions have access to the current MatcherContext and all "open" parent MatcherContexts through the getParent() chain.

For performance reasons subcontext instances are reused instead of being recreated. If a MatcherContext instance returns null on a getMatcher() call it has been retired (is invalid) and is waiting to be reinitialized with a new Matcher by its parent

  • Constructor Details

    • MatcherContext

      public MatcherContext(InputBuffer inputBuffer, ValueStack<V> valueStack, List<ParseError> parseErrors, MatchHandler matchHandler, Matcher matcher, boolean fastStringMatching)
      Initializes a new root MatcherContext.
      Parameters:
      inputBuffer - the InputBuffer for the parsing run
      valueStack - the ValueStack instance to use for the parsing run
      parseErrors - the parse error list to create ParseError objects in
      matchHandler - the MatcherHandler to use for the parsing run
      matcher - the root matcher
      fastStringMatching -

      Fast string matching "short-circuits" the default practice of treating string rules as simple Sequence of character rules. When fast string matching is enabled strings are matched at once, without relying on inner CharacterMatchers. Even though this can lead to significant increases of parsing performance it does not play well with error reporting and recovery, which relies on character level matches. Therefore the ReportingParseRunner and RecoveringParseRunner implementations only enable fast string matching during their basic first parsing run and disable it once the input has proven to contain errors.

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getParent

      public MatcherContext<V> getParent()
      Description copied from interface: Context
      Returns the parent context, i.e. the context for the currently running parent matcher.
      Specified by:
      getParent in interface Context<V>
      Returns:
      the parent context

    • getInputBuffer

      public InputBuffer getInputBuffer()
      Description copied from interface: Context
      Returns the InputBuffer the parser is currently running against
      Specified by:
      getInputBuffer in interface Context<V>
      Returns:
      the InputBuffer

    • getStartIndex

      public int getStartIndex()
      Description copied from interface: Context
      Returns the index into the underlying input buffer where the matcher of this context started its match.
      Specified by:
      getStartIndex in interface Context<V>
      Returns:
      the start index

    • getMatcher

      public Matcher getMatcher()
      Description copied from interface: Context
      Returns the Matcher of this context or null, if this context is not valid anymore.
      Specified by:
      getMatcher in interface Context<V>
      Returns:
      the matcher

    • getCurrentChar

      public char getCurrentChar()
      Description copied from interface: Context
      Returns the character at the current index..
      Specified by:
      getCurrentChar in interface Context<V>
      Returns:
      the current character

    • getParseErrors

      public List<ParseError> getParseErrors()
      Description copied from interface: Context
      Returns the list of parse errors for the entire parsing run.
      Specified by:
      getParseErrors in interface Context<V>
      Returns:
      the list of parse errors

    • getCurrentIndex

      public int getCurrentIndex()
      Description copied from interface: Context
      Returns the current index in the input buffer.
      Specified by:
      getCurrentIndex in interface Context<V>
      Returns:
      the current index

    • getPath

      public MatcherPath getPath()
      Description copied from interface: Context
      Returns the MatcherPath to the currently running matcher.
      Specified by:
      getPath in interface Context<V>
      Returns:
      the path

    • getLevel

      public int getLevel()
      Description copied from interface: Context
      Returns the current matcher level, with 0 being the root level, 1 being one level below the root and so on.
      Specified by:
      getLevel in interface Context<V>
      Returns:
      the current matcher level

    • fastStringMatching

      public boolean fastStringMatching()
      Description copied from interface: Context

      Returns true if fast string matching is enabled for this parsing run.

      Fast string matching "short-circuits" the default practice of treating string rules as simple Sequence of character rules. When fast string matching is enabled strings are matched at once, without relying on inner CharacterMatchers. Even though this can lead to significant increases of parsing performance it does not play well with error reporting and recovery, which relies on character level matches. Therefore the ReportingParseRunner and RecoveringParseRunner implementations only enable fast string matching during their basic first parsing run and disable it once the input has proven to contain errors.

      Specified by:
      fastStringMatching in interface Context<V>
      Returns:
      true if fast string matching is enabled during the current parsing run

    • getSubNodes

      public ImmutableLinkedList<Node<V>> getSubNodes()
      Description copied from interface: Context
      Returns the parse tree subnodes already created in the current context scope. Note that the returned list is immutable.
      Specified by:
      getSubNodes in interface Context<V>
      Returns:
      the parse tree subnodes already created in the current context scope

    • inPredicate

      public boolean inPredicate()
      Description copied from interface: Context
      Determines if the current rule is running somewhere underneath a Test/TestNot rule.
      Specified by:
      inPredicate in interface Context<V>
      Returns:
      true if the current context has a parent which corresponds to a Test/TestNot rule

    • inErrorRecovery

      public boolean inErrorRecovery()
      Description copied from interface: Context
      Determines if the action calling this method is run during the resynchronization phase of an error recovery.
      Specified by:
      inErrorRecovery in interface Context<V>
      Returns:
      true if the action calling this method is run during the resynchronization phase of an error recovery

    • isNodeSuppressed

      public boolean isNodeSuppressed()
      Description copied from interface: Context
      Determines if the current context is for or below a rule marked @SuppressNode or below one marked @SuppressSubnodes.
      Specified by:
      isNodeSuppressed in interface Context<V>
      Returns:
      true or false

    • hasError

      public boolean hasError()
      Description copied from interface: Context
      Determines if this context or any sub node recorded a parse error.
      Specified by:
      hasError in interface Context<V>
      Returns:
      true if this context or any sub node recorded a parse error

    • getMatch

      public String getMatch()
      Description copied from interface: Context

      Returns the input text matched by the rule immediately preceding the action expression that is currently being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first position in this Sequence.

      Specified by:
      getMatch in interface Context<V>
      Returns:
      the input text matched by the immediately preceding subcontext

    • getFirstMatchChar

      public char getFirstMatchChar()
      Description copied from interface: Context

      Returns the first character of the input text matched by the rule immediately preceding the action expression that is currently being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first position in this Sequence.

      If the immediately preceding rule did not match anything this method throws a GrammarException. If you need to able to handle that case use the getMatch() method.

      Specified by:
      getFirstMatchChar in interface Context<V>
      Returns:
      the input text matched by the immediately preceding subcontext

    • getMatchStartIndex

      public int getMatchStartIndex()
      Description copied from interface: Context

      Returns the start index of the rule immediately preceding the action expression that is currently being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first position in this Sequence.

      Specified by:
      getMatchStartIndex in interface Context<V>
      Returns:
      the start index of the context immediately preceding current action

    • getMatchEndIndex

      public int getMatchEndIndex()
      Description copied from interface: Context

      Returns the end index of the rule immediately preceding the action expression that is currently being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first position in this Sequence.

      Specified by:
      getMatchEndIndex in interface Context<V>
      Returns:
      the end index of the context immediately preceding current action, i.e. the index of the character immediately following the last matched character

    • getMatchLength

      public int getMatchLength()
      Description copied from interface: Context

      Returns the number of characters matched by the rule immediately preceding the action expression that is currently being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first position in this Sequence.

      Specified by:
      getMatchLength in interface Context<V>
      Returns:
      the number of characters matched

    • getPosition

      public Position getPosition()
      Description copied from interface: Context

      Returns the current position in the underlying InputBuffer as a Position instance.

      Specified by:
      getPosition in interface Context<V>
      Returns:
      the current position in the underlying inputbuffer

    • getMatchRange

      public IndexRange getMatchRange()
      Description copied from interface: Context
      Creates a new IndexRange instance covering the input text matched by the rule immediately preceding the action expression that is currently being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first position in this Sequence.
      Specified by:
      getMatchRange in interface Context<V>
      Returns:
      a new IndexRange instance

    • getValueStack

      public ValueStack<V> getValueStack()
      Description copied from interface: Context
      Returns the value stack instance used during this parsing run.
      Specified by:
      getValueStack in interface Context<V>
      Returns:
      the value stack

    • setMatcher

      public void setMatcher(Matcher matcher)

    • setStartIndex

      public void setStartIndex(int startIndex)

    • setCurrentIndex

      public void setCurrentIndex(int currentIndex)

    • setInErrorRecovery

      public void setInErrorRecovery(boolean flag)

    • advanceIndex

      public void advanceIndex(int delta)

    • getNode

      public Node<V> getNode()

    • getIntTag

      public int getIntTag()

    • setIntTag

      public void setIntTag(int intTag)

    • markError

      public void markError()

    • hasMismatched

      public Boolean hasMismatched()

    • memoizeMismatch

      public void memoizeMismatch()

    • createNode

      public void createNode()

    • getBasicSubContext

      public final MatcherContext<V> getBasicSubContext()

    • getSubContext

      public final MatcherContext<V> getSubContext(Matcher matcher)

    • runMatcher

      public boolean runMatcher()