contrib/llvm/tools/clang/include/clang/ASTMatchers/Dynamic/Registry.h

   1 //===--- Registry.h - Matcher registry -----*- 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 /// \file
  11 /// \brief Registry of all known matchers.
  12 ///
  13 /// The registry provides a generic interface to construct any matcher by name.
  14 ///
  15 //===----------------------------------------------------------------------===//
  16
  17 #ifndef LLVM_CLANG_AST_MATCHERS_DYNAMIC_REGISTRY_H
  18 #define LLVM_CLANG_AST_MATCHERS_DYNAMIC_REGISTRY_H
  19
  20 #include "clang/ASTMatchers/Dynamic/Diagnostics.h"
  21 #include "clang/ASTMatchers/Dynamic/VariantValue.h"
  22 #include "clang/Basic/LLVM.h"
  23 #include "llvm/ADT/ArrayRef.h"
  24 #include "llvm/ADT/Optional.h"
  25 #include "llvm/ADT/StringRef.h"
  26
  27 namespace clang {
  28 namespace ast_matchers {
  29 namespace dynamic {
  30
  31 namespace internal {
  32 class MatcherDescriptor;
  33 }
  34
  35 typedef const internal::MatcherDescriptor *MatcherCtor;
  36
  37 struct MatcherCompletion {
  38   MatcherCompletion() {}
  39   MatcherCompletion(StringRef TypedText, StringRef MatcherDecl)
  40       : TypedText(TypedText), MatcherDecl(MatcherDecl) {}
  41
  42   /// \brief The text to type to select this matcher.
  43   std::string TypedText;
  44
  45   /// \brief The "declaration" of the matcher, with type information.
  46   std::string MatcherDecl;
  47
  48   bool operator==(const MatcherCompletion &Other) const {
  49     return TypedText == Other.TypedText && MatcherDecl == Other.MatcherDecl;
  50   }
  51 };
  52
  53 class Registry {
  54 public:
  55   /// \brief Look up a matcher in the registry by name,
  56   ///
  57   /// \return An opaque value which may be used to refer to the matcher
  58   /// constructor, or Optional<MatcherCtor>() if not found.
  59   static llvm::Optional<MatcherCtor> lookupMatcherCtor(StringRef MatcherName);
  60
  61   /// \brief Compute the list of completions for \p Context.
  62   ///
  63   /// Each element of \p Context represents a matcher invocation, going from
  64   /// outermost to innermost. Elements are pairs consisting of a reference to the
  65   /// matcher constructor and the index of the next element in the argument list
  66   /// of that matcher (or for the last element, the index of the completion
  67   /// point in the argument list). An empty list requests completion for the
  68   /// root matcher.
  69   ///
  70   /// The completions are ordered first by decreasing relevance, then
  71   /// alphabetically.  Relevance is determined by how closely the matcher's
  72   /// type matches that of the context. For example, if the innermost matcher
  73   /// takes a FunctionDecl matcher, the FunctionDecl matchers are returned
  74   /// first, followed by the ValueDecl matchers, then NamedDecl, then Decl, then
  75   /// polymorphic matchers.
  76   ///
  77   /// Matchers which are technically convertible to the innermost context but
  78   /// which would match either all or no nodes are excluded. For example,
  79   /// namedDecl and varDecl are excluded in a FunctionDecl context, because
  80   /// those matchers would match respectively all or no nodes in such a context.
  81   static std::vector<MatcherCompletion>
  82   getCompletions(ArrayRef<std::pair<MatcherCtor, unsigned> > Context);
  83
  84   /// \brief Construct a matcher from the registry.
  85   ///
  86   /// \param Ctor The matcher constructor to instantiate.
  87   ///
  88   /// \param NameRange The location of the name in the matcher source.
  89   ///   Useful for error reporting.
  90   ///
  91   /// \param Args The argument list for the matcher. The number and types of the
  92   ///   values must be valid for the matcher requested. Otherwise, the function
  93   ///   will return an error.
  94   ///
  95   /// \return The matcher object constructed if no error was found.
  96   ///   A null matcher if the number of arguments or argument types do not match
  97   ///   the signature.  In that case \c Error will contain the description of
  98   ///   the error.
  99   static VariantMatcher constructMatcher(MatcherCtor Ctor,
 100                                          const SourceRange &NameRange,
 101                                          ArrayRef<ParserValue> Args,
 102                                          Diagnostics *Error);
 103
 104   /// \brief Construct a matcher from the registry and bind it.
 105   ///
 106   /// Similar the \c constructMatcher() above, but it then tries to bind the
 107   /// matcher to the specified \c BindID.
 108   /// If the matcher is not bindable, it sets an error in \c Error and returns
 109   /// a null matcher.
 110   static VariantMatcher constructBoundMatcher(MatcherCtor Ctor,
 111                                               const SourceRange &NameRange,
 112                                               StringRef BindID,
 113                                               ArrayRef<ParserValue> Args,
 114                                               Diagnostics *Error);
 115
 116 private:
 117   Registry() LLVM_DELETED_FUNCTION;
 118 };
 119
 120 }  // namespace dynamic
 121 }  // namespace ast_matchers
 122 }  // namespace clang
 123
 124 #endif  // LLVM_CLANG_AST_MATCHERS_DYNAMIC_REGISTRY_H