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 LLDB_EXPRESSION_USEREXPRESSION_H 10 #define LLDB_EXPRESSION_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() const 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 /// Evaluate one expression in the scratch context of the target passed in 217 /// the exe_ctx and return its result. 218 /// 219 /// \param[in] exe_ctx 220 /// The execution context to use when evaluating the expression. 221 /// 222 /// \param[in] options 223 /// Expression evaluation options. N.B. The language in the 224 /// evaluation options will be used to determine the language used for 225 /// expression evaluation. 226 /// 227 /// \param[in] expr_cstr 228 /// A C string containing the expression to be evaluated. 229 /// 230 /// \param[in] expr_prefix 231 /// If non-nullptr, a C string containing translation-unit level 232 /// definitions to be included when the expression is parsed. 233 /// 234 /// \param[in,out] result_valobj_sp 235 /// If execution is successful, the result valobj is placed here. 236 /// 237 /// \param[out] error 238 /// Filled in with an error in case the expression evaluation 239 /// fails to parse, run, or evaluated. 240 /// 241 /// \param[out] fixed_expression 242 /// If non-nullptr, the fixed expression is copied into the provided 243 /// string. 244 /// 245 /// \param[in] ctx_obj 246 /// If specified, then the expression will be evaluated in the context of 247 /// this object. It means that the context object's address will be 248 /// treated as `this` for the expression (the expression will be 249 /// evaluated as if it was inside of a method of the context object's 250 /// class, and its `this` parameter were pointing to the context object). 251 /// The parameter makes sense for class and union types only. 252 /// Currently there is a limitation: the context object must be located 253 /// in the debuggee process' memory (and have the load address). 254 /// 255 /// \result 256 /// A Process::ExpressionResults value. eExpressionCompleted for 257 /// success. 258 static lldb::ExpressionResults 259 Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options, 260 llvm::StringRef expr_cstr, llvm::StringRef expr_prefix, 261 lldb::ValueObjectSP &result_valobj_sp, Status &error, 262 std::string *fixed_expression = nullptr, 263 ValueObject *ctx_obj = nullptr); 264 265 static const Status::ValueType kNoResult = 266 0x1001; ///< ValueObject::GetError() returns this if there is no result 267 /// from the expression. 268 269 llvm::StringRef GetFixedText() { 270 return m_fixed_text; 271 } 272 273 protected: 274 virtual lldb::ExpressionResults 275 DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, 276 const EvaluateExpressionOptions &options, 277 lldb::UserExpressionSP &shared_ptr_to_me, 278 lldb::ExpressionVariableSP &result) = 0; 279 280 static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp, 281 ConstString &object_name, Status &err); 282 283 /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the 284 /// environment. 285 286 void InstallContext(ExecutionContext &exe_ctx); 287 288 bool LockAndCheckContext(ExecutionContext &exe_ctx, lldb::TargetSP &target_sp, 289 lldb::ProcessSP &process_sp, 290 lldb::StackFrameSP &frame_sp); 291 292 Address m_address; ///< The address the process is stopped in. 293 std::string m_expr_text; ///< The text of the expression, as typed by the user 294 std::string m_expr_prefix; ///< The text of the translation-level definitions, 295 ///as provided by the user 296 std::string m_fixed_text; ///< The text of the expression with fix-its applied 297 ///- this won't be set if the fixed text doesn't 298 ///parse. 299 lldb::LanguageType m_language; ///< The language to use when parsing 300 ///(eLanguageTypeUnknown means use defaults) 301 ResultType m_desired_type; ///< The type to coerce the expression's result to. 302 ///If eResultTypeAny, inferred from the expression. 303 EvaluateExpressionOptions 304 m_options; ///< Additional options provided by the user. 305 }; 306 307 } // namespace lldb_private 308 309 #endif // LLDB_EXPRESSION_USEREXPRESSION_H 310