LLDB  mainline
UserExpression.h
Go to the documentation of this file.
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"
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.
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.
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 
210 
211  virtual lldb::ExpressionVariableSP
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.
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 
266  0x1001; ///< ValueObject::GetError() returns this if there is no result
267  /// from the expression.
268 
269  const char *GetFixedText() {
270  if (m_fixed_text.empty())
271  return nullptr;
272  return m_fixed_text.c_str();
273  }
274 
275 protected:
277  DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
278  const EvaluateExpressionOptions &options,
279  lldb::UserExpressionSP &shared_ptr_to_me,
280  lldb::ExpressionVariableSP &result) = 0;
281 
282  static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp,
283  ConstString &object_name, Status &err);
284 
285  /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the
286  /// environment.
287 
288  void InstallContext(ExecutionContext &exe_ctx);
289 
290  bool LockAndCheckContext(ExecutionContext &exe_ctx, lldb::TargetSP &target_sp,
291  lldb::ProcessSP &process_sp,
292  lldb::StackFrameSP &frame_sp);
293 
294  Address m_address; ///< The address the process is stopped in.
295  std::string m_expr_text; ///< The text of the expression, as typed by the user
296  std::string m_expr_prefix; ///< The text of the translation-level definitions,
297  ///as provided by the user
298  std::string m_fixed_text; ///< The text of the expression with fix-its applied
299  ///- this won't be set if the fixed text doesn't
300  ///parse.
301  lldb::LanguageType m_language; ///< The language to use when parsing
302  ///(eLanguageTypeUnknown means use defaults)
303  ResultType m_desired_type; ///< The type to coerce the expression's result to.
304  ///If eResultTypeAny, inferred from the expression.
306  m_options; ///< Additional options provided by the user.
307 };
308 
309 } // namespace lldb_private
310 
311 #endif // LLDB_EXPRESSION_USEREXPRESSION_H
lldb_private::UserExpression::InstallContext
void InstallContext(ExecutionContext &exe_ctx)
Populate m_in_cplusplus_method and m_in_objectivec_method based on the environment.
Definition: UserExpression.cpp:58
lldb_private::UserExpression::m_address
Address m_address
The address the process is stopped in.
Definition: UserExpression.h:294
lldb_private::UserExpression::m_desired_type
ResultType m_desired_type
The type to coerce the expression's result to.
Definition: UserExpression.h:303
lldb_private::ExecutionContext
Definition: ExecutionContext.h:292
lldb_private::UserExpression::~UserExpression
~UserExpression() override
Destructor.
lldb_private::UserExpression::GetUserText
const char * GetUserText()
Return the string that the user typed.
Definition: UserExpression.h:189
lldb_private::UserExpression::GetFixedText
const char * GetFixedText()
Definition: UserExpression.h:269
lldb_private::UserExpression::CanInterpret
virtual bool CanInterpret()=0
lldb_private::ExecutionPolicy
ExecutionPolicy
Expression execution policies.
Definition: lldb-private-enumerations.h:144
lldb::ExpressionResults
ExpressionResults
The results of expression evaluation.
Definition: lldb-enumerations.h:270
lldb_private::UserExpression::FunctionName
const char * FunctionName() override
Return the function name that should be used for executing the expression.
Definition: UserExpression.h:193
lldb_private::UserExpression::isA
bool isA(const void *ClassID) const override
Definition: UserExpression.h:40
lldb_private::UserExpression::Text
const char * Text() override
Return the string that the parser should parse.
Definition: UserExpression.h:186
lldb_private::EvaluateExpressionOptions
Definition: Target.h:259
lldb::LanguageType
LanguageType
Programming language type.
Definition: lldb-enumerations.h:436
lldb_private::UserExpression
Definition: UserExpression.h:35
lldb_private::UserExpression::Evaluate
static lldb::ExpressionResults Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options, llvm::StringRef expr_cstr, llvm::StringRef expr_prefix, lldb::ValueObjectSP &result_valobj_sp, Status &error, std::string *fixed_expression=nullptr, ValueObject *ctx_obj=nullptr)
Evaluate one expression in the scratch context of the target passed in the exe_ctx and return its res...
Definition: UserExpression.cpp:139
lldb_private::UserExpression::GetOptions
EvaluateExpressionOptions * GetOptions() override
Definition: UserExpression.h:209
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb_private::UserExpression::m_fixed_text
std::string m_fixed_text
The text of the expression with fix-its applied.
Definition: UserExpression.h:298
lldb_private::UserExpression::GetResultAfterDematerialization
virtual lldb::ExpressionVariableSP GetResultAfterDematerialization(ExecutionContextScope *exe_scope)
Definition: UserExpression.h:212
lldb_private::Expression::isA
virtual bool isA(const void *ClassID) const =0
lldb_private::UserExpression::m_options
EvaluateExpressionOptions m_options
Additional options provided by the user.
Definition: UserExpression.h:306
lldb_private::UserExpression::FinalizeJITExecution
virtual bool FinalizeJITExecution(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, lldb::ExpressionVariableSP &result, lldb::addr_t function_stack_bottom=LLDB_INVALID_ADDRESS, lldb::addr_t function_stack_top=LLDB_INVALID_ADDRESS)=0
Apply the side effects of the function to program state.
lldb_private::Expression::ResultType
ResultType
Definition: Expression.h:35
Target.h
error
static llvm::raw_ostream & error(Stream &strm)
Definition: CommandReturnObject.cpp:17
lldb_private::ExecutionContextScope
Definition: ExecutionContextScope.h:32
lldb_private::ConstString
Definition: ConstString.h:40
lldb_private::UserExpression::DesiredResultType
ResultType DesiredResultType() override
Return the desired result type of the function, or eResultTypeAny if indifferent.
Definition: UserExpression.h:201
lldb_private::UserExpression::Language
lldb::LanguageType Language() const override
Return the language that should be used when parsing.
Definition: UserExpression.h:197
lldb_private::UserExpression::GetObjectPointer
static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp, ConstString &object_name, Status &err)
Definition: UserExpression.cpp:100
lldb_private::UserExpression::NeedsValidation
bool NeedsValidation() override
Return true if validation code should be inserted into the expression.
Definition: UserExpression.h:204
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:40
Address.h
lldb-private.h
Materializer.h
lldb_private::Status
Definition: Status.h:44
lldb_private::ValueObject
ValueObject:
Definition: ValueObject.h:105
lldb_private::UserExpression::Parse
virtual bool Parse(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, lldb_private::ExecutionPolicy execution_policy, bool keep_result_in_memory, bool generate_debug_info)=0
Parse the expression.
uint32_t
lldb_private::Address
Definition: Address.h:59
lldb_private::UserExpression::m_language
lldb::LanguageType m_language
The language to use when parsing (eLanguageTypeUnknown means use defaults)
Definition: UserExpression.h:301
lldb_private::DiagnosticManager
Definition: DiagnosticManager.h:93
lldb_private::UserExpression::Complete
virtual bool Complete(ExecutionContext &exe_ctx, CompletionRequest &request, unsigned complete_pos)
Attempts to find possible command line completions for the given (possible incomplete) user expressio...
Definition: UserExpression.h:111
lldb_private::UserExpression::Execute
lldb::ExpressionResults Execute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options, lldb::UserExpressionSP &shared_ptr_to_me, lldb::ExpressionVariableSP &result)
Execute the parsed expression by callinng the derived class's DoExecute method.
Definition: UserExpression.cpp:394
LLDB_INVALID_ADDRESS
#define LLDB_INVALID_ADDRESS
Definition: lldb-defines.h:86
lldb-forward.h
lldb_private::UserExpression::kNoResult
static const Status::ValueType kNoResult
ValueObject::GetError() returns this if there is no result from the expression.
Definition: UserExpression.h:265
lldb_private::UserExpression::kDefaultTimeout
@ kDefaultTimeout
Definition: UserExpression.h:43
lldb_private::UserExpression::UserExpression
UserExpression(ExecutionContextScope &exe_scope, llvm::StringRef expr, llvm::StringRef prefix, lldb::LanguageType language, ResultType desired_type, const EvaluateExpressionOptions &options)
Constructor.
Definition: UserExpression.cpp:47
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::UserExpression::ID
static char ID
LLVM RTTI support.
Definition: UserExpression.h:37
lldb_private::UserExpression::m_expr_prefix
std::string m_expr_prefix
The text of the translation-level definitions, as provided by the user.
Definition: UserExpression.h:296
lldb_private::UserExpression::m_expr_text
std::string m_expr_text
The text of the expression, as typed by the user.
Definition: UserExpression.h:295
lldb_private::UserExpression::classof
static bool classof(const Expression *obj)
Definition: UserExpression.h:41
lldb_private::UserExpression::LockAndCheckContext
bool LockAndCheckContext(ExecutionContext &exe_ctx, lldb::TargetSP &target_sp, lldb::ProcessSP &process_sp, lldb::StackFrameSP &frame_sp)
Definition: UserExpression.cpp:67
Expression.h
lldb_private::Expression
Definition: Expression.h:33
lldb_private::UserExpression::DoExecute
virtual lldb::ExpressionResults DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options, lldb::UserExpressionSP &shared_ptr_to_me, lldb::ExpressionVariableSP &result)=0
lldb_private::UserExpression::NeedsVariableResolution
bool NeedsVariableResolution() override
Return true if external variables in the expression should be resolved.
Definition: UserExpression.h:207
ExecutionContext.h
lldb_private::CompletionRequest
Definition: CompletionRequest.h:100
lldb_private::UserExpression::MatchesContext
bool MatchesContext(ExecutionContext &exe_ctx)
Definition: UserExpression.cpp:92