1//===-- ClangUtilityFunction.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_ClangUtilityFunction_h_
11#define liblldb_ClangUtilityFunction_h_
12
13// C Includes
14// C++ Includes
15#include <string>
16#include <map>
17#include <vector>
18
19// Other libraries and framework includes
20// Project includes
21
22#include "lldb/lldb-forward.h"
23#include "lldb/lldb-private.h"
24#include "lldb/Core/ClangForward.h"
25#include "lldb/Expression/ClangExpression.h"
26
27namespace lldb_private
28{
29
30//----------------------------------------------------------------------
31/// @class ClangUtilityFunction ClangUtilityFunction.h "lldb/Expression/ClangUtilityFunction.h"
32/// @brief Encapsulates a single expression for use with Clang
33///
34/// LLDB uses expressions for various purposes, notably to call functions
35/// and as a backend for the expr command.  ClangUtilityFunction encapsulates
36/// a self-contained function meant to be used from other code.  Utility
37/// functions can perform error-checking for ClangUserExpressions,
38//----------------------------------------------------------------------
39class ClangUtilityFunction : public ClangExpression
40{
41public:
42    //------------------------------------------------------------------
43    /// Constructor
44    ///
45    /// @param[in] text
46    ///     The text of the function.  Must be a full translation unit.
47    ///
48    /// @param[in] name
49    ///     The name of the function, as used in the text.
50    //------------------------------------------------------------------
51    ClangUtilityFunction (const char *text,
52                          const char *name);
53
54    virtual
55    ~ClangUtilityFunction ();
56
57    //------------------------------------------------------------------
58    /// Install the utility function into a process
59    ///
60    /// @param[in] error_stream
61    ///     A stream to print parse errors and warnings to.
62    ///
63    /// @param[in] exe_ctx
64    ///     The execution context to install the utility function to.
65    ///
66    /// @return
67    ///     True on success (no errors); false otherwise.
68    //------------------------------------------------------------------
69    bool
70    Install (Stream &error_stream, ExecutionContext &exe_ctx);
71
72    //------------------------------------------------------------------
73    /// Check whether the given PC is inside the function
74    ///
75    /// Especially useful if the function dereferences NULL to indicate a failed
76    /// assert.
77    ///
78    /// @param[in] pc
79    ///     The program counter to check.
80    ///
81    /// @return
82    ///     True if the program counter falls within the function's bounds;
83    ///     false if not (or the function is not JIT compiled)
84    //------------------------------------------------------------------
85    bool
86    ContainsAddress (lldb::addr_t address)
87    {
88        // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS,
89        // so this always returns false if the function is not JIT compiled yet
90        return (address >= m_jit_start_addr && address < m_jit_end_addr);
91    }
92
93
94    //------------------------------------------------------------------
95    /// Return the string that the parser should parse.  Must be a full
96    /// translation unit.
97    //------------------------------------------------------------------
98    const char *
99    Text ()
100    {
101        return m_function_text.c_str();
102    }
103
104    //------------------------------------------------------------------
105    /// Return the function name that should be used for executing the
106    /// expression.  Text() should contain the definition of this
107    /// function.
108    //------------------------------------------------------------------
109    const char *
110    FunctionName ()
111    {
112        return m_function_name.c_str();
113    }
114
115    //------------------------------------------------------------------
116    /// Return the object that the parser should use when resolving external
117    /// values.  May be NULL if everything should be self-contained.
118    //------------------------------------------------------------------
119    ClangExpressionDeclMap *
120    DeclMap ()
121    {
122        return m_expr_decl_map.get();
123    }
124
125    //------------------------------------------------------------------
126    /// Return the object that the parser should use when registering
127    /// local variables.  May be NULL if the Expression doesn't care.
128    //------------------------------------------------------------------
129    ClangExpressionVariableList *
130    LocalVariables ()
131    {
132        return NULL;
133    }
134
135    //------------------------------------------------------------------
136    /// Return the object that the parser should allow to access ASTs.
137    /// May be NULL if the ASTs do not need to be transformed.
138    ///
139    /// @param[in] passthrough
140    ///     The ASTConsumer that the returned transformer should send
141    ///     the ASTs to after transformation.
142    //------------------------------------------------------------------
143    clang::ASTConsumer *
144    ASTTransformer (clang::ASTConsumer *passthrough)
145    {
146        return NULL;
147    }
148
149    //------------------------------------------------------------------
150    /// Return true if validation code should be inserted into the
151    /// expression.
152    //------------------------------------------------------------------
153    bool
154    NeedsValidation ()
155    {
156        return false;
157    }
158
159    //------------------------------------------------------------------
160    /// Return true if external variables in the expression should be
161    /// resolved.
162    //------------------------------------------------------------------
163    bool
164    NeedsVariableResolution ()
165    {
166        return false;
167    }
168
169private:
170    std::unique_ptr<ClangExpressionDeclMap>  m_expr_decl_map;    ///< The map to use when parsing and materializing the expression.
171    std::unique_ptr<IRExecutionUnit>         m_execution_unit_ap;
172
173    std::string                             m_function_text;    ///< The text of the function.  Must be a well-formed translation unit.
174    std::string                             m_function_name;    ///< The name of the function.
175};
176
177} // namespace lldb_private
178
179#endif  // liblldb_ClangUtilityFunction_h_
180