Line data    Source code

       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           0 :   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