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

   1 //===-- UserExpression.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_UserExpression_h_
  11 #define liblldb_UserExpression_h_
  12
  13 #include <memory>
  14 #include <string>
  15 #include <vector>
  16
  17 #include "lldb/Core/Address.h"
  18 #include "lldb/Expression/Expression.h"
  19 #include "lldb/Expression/Materializer.h"
  20 #include "lldb/Target/ExecutionContext.h"
  21 #include "lldb/Target/Target.h"
  22 #include "lldb/lldb-forward.h"
  23 #include "lldb/lldb-private.h"
  24
  25 namespace lldb_private {
  26
  27 //----------------------------------------------------------------------
  28 /// @class UserExpression UserExpression.h "lldb/Expression/UserExpression.h"
  29 /// Encapsulates a one-time expression for use in lldb.
  30 ///
  31 /// LLDB uses expressions for various purposes, notably to call functions
  32 /// and as a backend for the expr command.  UserExpression is a virtual base
  33 /// class that encapsulates the objects needed to parse and interpret or
  34 /// JIT an expression.  The actual parsing part will be provided by the specific
  35 /// implementations of UserExpression - which will be vended through the
  36 /// appropriate TypeSystem.
  37 //----------------------------------------------------------------------
  38 class UserExpression : public Expression {
  39 public:
  40   enum { kDefaultTimeout = 500000u };
  41
  42   //------------------------------------------------------------------
  43   /// Constructor
  44   ///
  45   /// @param[in] expr
  46   ///     The expression to parse.
  47   ///
  48   /// @param[in] expr_prefix
  49   ///     If non-nullptr, a C string containing translation-unit level
  50   ///     definitions to be included when the expression is parsed.
  51   ///
  52   /// @param[in] language
  53   ///     If not eLanguageTypeUnknown, a language to use when parsing
  54   ///     the expression.  Currently restricted to those languages
  55   ///     supported by Clang.
  56   ///
  57   /// @param[in] desired_type
  58   ///     If not eResultTypeAny, the type to use for the expression
  59   ///     result.
  60   //------------------------------------------------------------------
  61   UserExpression(ExecutionContextScope &exe_scope, llvm::StringRef expr,
  62                  llvm::StringRef prefix, lldb::LanguageType language,
  63                  ResultType desired_type,
  64                  const EvaluateExpressionOptions &options);
  65
  66   //------------------------------------------------------------------
  67   /// Destructor
  68   //------------------------------------------------------------------
  69   ~UserExpression() override;
  70
  71   //------------------------------------------------------------------
  72   /// Parse the expression
  73   ///
  74   /// @param[in] diagnostic_manager
  75   ///     A diagnostic manager to report parse errors and warnings to.
  76   ///
  77   /// @param[in] exe_ctx
  78   ///     The execution context to use when looking up entities that
  79   ///     are needed for parsing (locations of functions, types of
  80   ///     variables, persistent variables, etc.)
  81   ///
  82   /// @param[in] execution_policy
  83   ///     Determines whether interpretation is possible or mandatory.
  84   ///
  85   /// @param[in] keep_result_in_memory
  86   ///     True if the resulting persistent variable should reside in
  87   ///     target memory, if applicable.
  88   ///
  89   /// @return
  90   ///     True on success (no errors); false otherwise.
  91   //------------------------------------------------------------------
  92   virtual bool Parse(DiagnosticManager &diagnostic_manager,
  93                      ExecutionContext &exe_ctx,
  94                      lldb_private::ExecutionPolicy execution_policy,
  95                      bool keep_result_in_memory, bool generate_debug_info) = 0;
  96
  97   //------------------------------------------------------------------
  98   /// Attempts to find possible command line completions for the given
  99   /// (possible incomplete) user expression.
 100   ///
 101   /// @param[in] exe_ctx
 102   ///     The execution context to use when looking up entities that
 103   ///     are needed for parsing and completing (locations of functions, types
 104   ///     of variables, persistent variables, etc.)
 105   ///
 106   /// @param[out] request
 107   ///     The completion request to fill out. The completion should be a string
 108   ///     that would complete the current token at the cursor position.
 109   ///     Note that the string in the list replaces the current token
 110   ///     in the command line.
 111   ///
 112   /// @param[in] complete_pos
 113   ///     The position of the cursor inside the user expression string.
 114   ///     The completion process starts on the token that the cursor is in.
 115   ///
 116   /// @return
 117   ///     True if we added any completion results to the output;
 118   ///     false otherwise.
 119   //------------------------------------------------------------------
 120   virtual bool Complete(ExecutionContext &exe_ctx, CompletionRequest &request,
 121                         unsigned complete_pos) {
 122     return false;
 123   }
 124
 125   virtual bool CanInterpret() = 0;
 126
 127   bool MatchesContext(ExecutionContext &exe_ctx);
 128
 129   //------------------------------------------------------------------
 130   /// Execute the parsed expression by callinng the derived class's DoExecute
 131   /// method.
 132   ///
 133   /// @param[in] diagnostic_manager
 134   ///     A diagnostic manager to report errors to.
 135   ///
 136   /// @param[in] exe_ctx
 137   ///     The execution context to use when looking up entities that
 138   ///     are needed for parsing (locations of variables, etc.)
 139   ///
 140   /// @param[in] options
 141   ///     Expression evaluation options.
 142   ///
 143   /// @param[in] shared_ptr_to_me
 144   ///     This is a shared pointer to this UserExpression.  This is
 145   ///     needed because Execute can push a thread plan that will hold onto
 146   ///     the UserExpression for an unbounded period of time.  So you
 147   ///     need to give the thread plan a reference to this object that can
 148   ///     keep it alive.
 149   ///
 150   /// @param[in] result
 151   ///     A pointer to direct at the persistent variable in which the
 152   ///     expression's result is stored.
 153   ///
 154   /// @return
 155   ///     A Process::Execution results value.
 156   //------------------------------------------------------------------
 157   lldb::ExpressionResults Execute(DiagnosticManager &diagnostic_manager,
 158                                   ExecutionContext &exe_ctx,
 159                                   const EvaluateExpressionOptions &options,
 160                                   lldb::UserExpressionSP &shared_ptr_to_me,
 161                                   lldb::ExpressionVariableSP &result);
 162
 163   //------------------------------------------------------------------
 164   /// Apply the side effects of the function to program state.
 165   ///
 166   /// @param[in] diagnostic_manager
 167   ///     A diagnostic manager to report errors to.
 168   ///
 169   /// @param[in] exe_ctx
 170   ///     The execution context to use when looking up entities that
 171   ///     are needed for parsing (locations of variables, etc.)
 172   ///
 173   /// @param[in] result
 174   ///     A pointer to direct at the persistent variable in which the
 175   ///     expression's result is stored.
 176   ///
 177   /// @param[in] function_stack_pointer
 178   ///     A pointer to the base of the function's stack frame.  This
 179   ///     is used to determine whether the expression result resides in
 180   ///     memory that will still be valid, or whether it needs to be
 181   ///     treated as homeless for the purpose of future expressions.
 182   ///
 183   /// @return
 184   ///     A Process::Execution results value.
 185   //------------------------------------------------------------------
 186   virtual bool FinalizeJITExecution(
 187       DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
 188       lldb::ExpressionVariableSP &result,
 189       lldb::addr_t function_stack_bottom = LLDB_INVALID_ADDRESS,
 190       lldb::addr_t function_stack_top = LLDB_INVALID_ADDRESS) = 0;
 191
 192   //------------------------------------------------------------------
 193   /// Return the string that the parser should parse.
 194   //------------------------------------------------------------------
 195   const char *Text() override { return m_expr_text.c_str(); }
 196
 197   //------------------------------------------------------------------
 198   /// Return the string that the user typed.
 199   //------------------------------------------------------------------
 200   const char *GetUserText() { return m_expr_text.c_str(); }
 201
 202   //------------------------------------------------------------------
 203   /// Return the function name that should be used for executing the
 204   /// expression.  Text() should contain the definition of this function.
 205   //------------------------------------------------------------------
 206   const char *FunctionName() override { return "$__lldb_expr"; }
 207
 208   //------------------------------------------------------------------
 209   /// Return the language that should be used when parsing.  To use the
 210   /// default, return eLanguageTypeUnknown.
 211   //------------------------------------------------------------------
 212   lldb::LanguageType Language() override { return m_language; }
 213
 214   //------------------------------------------------------------------
 215   /// Return the desired result type of the function, or eResultTypeAny if
 216   /// indifferent.
 217   //------------------------------------------------------------------
 218   ResultType DesiredResultType() override { return m_desired_type; }
 219
 220   //------------------------------------------------------------------
 221   /// Return true if validation code should be inserted into the expression.
 222   //------------------------------------------------------------------
 223   bool NeedsValidation() override { return true; }
 224
 225   //------------------------------------------------------------------
 226   /// Return true if external variables in the expression should be resolved.
 227   //------------------------------------------------------------------
 228   bool NeedsVariableResolution() override { return true; }
 229
 230   EvaluateExpressionOptions *GetOptions() override { return &m_options; }
 231
 232   virtual lldb::ExpressionVariableSP
 233   GetResultAfterDematerialization(ExecutionContextScope *exe_scope) {
 234     return lldb::ExpressionVariableSP();
 235   }
 236
 237   virtual lldb::ModuleSP GetJITModule() { return lldb::ModuleSP(); }
 238
 239   //------------------------------------------------------------------
 240   /// Evaluate one expression in the scratch context of the target passed in
 241   /// the exe_ctx and return its result.
 242   ///
 243   /// @param[in] exe_ctx
 244   ///     The execution context to use when evaluating the expression.
 245   ///
 246   /// @param[in] options
 247   ///     Expression evaluation options.  N.B. The language in the
 248   ///     evaluation options will be used to determine the language used for
 249   ///     expression evaluation.
 250   ///
 251   /// @param[in] expr_cstr
 252   ///     A C string containing the expression to be evaluated.
 253   ///
 254   /// @param[in] expr_prefix
 255   ///     If non-nullptr, a C string containing translation-unit level
 256   ///     definitions to be included when the expression is parsed.
 257   ///
 258   /// @param[in,out] result_valobj_sp
 259   ///      If execution is successful, the result valobj is placed here.
 260   ///
 261   /// @param[out] error
 262   ///     Filled in with an error in case the expression evaluation
 263   ///     fails to parse, run, or evaluated.
 264   ///
 265   /// @param[in] line_offset
 266   ///     The offset of the first line of the expression from the "beginning" of
 267   ///     a virtual source file used for error reporting and debug info.
 268   ///
 269   /// @param[out] fixed_expression
 270   ///     If non-nullptr, the fixed expression is copied into the provided
 271   ///     string.
 272   ///
 273   /// @param[out] jit_module_sp_ptr
 274   ///     If non-nullptr, used to persist the generated IR module.
 275   ///
 276   /// @result
 277   ///      A Process::ExpressionResults value.  eExpressionCompleted for
 278   ///      success.
 279   //------------------------------------------------------------------
 280   static lldb::ExpressionResults
 281   Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options,
 282            llvm::StringRef expr_cstr, llvm::StringRef expr_prefix,
 283            lldb::ValueObjectSP &result_valobj_sp, Status &error,
 284            uint32_t line_offset = 0, std::string *fixed_expression = nullptr,
 285            lldb::ModuleSP *jit_module_sp_ptr = nullptr);
 286
 287   static const Status::ValueType kNoResult =
 288       0x1001; ///< ValueObject::GetError() returns this if there is no result
 289               /// from the expression.
 290
 291   const char *GetFixedText() {
 292     if (m_fixed_text.empty())
 293       return nullptr;
 294     return m_fixed_text.c_str();
 295   }
 296
 297 protected:
 298   virtual lldb::ExpressionResults
 299   DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
 300             const EvaluateExpressionOptions &options,
 301             lldb::UserExpressionSP &shared_ptr_to_me,
 302             lldb::ExpressionVariableSP &result) = 0;
 303
 304   static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp,
 305                                        ConstString &object_name, Status &err);
 306
 307   //------------------------------------------------------------------
 308   /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the
 309   /// environment.
 310   //------------------------------------------------------------------
 311
 312   void InstallContext(ExecutionContext &exe_ctx);
 313
 314   bool LockAndCheckContext(ExecutionContext &exe_ctx, lldb::TargetSP &target_sp,
 315                            lldb::ProcessSP &process_sp,
 316                            lldb::StackFrameSP &frame_sp);
 317
 318   Address m_address;       ///< The address the process is stopped in.
 319   std::string m_expr_text; ///< The text of the expression, as typed by the user
 320   std::string m_expr_prefix; ///< The text of the translation-level definitions,
 321                              ///as provided by the user
 322   std::string m_fixed_text; ///< The text of the expression with fix-its applied
 323                             ///- this won't be set if the fixed text doesn't
 324                             ///parse.
 325   lldb::LanguageType m_language; ///< The language to use when parsing
 326                                  ///(eLanguageTypeUnknown means use defaults)
 327   ResultType m_desired_type; ///< The type to coerce the expression's result to.
 328                              ///If eResultTypeAny, inferred from the expression.
 329   EvaluateExpressionOptions
 330       m_options; ///< Additional options provided by the user.
 331 };
 332
 333 } // namespace lldb_private
 334
 335 #endif // liblldb_UserExpression_h_