//===- Registry.h - Matcher registry ----------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
/// \file
/// Registry of all known matchers.
///
/// The registry provides a generic interface to construct any matcher by name.
//
//===----------------------------------------------------------------------===//
#ifndef LLVM_CLANG_ASTMATCHERS_DYNAMIC_REGISTRY_H
#define LLVM_CLANG_ASTMATCHERS_DYNAMIC_REGISTRY_H
#include "clang/ASTMatchers/Dynamic/Diagnostics.h"
#include "clang/ASTMatchers/Dynamic/VariantValue.h"
#include "llvm/ADT/ArrayRef.h"
#include "llvm/ADT/StringRef.h"
#include <optional>
#include <string>
#include <utility>
#include <vector>
namespace clang {
namespace ast_matchers {
namespace dynamic {
namespace internal {
class MatcherDescriptor;
/// A smart (owning) pointer for MatcherDescriptor. We can't use unique_ptr
/// because MatcherDescriptor is forward declared
class MatcherDescriptorPtr {
public:
explicit MatcherDescriptorPtr(MatcherDescriptor *);
~MatcherDescriptorPtr();
MatcherDescriptorPtr(MatcherDescriptorPtr &&) = default;
MatcherDescriptorPtr &operator=(MatcherDescriptorPtr &&) = default;
MatcherDescriptorPtr(const MatcherDescriptorPtr &) = delete;
MatcherDescriptorPtr &operator=(const MatcherDescriptorPtr &) = delete;
MatcherDescriptor *get() { return Ptr; }
private:
MatcherDescriptor *Ptr;
};
} // namespace internal
using MatcherCtor = const internal::MatcherDescriptor *;
struct MatcherCompletion {
MatcherCompletion() = default;
MatcherCompletion(StringRef TypedText, StringRef MatcherDecl,
unsigned Specificity)
: TypedText(TypedText), MatcherDecl(MatcherDecl),
Specificity(Specificity) {}
bool operator==(const MatcherCompletion &Other) const {
return TypedText == Other.TypedText && MatcherDecl == Other.MatcherDecl;
}
/// The text to type to select this matcher.
std::string TypedText;
/// The "declaration" of the matcher, with type information.
std::string MatcherDecl;
/// Value corresponding to the "specificity" of the converted matcher.
///
/// Zero specificity indicates that this conversion would produce a trivial
/// matcher that will either always or never match.
/// Such matchers are excluded from code completion results.
unsigned Specificity;
};
class Registry {
public:
Registry() = delete;
static ASTNodeKind nodeMatcherType(MatcherCtor);
static bool isBuilderMatcher(MatcherCtor Ctor);
static internal::MatcherDescriptorPtr
buildMatcherCtor(MatcherCtor, SourceRange NameRange,
ArrayRef<ParserValue> Args, Diagnostics *Error);
/// Look up a matcher in the registry by name,
///
/// \return An opaque value which may be used to refer to the matcher
/// constructor, or std::optional<MatcherCtor>() if not found.
static std::optional<MatcherCtor> lookupMatcherCtor(StringRef MatcherName);
/// Compute the list of completion types for \p Context.
///
/// Each element of \p Context represents a matcher invocation, going from
/// outermost to innermost. Elements are pairs consisting of a reference to
/// the matcher constructor and the index of the next element in the
/// argument list of that matcher (or for the last element, the index of
/// the completion point in the argument list). An empty list requests
/// completion for the root matcher.
static std::vector<ArgKind> getAcceptedCompletionTypes(
llvm::ArrayRef<std::pair<MatcherCtor, unsigned>> Context);
/// Compute the list of completions that match any of
/// \p AcceptedTypes.
///
/// \param AcceptedTypes All types accepted for this completion.
///
/// \return All completions for the specified types.
/// Completions should be valid when used in \c lookupMatcherCtor().
/// The matcher constructed from the return of \c lookupMatcherCtor()
/// should be convertible to some type in \p AcceptedTypes.
static std::vector<MatcherCompletion>
getMatcherCompletions(ArrayRef<ArgKind> AcceptedTypes);
/// Construct a matcher from the registry.
///
/// \param Ctor The matcher constructor to instantiate.
///
/// \param NameRange The location of the name in the matcher source.
/// Useful for error reporting.
///
/// \param Args The argument list for the matcher. The number and types of the
/// values must be valid for the matcher requested. Otherwise, the function
/// will return an error.
///
/// \return The matcher object constructed if no error was found.
/// A null matcher if the number of arguments or argument types do not match
/// the signature. In that case \c Error will contain the description of
/// the error.
static VariantMatcher constructMatcher(MatcherCtor Ctor,
SourceRange NameRange,
ArrayRef<ParserValue> Args,
Diagnostics *Error);
/// Construct a matcher from the registry and bind it.
///
/// Similar the \c constructMatcher() above, but it then tries to bind the
/// matcher to the specified \c BindID.
/// If the matcher is not bindable, it sets an error in \c Error and returns
/// a null matcher.
static VariantMatcher constructBoundMatcher(MatcherCtor Ctor,
SourceRange NameRange,
StringRef BindID,
ArrayRef<ParserValue> Args,
Diagnostics *Error);
};
} // namespace dynamic
} // namespace ast_matchers
} // namespace clang
#endif // LLVM_CLANG_ASTMATCHERS_DYNAMIC_REGISTRY_H