ClangUserExpression.h revision a91dd997b1e809c67901b7ac481942cacae19150 
1//===-- ClangUserExpression.h -----------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef liblldb_ClangUserExpression_h_
11#define liblldb_ClangUserExpression_h_
12
13// C Includes
14// C++ Includes
15#include <string>
16#include <map>
17#include <memory>
18#include <vector>
19
20// Other libraries and framework includes
21// Project includes
22
23#include "lldb/lldb-forward.h"
24#include "lldb/lldb-private.h"
25#include "lldb/Core/ClangForward.h"
26#include "lldb/Expression/ClangExpression.h"
27#include "lldb/Expression/ClangExpressionVariable.h"
28#include "lldb/Symbol/TaggedASTType.h"
29
30#include "llvm/ExecutionEngine/JITMemoryManager.h"
31
32namespace lldb_private
33{
34
35//----------------------------------------------------------------------
36/// @class ClangUserExpression ClangUserExpression.h "lldb/Expression/ClangUserExpression.h"
37/// @brief Encapsulates a single expression for use with Clang
38///
39/// LLDB uses expressions for various purposes, notably to call functions
40/// and as a backend for the expr command.  ClangUserExpression encapsulates
41/// the objects needed to parse and interpret or JIT an expression.  It
42/// uses the Clang parser to produce LLVM IR from the expression.
43//----------------------------------------------------------------------
44class ClangUserExpression : public ClangExpression
45{
46public:
47    //------------------------------------------------------------------
48    /// Constructor
49    ///
50    /// @param[in] expr
51    ///     The expression to parse.
52    ///
53    /// @param[in] expr_prefix
54    ///     If non-NULL, a C string containing translation-unit level
55    ///     definitions to be included when the expression is parsed.
56    //------------------------------------------------------------------
57    ClangUserExpression (const char *expr,
58                         const char *expr_prefix);
59
60    //------------------------------------------------------------------
61    /// Destructor
62    //------------------------------------------------------------------
63    virtual
64    ~ClangUserExpression ();
65
66    //------------------------------------------------------------------
67    /// Parse the expression
68    ///
69    /// @param[in] error_stream
70    ///     A stream to print parse errors and warnings to.
71    ///
72    /// @param[in] exe_ctx
73    ///     The execution context to use when looking up entities that
74    ///     are needed for parsing (locations of functions, types of
75    ///     variables, persistent variables, etc.)
76    ///
77    /// @param[in] desired_type
78    ///     The type that the expression should be coerced to.  If NULL,
79    ///     inferred from the expression itself.
80    ///
81    /// @return
82    ///     True on success (no errors); false otherwise.
83    //------------------------------------------------------------------
84    bool
85    Parse (Stream &error_stream,
86           ExecutionContext &exe_ctx,
87           TypeFromUser desired_type);
88
89    //------------------------------------------------------------------
90    /// Execute the parsed expression
91    ///
92    /// @param[in] error_stream
93    ///     A stream to print errors to.
94    ///
95    /// @param[in] exe_ctx
96    ///     The execution context to use when looking up entities that
97    ///     are needed for parsing (locations of variables, etc.)
98    ///
99    /// @param[in] discard_on_error
100    ///     If true, and the execution stops before completion, we unwind the
101    ///     function call, and return the program state to what it was before the
102    ///     execution.  If false, we leave the program in the stopped state.
103    ///
104    /// @param[in] result
105    ///     A pointer to direct at the persistent variable in which the
106    ///     expression's result is stored.
107    ///
108    /// @return
109    ///     True on success; false otherwise.
110    //------------------------------------------------------------------
111    bool
112    Execute (Stream &error_stream,
113             ExecutionContext &exe_ctx,
114             bool discard_on_error,
115             ClangExpressionVariable *&result);
116
117    ThreadPlan *
118    GetThreadPlanToExecuteJITExpression (Stream &error_stream,
119                                         ExecutionContext &exe_ctx);
120    bool
121    FinalizeJITExecution (Stream &error_stream,
122                          ExecutionContext &exe_ctx,
123                          ClangExpressionVariable *&result);
124
125    //------------------------------------------------------------------
126    /// Return the string that the parser should parse.  Must be a full
127    /// translation unit.
128    //------------------------------------------------------------------
129    const char *
130    Text ()
131    {
132        return m_transformed_text.c_str();
133    }
134
135    //------------------------------------------------------------------
136    /// Return the string that the user typed.
137    //------------------------------------------------------------------
138    const char *
139    GetUserText ()
140    {
141        return m_expr_text.c_str();
142    }
143
144    //------------------------------------------------------------------
145    /// Return the function name that should be used for executing the
146    /// expression.  Text() should contain the definition of this
147    /// function.
148    //------------------------------------------------------------------
149    const char *
150    FunctionName ()
151    {
152        return "$__lldb_expr";
153    }
154
155    //------------------------------------------------------------------
156    /// Return the object that the parser should use when resolving external
157    /// values.  May be NULL if everything should be self-contained.
158    //------------------------------------------------------------------
159    ClangExpressionDeclMap *
160    DeclMap ()
161    {
162        return m_expr_decl_map.get();
163    }
164
165    //------------------------------------------------------------------
166    /// Return the object that the parser should use when registering
167    /// local variables.  May be NULL if the Expression doesn't care.
168    //------------------------------------------------------------------
169    ClangExpressionVariableStore *
170    LocalVariables ()
171    {
172        return m_local_variables.get();
173    }
174
175    //------------------------------------------------------------------
176    /// Return the object that the parser should allow to access ASTs.
177    /// May be NULL if the ASTs do not need to be transformed.
178    ///
179    /// @param[in] passthrough
180    ///     The ASTConsumer that the returned transformer should send
181    ///     the ASTs to after transformation.
182    //------------------------------------------------------------------
183    clang::ASTConsumer *
184    ASTTransformer (clang::ASTConsumer *passthrough);
185
186    //------------------------------------------------------------------
187    /// Return the stream that the parser should use to write DWARF
188    /// opcodes.
189    //------------------------------------------------------------------
190    StreamString &
191    DwarfOpcodeStream ();
192
193    //------------------------------------------------------------------
194    /// Return true if validation code should be inserted into the
195    /// expression.
196    //------------------------------------------------------------------
197    bool
198    NeedsValidation ()
199    {
200        return true;
201    }
202
203    //------------------------------------------------------------------
204    /// Return true if external variables in the expression should be
205    /// resolved.
206    //------------------------------------------------------------------
207    bool
208    NeedsVariableResolution ()
209    {
210        return true;
211    }
212
213    //------------------------------------------------------------------
214    /// Evaluate one expression and return its result.
215    ///
216    /// @param[in] exe_ctx
217    ///     The execution context to use when evaluating the expression.
218    ///
219    /// @param[in] expr_cstr
220    ///     A C string containing the expression to be evaluated.
221    ///
222    /// @param[in] expr_prefix
223    ///     If non-NULL, a C string containing translation-unit level
224    ///     definitions to be included when the expression is parsed.
225    //------------------------------------------------------------------
226    static lldb::ValueObjectSP
227    Evaluate (ExecutionContext &exe_ctx,
228              bool discard_on_error,
229              const char *expr_cstr,
230              const char *expr_prefix);
231
232private:
233    //------------------------------------------------------------------
234    /// Populate m_cplusplus and m_objetivec based on the environment.
235    //------------------------------------------------------------------
236    void
237    ScanContext(ExecutionContext &exe_ctx);
238
239    bool
240    PrepareToExecuteJITExpression (Stream &error_stream,
241                                   ExecutionContext &exe_ctx,
242                                   lldb::addr_t &struct_address,
243                                   lldb::addr_t &object_ptr);
244
245    std::string                                 m_expr_text;            ///< The text of the expression, as typed by the user
246    std::string                                 m_expr_prefix;          ///< The text of the translation-level definitions, as provided by the user
247    std::string                                 m_transformed_text;     ///< The text of the expression, as send to the parser
248    TypeFromUser                                m_desired_type;         ///< The type to coerce the expression's result to.  If NULL, inferred from the expression.
249
250    std::auto_ptr<ClangExpressionDeclMap>       m_expr_decl_map;        ///< The map to use when parsing and materializing the expression.
251    std::auto_ptr<ClangExpressionVariableStore> m_local_variables;      ///< The local expression variables, if the expression is DWARF.
252    std::auto_ptr<StreamString>                 m_dwarf_opcodes;        ///< The DWARF opcodes for the expression.  May be NULL.
253    lldb::addr_t                                m_jit_addr;             ///< The address of the JITted code.  LLDB_INVALID_ADDRESS if invalid.
254
255    bool                                        m_cplusplus;            ///< True if the expression is compiled as a C++ member function (true if it was parsed when exe_ctx was in a C++ method).
256    bool                                        m_objectivec;           ///< True if the expression is compiled as an Objective-C method (true if it was parsed when exe_ctx was in an Objective-C method).
257    bool                                        m_needs_object_ptr;     ///< True if "this" or "self" must be looked up and passed in.  False if the expression doesn't really use them and they can be NULL.
258};
259
260} // namespace lldb_private
261
262#endif  // liblldb_ClangUserExpression_h_
263