gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/atn/LexerActionExecutor.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 "CharStream.h"
   9 #include "atn/LexerAction.h"
  10
  11 namespace antlr4 {
  12 namespace atn {
  13
  14   /// Represents an executor for a sequence of lexer actions which traversed during
  15   /// the matching operation of a lexer rule (token).
  16   ///
  17   /// <para>The executor tracks position information for position-dependent lexer actions
  18   /// efficiently, ensuring that actions appearing only at the end of the rule do
  19   /// not cause bloating of the <seealso cref="DFA"/> created for the lexer.</para>
  20   class ANTLR4CPP_PUBLIC LexerActionExecutor : public std::enable_shared_from_this<LexerActionExecutor> {
  21   public:
  22     /// <summary>
  23     /// Constructs an executor for a sequence of <seealso cref="LexerAction"/> actions. </summary>
  24     /// <param name="lexerActions"> The lexer actions to execute. </param>
  25     LexerActionExecutor(const std::vector<Ref<LexerAction>> &lexerActions);
  26     virtual ~LexerActionExecutor();
  27
  28     /// <summary>
  29     /// Creates a <seealso cref="LexerActionExecutor"/> which executes the actions for
  30     /// the input {@code lexerActionExecutor} followed by a specified
  31     /// {@code lexerAction}.
  32     /// </summary>
  33     /// <param name="lexerActionExecutor"> The executor for actions already traversed by
  34     /// the lexer while matching a token within a particular
  35     /// <seealso cref="LexerATNConfig"/>. If this is {@code null}, the method behaves as
  36     /// though it were an empty executor. </param>
  37     /// <param name="lexerAction"> The lexer action to execute after the actions
  38     /// specified in {@code lexerActionExecutor}.
  39     /// </param>
  40     /// <returns> A <seealso cref="LexerActionExecutor"/> for executing the combine actions
  41     /// of {@code lexerActionExecutor} and {@code lexerAction}. </returns>
  42     static Ref<LexerActionExecutor> append(Ref<LexerActionExecutor> const& lexerActionExecutor,
  43                                            Ref<LexerAction> const& lexerAction);
  44
  45     /// <summary>
  46     /// Creates a <seealso cref="LexerActionExecutor"/> which encodes the current offset
  47     /// for position-dependent lexer actions.
  48     ///
  49     /// <para>Normally, when the executor encounters lexer actions where
  50     /// <seealso cref="LexerAction#isPositionDependent"/> returns {@code true}, it calls
  51     /// <seealso cref="IntStream#seek"/> on the input <seealso cref="CharStream"/> to set the input
  52     /// position to the <em>end</em> of the current token. This behavior provides
  53     /// for efficient DFA representation of lexer actions which appear at the end
  54     /// of a lexer rule, even when the lexer rule matches a variable number of
  55     /// characters.</para>
  56     ///
  57     /// <para>Prior to traversing a match transition in the ATN, the current offset
  58     /// from the token start index is assigned to all position-dependent lexer
  59     /// actions which have not already been assigned a fixed offset. By storing
  60     /// the offsets relative to the token start index, the DFA representation of
  61     /// lexer actions which appear in the middle of tokens remains efficient due
  62     /// to sharing among tokens of the same length, regardless of their absolute
  63     /// position in the input stream.</para>
  64     ///
  65     /// <para>If the current executor already has offsets assigned to all
  66     /// position-dependent lexer actions, the method returns {@code this}.</para>
  67     /// </summary>
  68     /// <param name="offset"> The current offset to assign to all position-dependent
  69     /// lexer actions which do not already have offsets assigned.
  70     /// </param>
  71     /// <returns> A <seealso cref="LexerActionExecutor"/> which stores input stream offsets
  72     /// for all position-dependent lexer actions. </returns>
  73     virtual Ref<LexerActionExecutor> fixOffsetBeforeMatch(int offset);
  74
  75     /// <summary>
  76     /// Gets the lexer actions to be executed by this executor. </summary>
  77     /// <returns> The lexer actions to be executed by this executor. </returns>
  78     virtual std::vector<Ref<LexerAction>> getLexerActions() const;
  79
  80     /// <summary>
  81     /// Execute the actions encapsulated by this executor within the context of a
  82     /// particular <seealso cref="Lexer"/>.
  83     ///
  84     /// <para>This method calls <seealso cref="IntStream#seek"/> to set the position of the
  85     /// {@code input} <seealso cref="CharStream"/> prior to calling
  86     /// <seealso cref="LexerAction#execute"/> on a position-dependent action. Before the
  87     /// method returns, the input position will be restored to the same position
  88     /// it was in when the method was invoked.</para>
  89     /// </summary>
  90     /// <param name="lexer"> The lexer instance. </param>
  91     /// <param name="input"> The input stream which is the source for the current token.
  92     /// When this method is called, the current <seealso cref="IntStream#index"/> for
  93     /// {@code input} should be the start of the following token, i.e. 1
  94     /// character past the end of the current token. </param>
  95     /// <param name="startIndex"> The token start index. This value may be passed to
  96     /// <seealso cref="IntStream#seek"/> to set the {@code input} position to the beginning
  97     /// of the token. </param>
  98     virtual void execute(Lexer *lexer, CharStream *input, size_t startIndex);
  99
 100     virtual size_t hashCode() const;
 101     virtual bool operator == (const LexerActionExecutor &obj) const;
 102     virtual bool operator != (const LexerActionExecutor &obj) const;
 103
 104   private:
 105     const std::vector<Ref<LexerAction>> _lexerActions;
 106
 107     /// Caches the result of <seealso cref="#hashCode"/> since the hash code is an element
 108     /// of the performance-critical <seealso cref="LexerATNConfig#hashCode"/> operation.
 109     const size_t _hashCode;
 110
 111     size_t generateHashCode() const;
 112   };
 113
 114 } // namespace atn
 115 } // namespace antlr4