1 /* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
2  * Use of this file is governed by the BSD 3-clause license that
3  * can be found in the LICENSE.txt file in the project root.
4  */
5 
6 #pragma once
7 
8 #include "tree/ParseTree.h"
9 
10 namespace antlr4 {
11 
12   /** A rule context is a record of a single rule invocation.
13    *
14    *  We form a stack of these context objects using the parent
15    *  pointer. A parent pointer of null indicates that the current
16    *  context is the bottom of the stack. The ParserRuleContext subclass
17    *  as a children list so that we can turn this data structure into a
18    *  tree.
19    *
20    *  The root node always has a null pointer and invokingState of -1.
21    *
22    *  Upon entry to parsing, the first invoked rule function creates a
23    *  context object (asubclass specialized for that rule such as
24    *  SContext) and makes it the root of a parse tree, recorded by field
25    *  Parser._ctx.
26    *
27    *  public final SContext s() throws RecognitionException {
28    *      SContext _localctx = new SContext(_ctx, getState()); <-- create new node
29    *      enterRule(_localctx, 0, RULE_s);                     <-- push it
30    *      ...
31    *      exitRule();                                          <-- pop back to _localctx
32    *      return _localctx;
33    *  }
34    *
35    *  A subsequent rule invocation of r from the start rule s pushes a
36    *  new context object for r whose parent points at s and use invoking
37    *  state is the state with r emanating as edge label.
38    *
39    *  The invokingState fields from a context object to the root
40    *  together form a stack of rule indication states where the root
41    *  (bottom of the stack) has a -1 sentinel value. If we invoke start
42    *  symbol s then call r1, which calls r2, the  would look like
43    *  this:
44    *
45    *     SContext[-1]   <- root node (bottom of the stack)
46    *     R1Context[p]   <- p in rule s called r1
47    *     R2Context[q]   <- q in rule r1 called r2
48    *
49    *  So the top of the stack, _ctx, represents a call to the current
50    *  rule and it holds the return address from another rule that invoke
51    *  to this rule. To invoke a rule, we must always have a current context.
52    *
53    *  The parent contexts are useful for computing lookahead sets and
54    *  getting error information.
55    *
56    *  These objects are used during parsing and prediction.
57    *  For the special case of parsers, we use the subclass
58    *  ParserRuleContext.
59    *
60    *  @see ParserRuleContext
61    */
62   class ANTLR4CPP_PUBLIC RuleContext : public tree::ParseTree {
63   public:
64     /// What state invoked the rule associated with this context?
65     /// The "return address" is the followState of invokingState
66     /// If parent is null, this should be -1 and this context object represents the start rule.
67     size_t invokingState;
68 
69     RuleContext();
70     RuleContext(RuleContext *parent, size_t invokingState);
71 
72     virtual int depth();
73 
74     /// A context is empty if there is no invoking state; meaning nobody called current context.
75     virtual bool isEmpty();
76 
77     // satisfy the ParseTree / SyntaxTree interface
78 
79     virtual misc::Interval getSourceInterval() override;
80 
81     virtual std::string getText() override;
82 
83     virtual size_t getRuleIndex() const;
84 
85     /** For rule associated with this parse tree internal node, return
86      *  the outer alternative number used to match the input. Default
87      *  implementation does not compute nor store this alt num. Create
88      *  a subclass of ParserRuleContext with backing field and set
89      *  option contextSuperClass.
90      *  to set it.
91      *
92      *  @since 4.5.3
93      */
94     virtual size_t getAltNumber() const;
95 
96     /** Set the outer alternative number for this context node. Default
97      *  implementation does nothing to avoid backing field overhead for
98      *  trees that don't need it.  Create
99      *  a subclass of ParserRuleContext with backing field and set
100      *  option contextSuperClass.
101      *
102      *  @since 4.5.3
103      */
104     virtual void setAltNumber(size_t altNumber);
105 
106     virtual antlrcpp::Any accept(tree::ParseTreeVisitor *visitor) override;
107 
108     /// <summary>
109     /// Print out a whole tree, not just a node, in LISP format
110     ///  (root child1 .. childN). Print just a node if this is a leaf.
111     ///  We have to know the recognizer so we can get rule names.
112     /// </summary>
113     virtual std::string toStringTree(Parser *recog, bool pretty = false) override;
114 
115     /// <summary>
116     /// Print out a whole tree, not just a node, in LISP format
117     ///  (root child1 .. childN). Print just a node if this is a leaf.
118     /// </summary>
119     virtual std::string toStringTree(std::vector<std::string> &ruleNames, bool pretty = false);
120 
121     virtual std::string toStringTree(bool pretty = false) override;
122     virtual std::string toString() override;
123     std::string toString(Recognizer *recog);
124     std::string toString(const std::vector<std::string> &ruleNames);
125 
126     // recog null unless ParserRuleContext, in which case we use subclass toString(...)
127     std::string toString(Recognizer *recog, RuleContext *stop);
128 
129     virtual std::string toString(const std::vector<std::string> &ruleNames, RuleContext *stop);
130 
131     bool operator == (const RuleContext &other) { return this == &other; } // Simple address comparison.
132 
133   private:
134     void InitializeInstanceFields();
135   };
136 
137 } // namespace antlr4
138