gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/RuleContext.h

   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