contrib/llvm/tools/lldb/include/lldb/Expression/ClangUtilityFunction.h

   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
  27 namespace 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 //----------------------------------------------------------------------
  39 class ClangUtilityFunction : public ClangExpression
  40 {
  41 public:
  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
 169 private:
 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_