contrib/llvm-project/lldb/include/lldb/Expression/UserExpression.h

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