contrib/llvm/tools/lldb/include/lldb/Expression/ExpressionParser.h

   1 //===-- ExpressionParser.h --------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_ExpressionParser_h_
  11 #define liblldb_ExpressionParser_h_
  12
  13 #include "lldb/Utility/CompletionRequest.h"
  14 #include "lldb/Utility/Status.h"
  15 #include "lldb/lldb-private-enumerations.h"
  16 #include "lldb/lldb-public.h"
  17
  18 namespace lldb_private {
  19
  20 class IRExecutionUnit;
  21
  22 //----------------------------------------------------------------------
  23 /// @class ExpressionParser ExpressionParser.h
  24 /// "lldb/Expression/ExpressionParser.h" Encapsulates an instance of a
  25 /// compiler that can parse expressions.
  26 ///
  27 /// ExpressionParser is the base class for llvm based Expression parsers.
  28 //----------------------------------------------------------------------
  29 class ExpressionParser {
  30 public:
  31   //------------------------------------------------------------------
  32   /// Constructor
  33   ///
  34   /// Initializes class variables.
  35   ///
  36   /// @param[in] exe_scope,
  37   ///     If non-NULL, an execution context scope that can help to
  38   ///     correctly create an expression with a valid process for
  39   ///     optional tuning Objective-C runtime support. Can be NULL.
  40   ///
  41   /// @param[in] expr
  42   ///     The expression to be parsed.
  43   //------------------------------------------------------------------
  44   ExpressionParser(ExecutionContextScope *exe_scope, Expression &expr,
  45                    bool generate_debug_info)
  46       : m_expr(expr), m_generate_debug_info(generate_debug_info) {}
  47
  48   //------------------------------------------------------------------
  49   /// Destructor
  50   //------------------------------------------------------------------
  51   virtual ~ExpressionParser(){};
  52
  53   //------------------------------------------------------------------
  54   /// Attempts to find possible command line completions for the given
  55   /// expression.
  56   ///
  57   /// @param[out] request
  58   ///     The completion request to fill out. The completion should be a string
  59   ///     that would complete the current token at the cursor position.
  60   ///     Note that the string in the list replaces the current token
  61   ///     in the command line.
  62   ///
  63   /// @param[in] line
  64   ///     The line with the completion cursor inside the expression as a string.
  65   ///     The first line in the expression has the number 0.
  66   ///
  67   /// @param[in] pos
  68   ///     The character position in the line with the completion cursor.
  69   ///     If the value is 0, then the cursor is on top of the first character
  70   ///     in the line (i.e. the user has requested completion from the start of
  71   ///     the expression).
  72   ///
  73   /// @param[in] typed_pos
  74   ///     The cursor position in the line as typed by the user. If the user
  75   ///     expression has not been transformed in some form (e.g. wrapping it
  76   ///     in a function body for C languages), then this is equal to the
  77   ///     'pos' parameter. The semantics of this value are otherwise equal to
  78   ///     'pos' (e.g. a value of 0 means the cursor is at start of the
  79   ///     expression).
  80   ///
  81   /// @return
  82   ///     True if we added any completion results to the output;
  83   ///     false otherwise.
  84   //------------------------------------------------------------------
  85   virtual bool Complete(CompletionRequest &request, unsigned line, unsigned pos,
  86                         unsigned typed_pos) = 0;
  87
  88   //------------------------------------------------------------------
  89   /// Parse a single expression and convert it to IR using Clang.  Don't wrap
  90   /// the expression in anything at all.
  91   ///
  92   /// @param[in] diagnostic_manager
  93   ///     The diagnostic manager in which to store the errors and warnings.
  94   ///
  95   /// @return
  96   ///     The number of errors encountered during parsing.  0 means
  97   ///     success.
  98   //------------------------------------------------------------------
  99   virtual unsigned Parse(DiagnosticManager &diagnostic_manager) = 0;
 100
 101   //------------------------------------------------------------------
 102   /// Try to use the FixIts in the diagnostic_manager to rewrite the
 103   /// expression.  If successful, the rewritten expression is stored in the
 104   /// diagnostic_manager, get it out with GetFixedExpression.
 105   ///
 106   /// @param[in] diagnostic_manager
 107   ///     The diagnostic manager containing fixit's to apply.
 108   ///
 109   /// @return
 110   ///     \b true if the rewrite was successful, \b false otherwise.
 111   //------------------------------------------------------------------
 112   virtual bool RewriteExpression(DiagnosticManager &diagnostic_manager) {
 113     return false;
 114   }
 115
 116   //------------------------------------------------------------------
 117   /// Ready an already-parsed expression for execution, possibly evaluating it
 118   /// statically.
 119   ///
 120   /// @param[out] func_addr
 121   ///     The address to which the function has been written.
 122   ///
 123   /// @param[out] func_end
 124   ///     The end of the function's allocated memory region.  (func_addr
 125   ///     and func_end do not delimit an allocated region; the allocated
 126   ///     region may begin before func_addr.)
 127   ///
 128   /// @param[in] execution_unit_sp
 129   ///     After parsing, ownership of the execution unit for
 130   ///     for the expression is handed to this shared pointer.
 131   ///
 132   /// @param[in] exe_ctx
 133   ///     The execution context to write the function into.
 134   ///
 135   /// @param[out] can_interpret
 136   ///     Set to true if the expression could be interpreted statically;
 137   ///     untouched otherwise.
 138   ///
 139   /// @param[in] execution_policy
 140   ///     Determines whether the expression must be JIT-compiled, must be
 141   ///     evaluated statically, or whether this decision may be made
 142   ///     opportunistically.
 143   ///
 144   /// @return
 145   ///     An error code indicating the success or failure of the operation.
 146   ///     Test with Success().
 147   //------------------------------------------------------------------
 148   virtual Status
 149   PrepareForExecution(lldb::addr_t &func_addr, lldb::addr_t &func_end,
 150                       std::shared_ptr<IRExecutionUnit> &execution_unit_sp,
 151                       ExecutionContext &exe_ctx, bool &can_interpret,
 152                       lldb_private::ExecutionPolicy execution_policy) = 0;
 153
 154   bool GetGenerateDebugInfo() const { return m_generate_debug_info; }
 155
 156 protected:
 157   Expression &m_expr; ///< The expression to be parsed
 158   bool m_generate_debug_info;
 159 };
 160 }
 161
 162 #endif // liblldb_ExpressionParser_h_