Registry.h revision 276479
1259701Sdim//===--- Registry.h - Matcher registry -----*- C++ -*-===//
2259701Sdim//
3259701Sdim//                     The LLVM Compiler Infrastructure
4259701Sdim//
5259701Sdim// This file is distributed under the University of Illinois Open Source
6259701Sdim// License. See LICENSE.TXT for details.
7259701Sdim//
8259701Sdim//===----------------------------------------------------------------------===//
9259701Sdim///
10259701Sdim/// \file
11259701Sdim/// \brief Registry of all known matchers.
12259701Sdim///
13259701Sdim/// The registry provides a generic interface to construct any matcher by name.
14259701Sdim///
15259701Sdim//===----------------------------------------------------------------------===//
16259701Sdim
17259701Sdim#ifndef LLVM_CLANG_AST_MATCHERS_DYNAMIC_REGISTRY_H
18259701Sdim#define LLVM_CLANG_AST_MATCHERS_DYNAMIC_REGISTRY_H
19259701Sdim
20259701Sdim#include "clang/ASTMatchers/Dynamic/Diagnostics.h"
21259701Sdim#include "clang/ASTMatchers/Dynamic/VariantValue.h"
22259701Sdim#include "clang/Basic/LLVM.h"
23259701Sdim#include "llvm/ADT/ArrayRef.h"
24276479Sdim#include "llvm/ADT/Optional.h"
25259701Sdim#include "llvm/ADT/StringRef.h"
26259701Sdim
27259701Sdimnamespace clang {
28259701Sdimnamespace ast_matchers {
29259701Sdimnamespace dynamic {
30259701Sdim
31276479Sdimnamespace internal {
32276479Sdimclass MatcherDescriptor;
33276479Sdim}
34276479Sdim
35276479Sdimtypedef const internal::MatcherDescriptor *MatcherCtor;
36276479Sdim
37276479Sdimstruct MatcherCompletion {
38276479Sdim  MatcherCompletion() {}
39276479Sdim  MatcherCompletion(StringRef TypedText, StringRef MatcherDecl)
40276479Sdim      : TypedText(TypedText), MatcherDecl(MatcherDecl) {}
41276479Sdim
42276479Sdim  /// \brief The text to type to select this matcher.
43276479Sdim  std::string TypedText;
44276479Sdim
45276479Sdim  /// \brief The "declaration" of the matcher, with type information.
46276479Sdim  std::string MatcherDecl;
47276479Sdim
48276479Sdim  bool operator==(const MatcherCompletion &Other) const {
49276479Sdim    return TypedText == Other.TypedText && MatcherDecl == Other.MatcherDecl;
50276479Sdim  }
51276479Sdim};
52276479Sdim
53259701Sdimclass Registry {
54259701Sdimpublic:
55276479Sdim  /// \brief Look up a matcher in the registry by name,
56259701Sdim  ///
57276479Sdim  /// \return An opaque value which may be used to refer to the matcher
58276479Sdim  /// constructor, or Optional<MatcherCtor>() if not found.
59276479Sdim  static llvm::Optional<MatcherCtor> lookupMatcherCtor(StringRef MatcherName);
60276479Sdim
61276479Sdim  /// \brief Compute the list of completions for \p Context.
62259701Sdim  ///
63276479Sdim  /// Each element of \p Context represents a matcher invocation, going from
64276479Sdim  /// outermost to innermost. Elements are pairs consisting of a reference to the
65276479Sdim  /// matcher constructor and the index of the next element in the argument list
66276479Sdim  /// of that matcher (or for the last element, the index of the completion
67276479Sdim  /// point in the argument list). An empty list requests completion for the
68276479Sdim  /// root matcher.
69259701Sdim  ///
70276479Sdim  /// The completions are ordered first by decreasing relevance, then
71276479Sdim  /// alphabetically.  Relevance is determined by how closely the matcher's
72276479Sdim  /// type matches that of the context. For example, if the innermost matcher
73276479Sdim  /// takes a FunctionDecl matcher, the FunctionDecl matchers are returned
74276479Sdim  /// first, followed by the ValueDecl matchers, then NamedDecl, then Decl, then
75276479Sdim  /// polymorphic matchers.
76276479Sdim  ///
77276479Sdim  /// Matchers which are technically convertible to the innermost context but
78276479Sdim  /// which would match either all or no nodes are excluded. For example,
79276479Sdim  /// namedDecl and varDecl are excluded in a FunctionDecl context, because
80276479Sdim  /// those matchers would match respectively all or no nodes in such a context.
81276479Sdim  static std::vector<MatcherCompletion>
82276479Sdim  getCompletions(ArrayRef<std::pair<MatcherCtor, unsigned> > Context);
83276479Sdim
84276479Sdim  /// \brief Construct a matcher from the registry.
85276479Sdim  ///
86276479Sdim  /// \param Ctor The matcher constructor to instantiate.
87276479Sdim  ///
88259701Sdim  /// \param NameRange The location of the name in the matcher source.
89259701Sdim  ///   Useful for error reporting.
90259701Sdim  ///
91259701Sdim  /// \param Args The argument list for the matcher. The number and types of the
92259701Sdim  ///   values must be valid for the matcher requested. Otherwise, the function
93259701Sdim  ///   will return an error.
94259701Sdim  ///
95259701Sdim  /// \return The matcher object constructed if no error was found.
96276479Sdim  ///   A null matcher if the number of arguments or argument types do not match
97276479Sdim  ///   the signature.  In that case \c Error will contain the description of
98276479Sdim  ///   the error.
99276479Sdim  static VariantMatcher constructMatcher(MatcherCtor Ctor,
100259701Sdim                                         const SourceRange &NameRange,
101259701Sdim                                         ArrayRef<ParserValue> Args,
102259701Sdim                                         Diagnostics *Error);
103259701Sdim
104259701Sdim  /// \brief Construct a matcher from the registry and bind it.
105259701Sdim  ///
106259701Sdim  /// Similar the \c constructMatcher() above, but it then tries to bind the
107259701Sdim  /// matcher to the specified \c BindID.
108259701Sdim  /// If the matcher is not bindable, it sets an error in \c Error and returns
109259701Sdim  /// a null matcher.
110276479Sdim  static VariantMatcher constructBoundMatcher(MatcherCtor Ctor,
111259701Sdim                                              const SourceRange &NameRange,
112259701Sdim                                              StringRef BindID,
113259701Sdim                                              ArrayRef<ParserValue> Args,
114259701Sdim                                              Diagnostics *Error);
115259701Sdim
116259701Sdimprivate:
117259701Sdim  Registry() LLVM_DELETED_FUNCTION;
118259701Sdim};
119259701Sdim
120259701Sdim}  // namespace dynamic
121259701Sdim}  // namespace ast_matchers
122259701Sdim}  // namespace clang
123259701Sdim
124259701Sdim#endif  // LLVM_CLANG_AST_MATCHERS_DYNAMIC_REGISTRY_H
125