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 Summary

Constructors

Constructor and Description
MatcherContext(InputBuffer inputBuffer, ValueStack<V> valueStack, List<ParseError> parseErrors, MatchHandler matchHandler, Matcher matcher, boolean fastStringMatching) Initializes a new root MatcherContext.

Method Summary

Methods

Modifier and Type	Method and Description
void	advanceIndex(int delta)
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 rule 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.
String	getMatch() Returns the input text matched by the rule immediately preceding the action expression that is currently being evaluated.
int	getMatchEndIndex() Returns the end index of the rule 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	getMatchLength() Returns the number of characters matched by the rule immediately preceding the action expression that is currently being evaluated.
IndexRange	getMatchRange() Creates a new IndexRange instance covering the input text matched by the rule immediately preceding the action expression that is currently being evaluated.
int	getMatchStartIndex() Returns the start index of the rule immediately preceding the action expression that is currently being evaluated.
Node<V>	getNode()
MatcherContext<V>	getParent() Returns the parent context, i.e.
List<ParseError>	getParseErrors() Returns the list of parse errors for the entire parsing run.
MatcherPath	getPath() Returns the MatcherPath to the currently running matcher.
Position	getPosition() Returns the current position in the underlying InputBuffer as a Position instance.
int	getStartIndex() Returns the index into the underlying input buffer where the matcher of this context started its match.
MatcherContext<V>	getSubContext(Matcher matcher)
ImmutableLinkedList<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() Determines if this context or any sub node recorded a parse error.
boolean	inErrorRecovery() Determines if the action calling this method is run during the resynchronization phase of an error recovery.
boolean	inPredicate() Determines if the current rule is running somewhere underneath a Test/TestNot rule.
boolean	isNodeSuppressed() Determines 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	setInErrorRecovery(boolean flag)
void	setIntTag(int intTag)
void	setMatcher(Matcher matcher)
void	setStartIndex(int startIndex)
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,
              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 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()

createNode

public void createNode()

getBasicSubContext

public final MatcherContext<V> getBasicSubContext()

getSubContext

public final MatcherContext<V> getSubContext(Matcher matcher)

runMatcher

public boolean runMatcher()