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
24namespace 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.
35class UserExpression : public Expression {
36 /// LLVM RTTI support.
37 static char ID;
38
39public:
40 bool isA(const void *ClassID) const override { return ClassID == &ID; }
41 static bool classof(const Expression *obj) { return obj->isA(ClassID: &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 /// Returns whether the call to Parse on this user expression is cacheable.
196 /// This function exists to provide an escape hatch for supporting languages
197 /// where parsing an expression in the exact same context is unsafe. For
198 /// example, languages where generic functions aren't monomorphized, but
199 /// implement some other mechanism to represent generic values, may be unsafe
200 /// to cache, as the concrete type substitution may be different in every
201 /// expression evaluation.
202 virtual bool IsParseCacheable() { return true; }
203 /// Return the language that should be used when parsing. To use the
204 /// default, return eLanguageTypeUnknown.
205 lldb::LanguageType Language() const override { return m_language; }
206
207 /// Return the desired result type of the function, or eResultTypeAny if
208 /// indifferent.
209 ResultType DesiredResultType() override { return m_desired_type; }
210
211 /// Return true if validation code should be inserted into the expression.
212 bool NeedsValidation() override { return true; }
213
214 /// Return true if external variables in the expression should be resolved.
215 bool NeedsVariableResolution() override { return true; }
216
217 EvaluateExpressionOptions *GetOptions() override { return &m_options; }
218
219 virtual lldb::ExpressionVariableSP
220 GetResultAfterDematerialization(ExecutionContextScope *exe_scope) {
221 return lldb::ExpressionVariableSP();
222 }
223
224 /// Evaluate one expression in the scratch context of the target passed in
225 /// the exe_ctx and return its result.
226 ///
227 /// \param[in] exe_ctx
228 /// The execution context to use when evaluating the expression.
229 ///
230 /// \param[in] options
231 /// Expression evaluation options. N.B. The language in the
232 /// evaluation options will be used to determine the language used for
233 /// expression evaluation.
234 ///
235 /// \param[in] expr_cstr
236 /// A C string containing the expression to be evaluated.
237 ///
238 /// \param[in] expr_prefix
239 /// If non-nullptr, a C string containing translation-unit level
240 /// definitions to be included when the expression is parsed.
241 ///
242 /// \param[in,out] result_valobj_sp
243 /// If execution is successful, the result valobj is placed here.
244 ///
245 /// \param[out] error
246 /// Filled in with an error in case the expression evaluation
247 /// fails to parse, run, or evaluated.
248 ///
249 /// \param[out] fixed_expression
250 /// If non-nullptr, the fixed expression is copied into the provided
251 /// string.
252 ///
253 /// \param[in] ctx_obj
254 /// If specified, then the expression will be evaluated in the context of
255 /// this object. It means that the context object's address will be
256 /// treated as `this` for the expression (the expression will be
257 /// evaluated as if it was inside of a method of the context object's
258 /// class, and its `this` parameter were pointing to the context object).
259 /// The parameter makes sense for class and union types only.
260 /// Currently there is a limitation: the context object must be located
261 /// in the debuggee process' memory (and have the load address).
262 ///
263 /// \result
264 /// A Process::ExpressionResults value. eExpressionCompleted for
265 /// success.
266 static lldb::ExpressionResults
267 Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options,
268 llvm::StringRef expr_cstr, llvm::StringRef expr_prefix,
269 lldb::ValueObjectSP &result_valobj_sp, Status &error,
270 std::string *fixed_expression = nullptr,
271 ValueObject *ctx_obj = nullptr);
272
273 static const Status::ValueType kNoResult =
274 0x1001; ///< ValueObject::GetError() returns this if there is no result
275 /// from the expression.
276
277 llvm::StringRef GetFixedText() {
278 return m_fixed_text;
279 }
280
281protected:
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 llvm::StringRef object_name,
290 Status &err);
291
292 /// Return ValueObject for a given variable name in the current stack frame
293 ///
294 /// \param[in] frame Current stack frame. When passed a 'nullptr', this
295 /// function returns an empty ValueObjectSP.
296 ///
297 /// \param[in] object_name Name of the variable in the current stack frame
298 /// for which we want the ValueObjectSP.
299 ///
300 /// \param[out] err Status object which will get set on error.
301 ///
302 /// \returns On success returns a ValueObjectSP corresponding to the variable
303 /// with 'object_name' in the current 'frame'. Otherwise, returns
304 /// 'nullptr' (and sets the error status parameter 'err').
305 static lldb::ValueObjectSP
306 GetObjectPointerValueObject(lldb::StackFrameSP frame,
307 llvm::StringRef object_name, Status &err);
308
309 /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the
310 /// environment.
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 // LLDB_EXPRESSION_USEREXPRESSION_H
336

source code of lldb/include/lldb/Expression/UserExpression.h