//===--- ASTMatchersMacros.h - Structural query framework -------*- 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 // //===----------------------------------------------------------------------===// // // Defines macros that enable us to define new matchers in a single place. // Since a matcher is a function which returns a Matcher<T> object, where // T is the type of the actual implementation of the matcher, the macros allow // us to write matchers like functions and take care of the definition of the // class boilerplate. // // Note that when you define a matcher with an AST_MATCHER* macro, only the // function which creates the matcher goes into the current namespace - the // class that implements the actual matcher, which gets returned by the // generator function, is put into the 'internal' namespace. This allows us // to only have the functions (which is all the user cares about) in the // 'ast_matchers' namespace and hide the boilerplate. // // To define a matcher in user code, put it into your own namespace. This would // help to prevent ODR violations in case a matcher with the same name is // defined in multiple translation units: // // namespace my_matchers { // AST_MATCHER_P(clang::MemberExpr, Member, // clang::ast_matchers::internal::Matcher<clang::ValueDecl>, // InnerMatcher) { // return InnerMatcher.matches(*Node.getMemberDecl(), Finder, Builder); // } // } // namespace my_matchers // // Alternatively, an unnamed namespace may be used: // // namespace clang { // namespace ast_matchers { // namespace { // AST_MATCHER_P(MemberExpr, Member, // internal::Matcher<ValueDecl>, InnerMatcher) { // return InnerMatcher.matches(*Node.getMemberDecl(), Finder, Builder); // } // } // namespace // } // namespace ast_matchers // } // namespace clang // //===----------------------------------------------------------------------===// #ifndef LLVM_CLANG_ASTMATCHERS_ASTMATCHERSMACROS_H #define LLVM_CLANG_ASTMATCHERS_ASTMATCHERSMACROS_H /// AST_MATCHER_FUNCTION(ReturnType, DefineMatcher) { ... } /// defines a zero parameter function named DefineMatcher() that returns a /// ReturnType object. #define AST_MATCHER_FUNCTION(ReturnType, DefineMatcher) … /// AST_MATCHER_FUNCTION_P(ReturnType, DefineMatcher, ParamType, Param) { /// ... } /// defines a single-parameter function named DefineMatcher() that returns a /// ReturnType object. /// /// The code between the curly braces has access to the following variables: /// /// Param: the parameter passed to the function; its type /// is ParamType. /// /// The code should return an instance of ReturnType. #define AST_MATCHER_FUNCTION_P(ReturnType, DefineMatcher, ParamType, Param) … #define AST_MATCHER_FUNCTION_P_OVERLOAD(ReturnType, DefineMatcher, ParamType, \ Param, OverloadId) … /// AST_MATCHER(Type, DefineMatcher) { ... } /// defines a zero parameter function named DefineMatcher() that returns a /// Matcher<Type> object. /// /// The code between the curly braces has access to the following variables: /// /// Node: the AST node being matched; its type is Type. /// Finder: an ASTMatchFinder*. /// Builder: a BoundNodesTreeBuilder*. /// /// The code should return true if 'Node' matches. #define AST_MATCHER(Type, DefineMatcher) … /// AST_MATCHER_P(Type, DefineMatcher, ParamType, Param) { ... } /// defines a single-parameter function named DefineMatcher() that returns a /// Matcher<Type> object. /// /// The code between the curly braces has access to the following variables: /// /// Node: the AST node being matched; its type is Type. /// Param: the parameter passed to the function; its type /// is ParamType. /// Finder: an ASTMatchFinder*. /// Builder: a BoundNodesTreeBuilder*. /// /// The code should return true if 'Node' matches. #define AST_MATCHER_P(Type, DefineMatcher, ParamType, Param) … #define AST_MATCHER_P_OVERLOAD(Type, DefineMatcher, ParamType, Param, \ OverloadId) … /// AST_MATCHER_P2( /// Type, DefineMatcher, ParamType1, Param1, ParamType2, Param2) { ... } /// defines a two-parameter function named DefineMatcher() that returns a /// Matcher<Type> object. /// /// The code between the curly braces has access to the following variables: /// /// Node: the AST node being matched; its type is Type. /// Param1, Param2: the parameters passed to the function; their types /// are ParamType1 and ParamType2. /// Finder: an ASTMatchFinder*. /// Builder: a BoundNodesTreeBuilder*. /// /// The code should return true if 'Node' matches. #define AST_MATCHER_P2(Type, DefineMatcher, ParamType1, Param1, ParamType2, \ Param2) … #define AST_MATCHER_P2_OVERLOAD(Type, DefineMatcher, ParamType1, Param1, \ ParamType2, Param2, OverloadId) … /// Construct a type-list to be passed to the AST_POLYMORPHIC_MATCHER* /// macros. /// /// You can't pass something like \c TypeList<Foo, Bar> to a macro, because it /// will look at that as two arguments. However, you can pass /// \c void(TypeList<Foo, Bar>), which works thanks to the parenthesis. /// The \c PolymorphicMatcherWithParam* classes will unpack the function type to /// extract the TypeList object. #define AST_POLYMORPHIC_SUPPORTED_TYPES(...) … /// AST_POLYMORPHIC_MATCHER(DefineMatcher) { ... } /// defines a single-parameter function named DefineMatcher() that is /// polymorphic in the return type. /// /// The variables are the same as for AST_MATCHER, but NodeType will be deduced /// from the calling context. #define AST_POLYMORPHIC_MATCHER(DefineMatcher, ReturnTypesF) … /// AST_POLYMORPHIC_MATCHER_P(DefineMatcher, ParamType, Param) { ... } /// defines a single-parameter function named DefineMatcher() that is /// polymorphic in the return type. /// /// The variables are the same as for /// AST_MATCHER_P, with the addition of NodeType, which specifies the node type /// of the matcher Matcher<NodeType> returned by the function matcher(). /// /// FIXME: Pull out common code with above macro? #define AST_POLYMORPHIC_MATCHER_P(DefineMatcher, ReturnTypesF, ParamType, \ Param) … #define AST_POLYMORPHIC_MATCHER_P_OVERLOAD(DefineMatcher, ReturnTypesF, \ ParamType, Param, OverloadId) … /// AST_POLYMORPHIC_MATCHER_P2( /// DefineMatcher, ParamType1, Param1, ParamType2, Param2) { ... } /// defines a two-parameter function named matcher() that is polymorphic in /// the return type. /// /// The variables are the same as for AST_MATCHER_P2, with the /// addition of NodeType, which specifies the node type of the matcher /// Matcher<NodeType> returned by the function DefineMatcher(). #define AST_POLYMORPHIC_MATCHER_P2(DefineMatcher, ReturnTypesF, ParamType1, \ Param1, ParamType2, Param2) … #define AST_POLYMORPHIC_MATCHER_P2_OVERLOAD(DefineMatcher, ReturnTypesF, \ ParamType1, Param1, ParamType2, \ Param2, OverloadId) … // FIXME: add a matcher for TypeLoc derived classes using its custom casting // API (no longer dyn_cast) if/when we need such matching #define AST_TYPE_TRAVERSE_MATCHER_DECL(MatcherName, FunctionName, \ ReturnTypesF) … #define AST_TYPE_TRAVERSE_MATCHER_DEF(MatcherName, ReturnTypesF) … /// AST_TYPE_TRAVERSE_MATCHER(MatcherName, FunctionName) defines /// the matcher \c MatcherName that can be used to traverse from one \c Type /// to another. /// /// For a specific \c SpecificType, the traversal is done using /// \c SpecificType::FunctionName. The existence of such a function determines /// whether a corresponding matcher can be used on \c SpecificType. #define AST_TYPE_TRAVERSE_MATCHER(MatcherName, FunctionName, ReturnTypesF) … #define AST_TYPELOC_TRAVERSE_MATCHER_DECL(MatcherName, FunctionName, \ ReturnTypesF) … #define AST_TYPELOC_TRAVERSE_MATCHER_DEF(MatcherName, ReturnTypesF) … /// AST_TYPELOC_TRAVERSE_MATCHER(MatcherName, FunctionName) works /// identical to \c AST_TYPE_TRAVERSE_MATCHER but operates on \c TypeLocs. #define AST_TYPELOC_TRAVERSE_MATCHER(MatcherName, FunctionName, ReturnTypesF) … /// AST_MATCHER_REGEX(Type, DefineMatcher, Param) { ... } /// defines a function named DefineMatcher() that takes a regular expression /// string paramater and an optional RegexFlags parameter and returns a /// Matcher<Type> object. /// /// The code between the curly braces has access to the following variables: /// /// Node: the AST node being matched; its type is Type. /// Param: a pointer to an \ref llvm::Regex object /// Finder: an ASTMatchFinder*. /// Builder: a BoundNodesTreeBuilder*. /// /// The code should return true if 'Node' matches. #define AST_MATCHER_REGEX(Type, DefineMatcher, Param) … #define AST_MATCHER_REGEX_OVERLOAD(Type, DefineMatcher, Param, OverloadId) … /// AST_POLYMORPHIC_MATCHER_REGEX(DefineMatcher, ReturnTypesF, Param) { ... } /// defines a function named DefineMatcher() that takes a regular expression /// string paramater and an optional RegexFlags parameter that is polymorphic in /// the return type. /// /// The variables are the same as for /// AST_MATCHER_REGEX, with the addition of NodeType, which specifies the node /// type of the matcher Matcher<NodeType> returned by the function matcher(). #define AST_POLYMORPHIC_MATCHER_REGEX(DefineMatcher, ReturnTypesF, Param) … #define AST_POLYMORPHIC_MATCHER_REGEX_OVERLOAD(DefineMatcher, ReturnTypesF, \ Param, OverloadId) … #endif // LLVM_CLANG_ASTMATCHERS_ASTMATCHERSMACROS_H
Codebase Browser
llvm