contrib/llvm-project/clang/include/clang/ASTMatchers/Dynamic/Registry.h

   1 //===- Registry.h - Matcher registry ----------------------------*- 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 /// \file
  10 /// Registry of all known matchers.
  11 ///
  12 /// The registry provides a generic interface to construct any matcher by name.
  13 //
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_CLANG_ASTMATCHERS_DYNAMIC_REGISTRY_H
  17 #define LLVM_CLANG_ASTMATCHERS_DYNAMIC_REGISTRY_H
  18
  19 #include "clang/ASTMatchers/Dynamic/Diagnostics.h"
  20 #include "clang/ASTMatchers/Dynamic/VariantValue.h"
  21 #include "llvm/ADT/ArrayRef.h"
  22 #include "llvm/ADT/Optional.h"
  23 #include "llvm/ADT/StringRef.h"
  24 #include <string>
  25 #include <utility>
  26 #include <vector>
  27
  28 namespace clang {
  29 namespace ast_matchers {
  30 namespace dynamic {
  31
  32 namespace internal {
  33
  34 class MatcherDescriptor;
  35
  36 } // namespace internal
  37
  38 using MatcherCtor = const internal::MatcherDescriptor *;
  39
  40 struct MatcherCompletion {
  41   MatcherCompletion() = default;
  42   MatcherCompletion(StringRef TypedText, StringRef MatcherDecl,
  43                     unsigned Specificity)
  44       : TypedText(TypedText), MatcherDecl(MatcherDecl),
  45         Specificity(Specificity) {}
  46
  47   bool operator==(const MatcherCompletion &Other) const {
  48     return TypedText == Other.TypedText && MatcherDecl == Other.MatcherDecl;
  49   }
  50
  51   /// The text to type to select this matcher.
  52   std::string TypedText;
  53
  54   /// The "declaration" of the matcher, with type information.
  55   std::string MatcherDecl;
  56
  57   /// Value corresponding to the "specificity" of the converted matcher.
  58   ///
  59   /// Zero specificity indicates that this conversion would produce a trivial
  60   /// matcher that will either always or never match.
  61   /// Such matchers are excluded from code completion results.
  62   unsigned Specificity;
  63 };
  64
  65 class Registry {
  66 public:
  67   Registry() = delete;
  68
  69   /// Look up a matcher in the registry by name,
  70   ///
  71   /// \return An opaque value which may be used to refer to the matcher
  72   /// constructor, or Optional<MatcherCtor>() if not found.
  73   static llvm::Optional<MatcherCtor> lookupMatcherCtor(StringRef MatcherName);
  74
  75   /// Compute the list of completion types for \p Context.
  76   ///
  77   /// Each element of \p Context represents a matcher invocation, going from
  78   /// outermost to innermost. Elements are pairs consisting of a reference to
  79   /// the matcher constructor and the index of the next element in the
  80   /// argument list of that matcher (or for the last element, the index of
  81   /// the completion point in the argument list). An empty list requests
  82   /// completion for the root matcher.
  83   static std::vector<ArgKind> getAcceptedCompletionTypes(
  84       llvm::ArrayRef<std::pair<MatcherCtor, unsigned>> Context);
  85
  86   /// Compute the list of completions that match any of
  87   /// \p AcceptedTypes.
  88   ///
  89   /// \param AcceptedTypes All types accepted for this completion.
  90   ///
  91   /// \return All completions for the specified types.
  92   /// Completions should be valid when used in \c lookupMatcherCtor().
  93   /// The matcher constructed from the return of \c lookupMatcherCtor()
  94   /// should be convertible to some type in \p AcceptedTypes.
  95   static std::vector<MatcherCompletion>
  96   getMatcherCompletions(ArrayRef<ArgKind> AcceptedTypes);
  97
  98   /// Construct a matcher from the registry.
  99   ///
 100   /// \param Ctor The matcher constructor to instantiate.
 101   ///
 102   /// \param NameRange The location of the name in the matcher source.
 103   ///   Useful for error reporting.
 104   ///
 105   /// \param Args The argument list for the matcher. The number and types of the
 106   ///   values must be valid for the matcher requested. Otherwise, the function
 107   ///   will return an error.
 108   ///
 109   /// \return The matcher object constructed if no error was found.
 110   ///   A null matcher if the number of arguments or argument types do not match
 111   ///   the signature.  In that case \c Error will contain the description of
 112   ///   the error.
 113   static VariantMatcher constructMatcher(MatcherCtor Ctor,
 114                                          SourceRange NameRange,
 115                                          ArrayRef<ParserValue> Args,
 116                                          Diagnostics *Error);
 117
 118   /// Construct a matcher from the registry and bind it.
 119   ///
 120   /// Similar the \c constructMatcher() above, but it then tries to bind the
 121   /// matcher to the specified \c BindID.
 122   /// If the matcher is not bindable, it sets an error in \c Error and returns
 123   /// a null matcher.
 124   static VariantMatcher constructBoundMatcher(MatcherCtor Ctor,
 125                                               SourceRange NameRange,
 126                                               StringRef BindID,
 127                                               ArrayRef<ParserValue> Args,
 128                                               Diagnostics *Error);
 129 };
 130
 131 } // namespace dynamic
 132 } // namespace ast_matchers
 133 } // namespace clang
 134
 135 #endif // LLVM_CLANG_AST_MATCHERS_DYNAMIC_REGISTRY_H