lldb/source/Plugins/ExpressionParser/Clang/ClangUserExpression.h

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