001/*
002 * Copyright (C) 2009-2011 Mathias Doenitz
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.parboiled;
018
019import org.parboiled.buffers.InputBuffer;
020import org.parboiled.errors.ParseError;
021import org.parboiled.matchers.Matcher;
022import org.parboiled.parserunners.RecoveringParseRunner;
023import org.parboiled.parserunners.ReportingParseRunner;
024import org.parboiled.support.IndexRange;
025import org.parboiled.support.MatcherPath;
026import org.parboiled.support.Position;
027import org.parboiled.support.ValueStack;
028import org.parboiled.matchers.Matcher;
029import org.parboiled.parserunners.RecoveringParseRunner;
030import org.parboiled.parserunners.ReportingParseRunner;
031import org.parboiled.support.IndexRange;
032import org.parboiled.support.MatcherPath;
033import org.parboiled.support.Position;
034import org.parboiled.support.ValueStack;
035
036import java.util.List;
037
038/**
039 * A Context object is available to parser actions methods during their runtime and provides various support functionalities.
040 */
041public interface Context<V> {
042
043    /**
044     * Returns the parent context, i.e. the context for the currently running parent matcher.
045     *
046     * @return the parent context
047     */
048    Context<V> getParent();
049
050    /**
051     * Returns the InputBuffer the parser is currently running against
052     *
053     * @return the InputBuffer
054     */
055    InputBuffer getInputBuffer();
056
057    /**
058     * Returns the Matcher of this context or null, if this context is not valid anymore.
059     *
060     * @return the matcher
061     */
062    Matcher getMatcher();
063
064    /**
065     * Returns the index into the underlying input buffer where the matcher of this context started its match.
066     *
067     * @return the start index
068     */
069    int getStartIndex();
070
071    /**
072     * Returns the current index in the input buffer.
073     *
074     * @return the current index
075     */
076    int getCurrentIndex();
077
078    /**
079     * Returns the character at the current index..
080     *
081     * @return the current character
082     */
083    char getCurrentChar();
084
085    /**
086     * Returns the list of parse errors for the entire parsing run.
087     *
088     * @return the list of parse errors
089     */
090    List<ParseError> getParseErrors();
091
092    /**
093     * Returns the {@link MatcherPath} to the currently running matcher.
094     *
095     * @return the path
096     */
097    MatcherPath getPath();
098
099    /**
100     * Returns the current matcher level, with 0 being the root level, 1 being one level below the root and so on.
101     *
102     * @return the current matcher level
103     */
104    int getLevel();
105
106    /**
107     * <p>Returns true if fast string matching is enabled for this parsing run.</p>
108     * <p>Fast string matching "short-circuits" the default practice of treating string rules as simple Sequence of
109     * character rules. When fast string matching is enabled strings are matched at once, without relying on inner
110     * CharacterMatchers. Even though this can lead to significant increases of parsing performance it does not play
111     * well with error reporting and recovery, which relies on character level matches.
112     * Therefore the {@link ReportingParseRunner} and {@link RecoveringParseRunner} implementations only enable fast
113     * string matching during their basic first parsing run and disable it once the input has proven to contain errors.
114     * </p>
115     *
116     * @return true if fast string matching is enabled during the current parsing run
117     */
118    boolean fastStringMatching();
119
120    /**
121     * Returns the parse tree subnodes already created in the current context scope.
122     * Note that the returned list is immutable.
123     *
124     * @return the parse tree subnodes already created in the current context scope
125     */
126    List<Node<V>> getSubNodes();
127
128    /**
129     * Determines if the current rule is running somewhere underneath a Test/TestNot rule.
130     *
131     * @return true if the current context has a parent which corresponds to a Test/TestNot rule
132     */
133    boolean inPredicate();
134    
135    /**
136     * Determines if the action calling this method is run during the resynchronization phase of an error recovery.
137     *
138     * @return true if the action calling this method is run during the resynchronization phase of an error recovery
139     */
140    boolean inErrorRecovery();
141
142    /**
143     * Determines if the current context is for or below a rule marked @SuppressNode or below one
144     * marked @SuppressSubnodes.
145     *
146     * @return true or false
147     */
148    boolean isNodeSuppressed();
149
150    /**
151     * Determines if this context or any sub node recorded a parse error.
152     *
153     * @return true if this context or any sub node recorded a parse error
154     */
155    boolean hasError();
156
157    /**
158     * <p>Returns the input text matched by the rule immediately preceding the action expression that is currently
159     * being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first
160     * position in this Sequence.</p>
161     *
162     * @return the input text matched by the immediately preceding subcontext
163     */
164    String getMatch();
165
166    /**
167     * <p>Returns the first character of the input text matched by the rule immediately preceding the action
168     * expression that is currently being evaluated. This call can only be used in actions that are part of a Sequence
169     * rule and are not at first position in this Sequence.</p>
170     * <p>If the immediately preceding rule did not match anything this method throws a GrammarException. If you need
171     * to able to handle that case use the getMatch() method.</p>
172     *
173     * @return the input text matched by the immediately preceding subcontext
174     */
175    char getFirstMatchChar();
176
177    /**
178     * <p>Returns the start index of the rule immediately preceding the action expression that is currently
179     * being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first
180     * position in this Sequence.</p>
181     *
182     * @return the start index of the context immediately preceding current action
183     */
184    int getMatchStartIndex();
185
186    /**
187     * <p>Returns the end index of the rule immediately preceding the action expression that is currently
188     * being evaluated. This call can only be used in actions that are part of a Sequence rule and are not at first
189     * position in this Sequence.</p>
190     *
191     * @return the end index of the context immediately preceding current action, i.e. the index of the character
192     *         immediately following the last matched character
193     */
194    int getMatchEndIndex();
195
196    /**
197     * <p>Returns the number of characters matched by the rule immediately preceding the action expression that is
198     * currently being evaluated. This call can only be used in actions that are part of a Sequence rule and are not
199     * at first position in this Sequence.</p>
200     * 
201     * @return the number of characters matched
202     */
203    int getMatchLength();
204    
205    /**
206     * <p>Returns the current position in the underlying {@link InputBuffer} as a
207     * {@link Position} instance.</p>
208     * 
209     * @return the current position in the underlying inputbuffer
210     */
211    Position getPosition();
212    
213    /**
214     * Creates a new {@link IndexRange} instance covering the input text matched by the rule immediately preceding the
215     * action expression that is currently being evaluated. This call can only be used in actions that are part of a
216     * Sequence rule and are not at first position in this Sequence.
217     *  
218     * @return a new IndexRange instance
219     */
220    IndexRange getMatchRange();
221    
222    /**
223     * Returns the value stack instance used during this parsing run.
224     *
225     * @return the value stack
226     */
227    ValueStack<V> getValueStack();
228}
229