org.parboiled
Class MatcherContext<V>

java.lang.Object
  extended by org.parboiled.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 Summary
MatcherContext(InputBuffer inputBuffer, ValueStack<V> valueStack, java.util.List<ParseError> parseErrors, MatchHandler matchHandler, Matcher matcher, boolean fastStringMatching)
          Initializes a new root MatcherContext.
 
Method Summary
 void advanceIndex(int delta)
           
 void clearNodeSuppression()
           
 void createNode()
           
 boolean fastStringMatching()
          Returns true if fast string matching is enabled for this parsing run.
 MatcherContext<V> getBasicSubContext()
           
 char getCurrentChar()
          Returns the character at the current index..
 int getCurrentIndex()
          Returns the current index in the input buffer.
 char getFirstMatchChar()
          Returns the first character of the input text matched by the context immediately preceding the action expression that is currently being evaluated.
 InputBuffer getInputBuffer()
          Returns the InputBuffer the parser is currently running against
 int getIntTag()
           
 int getLevel()
          Returns the current matcher level, with 0 being the root level, 1 being one level below the root and so on.
 java.lang.String getMatch()
          Returns the input text matched by the context immediately preceding the action expression that is currently being evaluated.
 int getMatchEndIndex()
          Returns the end index of the context immediately preceding the action expression that is currently being evaluated.
 Matcher getMatcher()
          Returns the Matcher of this context or null, if this context is not valid anymore.
 int getMatchStartIndex()
          Returns the start index of the context immediately preceding the action expression that is currently being evaluated.
 Node<V> getNode()
           
 MatcherContext<V> getParent()
          Returns the parent context, i.e.
 java.util.List<ParseError> getParseErrors()
          Returns the list of parse errors for the entire parsing run.
 MatcherPath getPath()
          Returns the MatcherPath to the currently running matcher.
 int getStartIndex()
          Returns the index into the underlying input buffer where the matcher of this context started its match.
 MatcherContext<V> getSubContext(Matcher matcher)
           
 java.util.List<Node<V>> getSubNodes()
          Returns the parse tree subnodes already created in the current context scope.
 ValueStack<V> getValueStack()
          Returns the value stack instance used during this parsing run.
 boolean hasError()
          Returns true if this context or any sub node recorded a parse error.
 boolean inPredicate()
          Returns true if the current rule is running somewhere underneath a Test/TestNot rule.
 boolean isNodeSuppressed()
          Returns true if the current context is for or below a rule marked @SuppressNode or below one marked @SuppressSubnodes.
 void markError()
           
 boolean runMatcher()
           
 void setCurrentIndex(int currentIndex)
           
 void setIntTag(int intTag)
           
 void setMatcher(Matcher matcher)
           
 void setStartIndex(int startIndex)
           
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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

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 java.util.List<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
Returns true 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

isNodeSuppressed

public boolean isNodeSuppressed()
Description copied from interface: Context
Returns true 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
Returns true 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 context 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 context 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 context 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 context 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

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)

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()

clearNodeSuppression

public void clearNodeSuppression()

createNode

public void createNode()

getBasicSubContext

public final MatcherContext<V> getBasicSubContext()

getSubContext

public final MatcherContext<V> getSubContext(Matcher matcher)

runMatcher

public boolean runMatcher()