LLDB  mainline
ClangUserExpression.h
Go to the documentation of this file.
1 //===-- ClangUserExpression.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_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_CLANGUSEREXPRESSION_H
10 #define LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_CLANGUSEREXPRESSION_H
11 
12 #include <vector>
13 
14 #include "ASTResultSynthesizer.h"
15 #include "ASTStructExtractor.h"
16 #include "ClangExpressionDeclMap.h"
17 #include "ClangExpressionHelper.h"
20 #include "IRForTarget.h"
21 
22 #include "lldb/Core/Address.h"
26 #include "lldb/lldb-forward.h"
27 #include "lldb/lldb-private.h"
28 
29 namespace lldb_private {
30 
31 /// \class ClangUserExpression ClangUserExpression.h
32 /// "lldb/Expression/ClangUserExpression.h" Encapsulates a single expression
33 /// for use with Clang
34 ///
35 /// LLDB uses expressions for various purposes, notably to call functions
36 /// and as a backend for the expr command. ClangUserExpression encapsulates
37 /// the objects needed to parse and interpret or JIT an expression. It uses
38 /// the Clang parser to produce LLVM IR from the expression.
40  // LLVM RTTI support
41  static char ID;
42 
43 public:
44  bool isA(const void *ClassID) const override {
45  return ClassID == &ID || LLVMUserExpression::isA(ClassID);
46  }
47  static bool classof(const Expression *obj) { return obj->isA(&ID); }
48 
49  enum { kDefaultTimeout = 500000u };
50 
52  public:
53  ClangUserExpressionHelper(Target &target, bool top_level)
54  : m_target(target), m_top_level(top_level) {}
55 
56  ~ClangUserExpressionHelper() override = default;
57 
58  /// Return the object that the parser should use when resolving external
59  /// values. May be NULL if everything should be self-contained.
61  return m_expr_decl_map_up.get();
62  }
63 
64  void ResetDeclMap() { m_expr_decl_map_up.reset(); }
65 
66  void ResetDeclMap(ExecutionContext &exe_ctx,
68  bool keep_result_in_memory,
69  ValueObject *ctx_obj);
70 
71  /// Return the object that the parser should allow to access ASTs. May be
72  /// NULL if the ASTs do not need to be transformed.
73  ///
74  /// \param[in] passthrough
75  /// The ASTConsumer that the returned transformer should send
76  /// the ASTs to after transformation.
77  clang::ASTConsumer *
78  ASTTransformer(clang::ASTConsumer *passthrough) override;
79 
80  void CommitPersistentDecls() override;
81 
82  private:
84  std::unique_ptr<ClangExpressionDeclMap> m_expr_decl_map_up;
85  std::unique_ptr<ASTStructExtractor> m_struct_extractor_up; ///< The class
86  ///that generates
87  ///the argument
88  ///struct layout.
89  std::unique_ptr<ASTResultSynthesizer> m_result_synthesizer_up;
91  };
92 
93  /// Constructor
94  ///
95  /// \param[in] expr
96  /// The expression to parse.
97  ///
98  /// \param[in] prefix
99  /// If non-NULL, a C string containing translation-unit level
100  /// definitions to be included when the expression is parsed.
101  ///
102  /// \param[in] language
103  /// If not eLanguageTypeUnknown, a language to use when parsing
104  /// the expression. Currently restricted to those languages
105  /// supported by Clang.
106  ///
107  /// \param[in] desired_type
108  /// If not eResultTypeAny, the type to use for the expression
109  /// result.
110  ///
111  /// \param[in] options
112  /// Additional options for the expression.
113  ///
114  /// \param[in] ctx_obj
115  /// The object (if any) in which context the expression
116  /// must be evaluated. For details see the comment to
117  /// `UserExpression::Evaluate`.
118  ClangUserExpression(ExecutionContextScope &exe_scope, llvm::StringRef expr,
119  llvm::StringRef prefix, lldb::LanguageType language,
120  ResultType desired_type,
121  const EvaluateExpressionOptions &options,
122  ValueObject *ctx_obj);
123 
124  ~ClangUserExpression() override;
125 
126  /// Parse the expression
127  ///
128  /// \param[in] diagnostic_manager
129  /// A diagnostic manager to report parse errors and warnings to.
130  ///
131  /// \param[in] exe_ctx
132  /// The execution context to use when looking up entities that
133  /// are needed for parsing (locations of functions, types of
134  /// variables, persistent variables, etc.)
135  ///
136  /// \param[in] execution_policy
137  /// Determines whether interpretation is possible or mandatory.
138  ///
139  /// \param[in] keep_result_in_memory
140  /// True if the resulting persistent variable should reside in
141  /// target memory, if applicable.
142  ///
143  /// \return
144  /// True on success (no errors); false otherwise.
145  bool Parse(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
146  lldb_private::ExecutionPolicy execution_policy,
147  bool keep_result_in_memory, bool generate_debug_info) override;
148 
149  bool Complete(ExecutionContext &exe_ctx, CompletionRequest &request,
150  unsigned complete_pos) override;
151 
153  return &m_type_system_helper;
154  }
155 
157 
159 
162  bool keep_result_in_memory) {
163  m_type_system_helper.ResetDeclMap(exe_ctx, result_delegate,
164  keep_result_in_memory,
165  m_ctx_obj);
166  }
167 
168  lldb::ExpressionVariableSP
170 
171  /// Returns true iff this expression is using any imported C++ modules.
172  bool DidImportCxxModules() const { return !m_imported_cpp_modules.empty(); }
173 
174 private:
175  /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the
176  /// environment.
177 
178  /// Contains the actual parsing implementation.
179  /// The parameter have the same meaning as in ClangUserExpression::Parse.
180  /// \see ClangUserExpression::Parse
181  bool TryParse(DiagnosticManager &diagnostic_manager,
182  ExecutionContextScope *exe_scope, ExecutionContext &exe_ctx,
183  lldb_private::ExecutionPolicy execution_policy, bool keep_result_in_memory,
184  bool generate_debug_info);
185 
187 
188  void ScanContext(ExecutionContext &exe_ctx,
189  lldb_private::Status &err) override;
190 
191  bool AddArguments(ExecutionContext &exe_ctx, std::vector<lldb::addr_t> &args,
192  lldb::addr_t struct_address,
193  DiagnosticManager &diagnostic_manager) override;
194 
195  void CreateSourceCode(DiagnosticManager &diagnostic_manager,
196  ExecutionContext &exe_ctx,
197  std::vector<std::string> modules_to_import,
198  bool for_completion);
199  /// Defines how the current expression should be wrapped.
201  bool SetupPersistentState(DiagnosticManager &diagnostic_manager,
202  ExecutionContext &exe_ctx);
203  bool PrepareForParsing(DiagnosticManager &diagnostic_manager,
204  ExecutionContext &exe_ctx, bool for_completion);
205 
207 
209  public:
210  ResultDelegate(lldb::TargetSP target) : m_target_sp(target) {}
211  ConstString GetName() override;
212  void DidDematerialize(lldb::ExpressionVariableSP &variable) override;
213 
214  void RegisterPersistentState(PersistentExpressionState *persistent_state);
215  lldb::ExpressionVariableSP &GetVariable();
216 
217  private:
219  lldb::ExpressionVariableSP m_variable;
220  lldb::TargetSP m_target_sp;
221  };
222 
223  /// The include directories that should be used when parsing the expression.
224  std::vector<std::string> m_include_directories;
225 
226  /// The absolute character position in the transformed source code where the
227  /// user code (as typed by the user) starts. If the variable is empty, then we
228  /// were not able to calculate this position.
229  llvm::Optional<size_t> m_user_expression_start_pos;
232  std::unique_ptr<ClangExpressionSourceCode> m_source_code;
233  /// The parser instance we used to parse the expression.
234  std::unique_ptr<ClangExpressionParser> m_parser;
235  /// File name used for the expression.
237 
238  /// The object (if any) in which context the expression is evaluated.
239  /// See the comment to `UserExpression::Evaluate` for details.
241 
242  /// A list of module names that should be imported when parsing.
243  /// \see CppModuleConfiguration::GetImportedModules
244  std::vector<std::string> m_imported_cpp_modules;
245 
246  /// True if the expression parser should enforce the presence of a valid class
247  /// pointer in order to generate the expression as a method.
249  /// True if the expression is compiled as a C++ member function (true if it
250  /// was parsed when exe_ctx was in a C++ method).
251  bool m_in_cplusplus_method = false;
252  /// True if the expression is compiled as an Objective-C method (true if it
253  /// was parsed when exe_ctx was in an Objective-C method).
255  /// True if the expression is compiled as a static (or class) method
256  /// (currently true if it was parsed when exe_ctx was in an Objective-C class
257  /// method).
258  bool m_in_static_method = false;
259  /// True if "this" or "self" must be looked up and passed in. False if the
260  /// expression doesn't really use them and they can be NULL.
261  bool m_needs_object_ptr = false;
262 };
263 
264 } // namespace lldb_private
265 
266 #endif // LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_CLANGUSEREXPRESSION_H
lldb_private::ClangUserExpression::ClangUserExpressionHelper::CommitPersistentDecls
void CommitPersistentDecls() override
Definition: ClangUserExpression.cpp:972
lldb_private::ClangUserExpression::ClangUserExpressionHelper::m_target
Target & m_target
Definition: ClangUserExpression.h:83
lldb_private::ClangUserExpression::m_clang_state
ClangPersistentVariables * m_clang_state
Definition: ClangUserExpression.h:231
lldb_private::ExecutionContext
Definition: ExecutionContext.h:292
ClangExpressionSourceCode.h
lldb_private::ClangPersistentVariables
Definition: ClangPersistentVariables.h:33
lldb_private::ClangUserExpression::ClangUserExpressionHelper::m_top_level
bool m_top_level
Definition: ClangUserExpression.h:90
lldb_private::ClangUserExpression::m_result_delegate
ResultDelegate m_result_delegate
Definition: ClangUserExpression.h:230
lldb_private::ExecutionPolicy
ExecutionPolicy
Expression execution policies.
Definition: lldb-private-enumerations.h:144
lldb_private::ClangUserExpression::CreateSourceCode
void CreateSourceCode(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, std::vector< std::string > modules_to_import, bool for_completion)
Definition: ClangUserExpression.cpp:417
ASTResultSynthesizer.h
lldb_private::ClangUserExpression::classof
static bool classof(const Expression *obj)
Definition: ClangUserExpression.h:47
lldb_private::ClangUserExpression::m_in_cplusplus_method
bool m_in_cplusplus_method
True if the expression is compiled as a C++ member function (true if it was parsed when exe_ctx was i...
Definition: ClangUserExpression.h:251
lldb_private::ClangUserExpression::isA
bool isA(const void *ClassID) const override
Definition: ClangUserExpression.h:44
lldb_private::EvaluateExpressionOptions
Definition: Target.h:253
lldb_private::ClangUserExpression::m_filename
std::string m_filename
File name used for the expression.
Definition: ClangUserExpression.h:236
lldb::LanguageType
LanguageType
Programming language type.
Definition: lldb-enumerations.h:436
lldb_private::ClangUserExpression::ClangUserExpressionHelper
Definition: ClangUserExpression.h:51
lldb_private::ClangUserExpression::ClangUserExpression
ClangUserExpression(ExecutionContextScope &exe_scope, llvm::StringRef expr, llvm::StringRef prefix, lldb::LanguageType language, ResultType desired_type, const EvaluateExpressionOptions &options, ValueObject *ctx_obj)
Constructor.
Definition: ClangUserExpression.cpp:68
lldb_private::ClangUserExpression::ClangUserExpressionHelper::DeclMap
ClangExpressionDeclMap * DeclMap() override
Return the object that the parser should use when resolving external values.
Definition: ClangUserExpression.h:60
lldb_private::ClangUserExpression::ResetDeclMap
void ResetDeclMap()
Definition: ClangUserExpression.h:158
lldb_private::ClangUserExpression::ClangUserExpressionHelper::ResetDeclMap
void ResetDeclMap()
Definition: ClangUserExpression.h:64
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb_private::ClangUserExpression::ResultDelegate::RegisterPersistentState
void RegisterPersistentState(PersistentExpressionState *persistent_state)
Definition: ClangUserExpression.cpp:987
lldb_private::Target
Definition: Target.h:445
lldb_private::ExpressionTypeSystemHelper
Definition: ExpressionTypeSystemHelper.h:26
lldb_private::ClangUserExpression::ResultDelegate::GetName
ConstString GetName() override
Definition: ClangUserExpression.cpp:978
lldb_private::ClangUserExpression::ClangUserExpressionHelper::m_result_synthesizer_up
std::unique_ptr< ASTResultSynthesizer > m_result_synthesizer_up
Definition: ClangUserExpression.h:89
lldb_private::ClangUserExpression::ResultDelegate::ResultDelegate
ResultDelegate(lldb::TargetSP target)
Definition: ClangUserExpression.h:210
lldb_private::Expression::isA
virtual bool isA(const void *ClassID) const =0
lldb_private::Expression::ResultType
ResultType
Definition: Expression.h:35
lldb_private::ClangUserExpression::ClangUserExpressionHelper::ClangUserExpressionHelper
ClangUserExpressionHelper(Target &target, bool top_level)
Definition: ClangUserExpression.h:53
lldb_private::ClangUserExpression::~ClangUserExpression
~ClangUserExpression() override
lldb_private::ClangUserExpression
Definition: ClangUserExpression.h:39
lldb_private::ClangUserExpression::m_ctx_obj
ValueObject * m_ctx_obj
The object (if any) in which context the expression is evaluated.
Definition: ClangUserExpression.h:240
lldb_private::ExecutionContextScope
Definition: ExecutionContextScope.h:32
lldb_private::LLVMUserExpression::isA
bool isA(const void *ClassID) const override
Definition: LLVMUserExpression.h:37
lldb_private::ClangUserExpression::ScanContext
void ScanContext(ExecutionContext &exe_ctx, lldb_private::Status &err) override
Definition: ClangUserExpression.cpp:95
lldb_private::ClangUserExpression::GetTypeSystemHelper
ExpressionTypeSystemHelper * GetTypeSystemHelper() override
Definition: ClangUserExpression.h:152
lldb_private::ClangUserExpression::m_in_static_method
bool m_in_static_method
True if the expression is compiled as a static (or class) method (currently true if it was parsed whe...
Definition: ClangUserExpression.h:258
IRForTarget.h
lldb_private::LLVMUserExpression
Definition: LLVMUserExpression.h:32
lldb_private::ClangUserExpression::ClangUserExpressionHelper::~ClangUserExpressionHelper
~ClangUserExpressionHelper() override=default
lldb_private::ConstString
Definition: ConstString.h:40
lldb_private::ClangUserExpression::SetupCppModuleImports
void SetupCppModuleImports(ExecutionContext &exe_ctx)
Definition: ClangUserExpression.cpp:627
lldb_private::ClangUserExpression::TryParse
bool TryParse(DiagnosticManager &diagnostic_manager, ExecutionContextScope *exe_scope, ExecutionContext &exe_ctx, lldb_private::ExecutionPolicy execution_policy, bool keep_result_in_memory, bool generate_debug_info)
Populate m_in_cplusplus_method and m_in_objectivec_method based on the environment.
Definition: ClangUserExpression.cpp:559
lldb_private::ClangUserExpression::m_in_objectivec_method
bool m_in_objectivec_method
True if the expression is compiled as an Objective-C method (true if it was parsed when exe_ctx was i...
Definition: ClangUserExpression.h:254
lldb_private::ClangUserExpression::ResultDelegate::m_persistent_state
PersistentExpressionState * m_persistent_state
Definition: ClangUserExpression.h:218
lldb_private::Materializer::PersistentVariableDelegate
Definition: Materializer.h:70
lldb_private::ClangUserExpression::m_imported_cpp_modules
std::vector< std::string > m_imported_cpp_modules
A list of module names that should be imported when parsing.
Definition: ClangUserExpression.h:244
lldb_private::ClangUserExpression::m_source_code
std::unique_ptr< ClangExpressionSourceCode > m_source_code
Definition: ClangUserExpression.h:232
lldb_private::ClangUserExpression::SetupPersistentState
bool SetupPersistentState(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx)
Definition: ClangUserExpression.cpp:328
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:39
lldb_private::ClangUserExpression::m_needs_object_ptr
bool m_needs_object_ptr
True if "this" or "self" must be looked up and passed in.
Definition: ClangUserExpression.h:261
lldb_private::ClangUserExpression::m_enforce_valid_object
bool m_enforce_valid_object
True if the expression parser should enforce the presence of a valid class pointer in order to genera...
Definition: ClangUserExpression.h:248
lldb_private::ClangExpressionSourceCode::WrapKind
WrapKind
The possible ways an expression can be wrapped.
Definition: ClangExpressionSourceCode.h:33
Address.h
lldb_private::ClangUserExpression::ResultDelegate
Definition: ClangUserExpression.h:208
lldb-private.h
lldb_private::ClangUserExpression::ResultDelegate::m_target_sp
lldb::TargetSP m_target_sp
Definition: ClangUserExpression.h:220
lldb_private::ClangUserExpression::m_parser
std::unique_ptr< ClangExpressionParser > m_parser
The parser instance we used to parse the expression.
Definition: ClangUserExpression.h:234
lldb_private::ClangUserExpression::m_type_system_helper
ClangUserExpressionHelper m_type_system_helper
Definition: ClangUserExpression.h:206
lldb_private::ClangUserExpression::ResultDelegate::m_variable
lldb::ExpressionVariableSP m_variable
Definition: ClangUserExpression.h:219
Materializer.h
lldb_private::Status
Definition: Status.h:44
lldb_private::ValueObject
ValueObject:
Definition: ValueObject.h:105
lldb_private::ClangUserExpression::ClangUserExpressionHelper::m_struct_extractor_up
std::unique_ptr< ASTStructExtractor > m_struct_extractor_up
The class that generates the argument struct layout.
Definition: ClangUserExpression.h:85
lldb_private::ClangUserExpression::ResetDeclMap
void ResetDeclMap(ExecutionContext &exe_ctx, Materializer::PersistentVariableDelegate &result_delegate, bool keep_result_in_memory)
Definition: ClangUserExpression.h:160
lldb_private::ClangUserExpression::GetResultAfterDematerialization
lldb::ExpressionVariableSP GetResultAfterDematerialization(ExecutionContextScope *exe_scope) override
Definition: ClangUserExpression.cpp:941
ASTStructExtractor.h
lldb_private::DiagnosticManager
Definition: DiagnosticManager.h:93
ClangExpressionDeclMap.h
lldb_private::ClangUserExpression::ID
static char ID
Definition: ClangUserExpression.h:41
lldb_private::ClangUserExpression::PrepareForParsing
bool PrepareForParsing(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, bool for_completion)
Definition: ClangUserExpression.cpp:526
lldb_private::ClangExpressionHelper
Definition: ClangExpressionHelper.h:30
lldb_private::ClangUserExpression::Parse
bool Parse(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, lldb_private::ExecutionPolicy execution_policy, bool keep_result_in_memory, bool generate_debug_info) override
Parse the expression.
Definition: ClangUserExpression.cpp:649
lldb-forward.h
lldb_private::ClangUserExpression::AddArguments
bool AddArguments(ExecutionContext &exe_ctx, std::vector< lldb::addr_t > &args, lldb::addr_t struct_address, DiagnosticManager &diagnostic_manager) override
Definition: ClangUserExpression.cpp:871
lldb_private::ClangUserExpression::ResultDelegate::DidDematerialize
void DidDematerialize(lldb::ExpressionVariableSP &variable) override
Definition: ClangUserExpression.cpp:982
lldb_private::PersistentExpressionState
Definition: ExpressionVariable.h:203
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::ClangUserExpression::m_user_expression_start_pos
llvm::Optional< size_t > m_user_expression_start_pos
The absolute character position in the transformed source code where the user code (as typed by the u...
Definition: ClangUserExpression.h:229
lldb_private::ClangUserExpression::ClangUserExpressionHelper::m_expr_decl_map_up
std::unique_ptr< ClangExpressionDeclMap > m_expr_decl_map_up
Definition: ClangUserExpression.h:84
lldb_private::ClangUserExpression::ClangUserExpressionHelper::ASTTransformer
clang::ASTConsumer * ASTTransformer(clang::ASTConsumer *passthrough) override
Return the object that the parser should allow to access ASTs.
Definition: ClangUserExpression.cpp:964
lldb_private::ClangUserExpression::DidImportCxxModules
bool DidImportCxxModules() const
Returns true iff this expression is using any imported C++ modules.
Definition: ClangUserExpression.h:172
ClangExpressionVariable.h
lldb_private::ClangUserExpression::Complete
bool Complete(ExecutionContext &exe_ctx, CompletionRequest &request, unsigned complete_pos) override
Attempts to find possible command line completions for the given (possible incomplete) user expressio...
Definition: ClangUserExpression.cpp:803
lldb_private::ClangUserExpression::kDefaultTimeout
@ kDefaultTimeout
Definition: ClangUserExpression.h:49
LLVMUserExpression.h
lldb_private::Expression
Definition: Expression.h:33
lldb_private::ClangUserExpression::m_include_directories
std::vector< std::string > m_include_directories
The include directories that should be used when parsing the expression.
Definition: ClangUserExpression.h:224
ClangExpressionHelper.h
lldb_private::ClangUserExpression::GetWrapKind
ClangExpressionSourceCode::WrapKind GetWrapKind() const
Defines how the current expression should be wrapped.
Definition: ClangUserExpression.cpp:401
ExecutionContext.h
lldb_private::ClangUserExpression::DeclMap
ClangExpressionDeclMap * DeclMap()
Definition: ClangUserExpression.h:156
lldb_private::ClangUserExpression::ResultDelegate::GetVariable
lldb::ExpressionVariableSP & GetVariable()
Definition: ClangUserExpression.cpp:992
lldb_private::ClangExpressionDeclMap
Definition: ClangExpressionDeclMap.h:56
lldb_private::CompletionRequest
Definition: CompletionRequest.h:100