1 //===-- ExpressionParser.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 liblldb_ExpressionParser_h_ 10 #define liblldb_ExpressionParser_h_ 11 12 #include "lldb/Utility/CompletionRequest.h" 13 #include "lldb/Utility/Status.h" 14 #include "lldb/lldb-private-enumerations.h" 15 #include "lldb/lldb-public.h" 16 17 namespace lldb_private { 18 19 class IRExecutionUnit; 20 21 /// \class ExpressionParser ExpressionParser.h 22 /// "lldb/Expression/ExpressionParser.h" Encapsulates an instance of a 23 /// compiler that can parse expressions. 24 /// 25 /// ExpressionParser is the base class for llvm based Expression parsers. 26 class ExpressionParser { 27 public: 28 /// Constructor 29 /// 30 /// Initializes class variables. 31 /// 32 /// \param[in] exe_scope, 33 /// If non-NULL, an execution context scope that can help to 34 /// correctly create an expression with a valid process for 35 /// optional tuning Objective-C runtime support. Can be NULL. 36 /// 37 /// \param[in] expr 38 /// The expression to be parsed. 39 ExpressionParser(ExecutionContextScope *exe_scope, Expression &expr, 40 bool generate_debug_info) 41 : m_expr(expr), m_generate_debug_info(generate_debug_info) {} 42 43 /// Destructor 44 virtual ~ExpressionParser(){}; 45 46 /// Attempts to find possible command line completions for the given 47 /// expression. 48 /// 49 /// \param[out] request 50 /// The completion request to fill out. The completion should be a string 51 /// that would complete the current token at the cursor position. 52 /// Note that the string in the list replaces the current token 53 /// in the command line. 54 /// 55 /// \param[in] line 56 /// The line with the completion cursor inside the expression as a string. 57 /// The first line in the expression has the number 0. 58 /// 59 /// \param[in] pos 60 /// The character position in the line with the completion cursor. 61 /// If the value is 0, then the cursor is on top of the first character 62 /// in the line (i.e. the user has requested completion from the start of 63 /// the expression). 64 /// 65 /// \param[in] typed_pos 66 /// The cursor position in the line as typed by the user. If the user 67 /// expression has not been transformed in some form (e.g. wrapping it 68 /// in a function body for C languages), then this is equal to the 69 /// 'pos' parameter. The semantics of this value are otherwise equal to 70 /// 'pos' (e.g. a value of 0 means the cursor is at start of the 71 /// expression). 72 /// 73 /// \return 74 /// True if we added any completion results to the output; 75 /// false otherwise. 76 virtual bool Complete(CompletionRequest &request, unsigned line, unsigned pos, 77 unsigned typed_pos) = 0; 78 79 /// Parse a single expression and convert it to IR using Clang. Don't wrap 80 /// the expression in anything at all. 81 /// 82 /// \param[in] diagnostic_manager 83 /// The diagnostic manager in which to store the errors and warnings. 84 /// 85 /// \return 86 /// The number of errors encountered during parsing. 0 means 87 /// success. 88 virtual unsigned Parse(DiagnosticManager &diagnostic_manager) = 0; 89 90 /// Try to use the FixIts in the diagnostic_manager to rewrite the 91 /// expression. If successful, the rewritten expression is stored in the 92 /// diagnostic_manager, get it out with GetFixedExpression. 93 /// 94 /// \param[in] diagnostic_manager 95 /// The diagnostic manager containing fixit's to apply. 96 /// 97 /// \return 98 /// \b true if the rewrite was successful, \b false otherwise. 99 virtual bool RewriteExpression(DiagnosticManager &diagnostic_manager) { 100 return false; 101 } 102 103 /// Ready an already-parsed expression for execution, possibly evaluating it 104 /// statically. 105 /// 106 /// \param[out] func_addr 107 /// The address to which the function has been written. 108 /// 109 /// \param[out] func_end 110 /// The end of the function's allocated memory region. (func_addr 111 /// and func_end do not delimit an allocated region; the allocated 112 /// region may begin before func_addr.) 113 /// 114 /// \param[in] execution_unit_sp 115 /// After parsing, ownership of the execution unit for 116 /// for the expression is handed to this shared pointer. 117 /// 118 /// \param[in] exe_ctx 119 /// The execution context to write the function into. 120 /// 121 /// \param[out] can_interpret 122 /// Set to true if the expression could be interpreted statically; 123 /// untouched otherwise. 124 /// 125 /// \param[in] execution_policy 126 /// Determines whether the expression must be JIT-compiled, must be 127 /// evaluated statically, or whether this decision may be made 128 /// opportunistically. 129 /// 130 /// \return 131 /// An error code indicating the success or failure of the operation. 132 /// Test with Success(). 133 virtual Status 134 PrepareForExecution(lldb::addr_t &func_addr, lldb::addr_t &func_end, 135 std::shared_ptr<IRExecutionUnit> &execution_unit_sp, 136 ExecutionContext &exe_ctx, bool &can_interpret, 137 lldb_private::ExecutionPolicy execution_policy) = 0; 138 139 bool GetGenerateDebugInfo() const { return m_generate_debug_info; } 140 141 protected: 142 Expression &m_expr; ///< The expression to be parsed 143 bool m_generate_debug_info; 144 }; 145 } 146 147 #endif // liblldb_ExpressionParser_h_ 148