Package org.parboiled

Class MatcherContext<V>

  • All Implemented Interfaces:
    Context<V>
    public class MatcherContext<V>
extends java.lang.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 Detail

      • MatcherContext

        public MatcherContext​(InputBuffer inputBuffer,
                      ValueStack<V> valueStack,
                      java.util.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 Detail

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.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 java.util.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

      • 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 java.lang.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 java.lang.Boolean hasMismatched()

      • memoizeMismatch

        public void memoizeMismatch()

      • createNode

        public void createNode()

      • runMatcher

        public boolean runMatcher()