From cdd5c2397a9c0010e95b9b9f5611b3dde35ecf98 Mon Sep 17 00:00:00 2001 From: Manuel Klimek Date: Wed, 9 Jan 2013 09:38:21 +0000 Subject: [PATCH] Fixes dump_ast_matchers to parse all matcher macros and updates the docs. llvm-svn: 171962 --- clang/docs/LibASTMatchersReference.html | 619 +++++++++++++++++++++++- clang/docs/tools/dump_ast_matchers.py | 41 +- 2 files changed, 653 insertions(+), 7 deletions(-) diff --git a/clang/docs/LibASTMatchersReference.html b/clang/docs/LibASTMatchersReference.html index ec703d3b7b25..163743cdc9db 100644 --- a/clang/docs/LibASTMatchersReference.html +++ b/clang/docs/LibASTMatchersReference.html @@ -229,6 +229,31 @@ Example matches a +Matcher<NestedNameSpecifierLoc>nestedNameSpecifierLocMatcher<NestedNameSpecifierLoc>... +
Same as nestedNameSpecifier but matches NestedNameSpecifierLoc.
+
+ + +Matcher<NestedNameSpecifier>nestedNameSpecifierMatcher<NestedNameSpecifier>... +
Matches nested name specifiers.
+
+Given
+  namespace ns {
+    struct A { static void f(); };
+    void A::f() {}
+    void g() { A::f(); }
+  }
+  ns::A a;
+nestedNameSpecifier()
+  matches "ns::" and both "A::"
+
+ + +Matcher<QualType>qualTypeMatcher<QualType>... +
Matches QualTypes in the clang AST.
+
+ + Matcher<Stmt>arraySubscriptExprMatcher<ArraySubscriptExpr>... 
Matches array subscript expressions.
 
@@ -791,15 +816,363 @@ whileStmt()
+Matcher<TypeLoc>arrayTypeLocMatcher<ArrayTypeLoc>... +
Matches all kinds of arrays.
+
+Given
+  int a[] = { 2, 3 };
+  int b[4];
+  void f() { int c[a[0]]; }
+arrayType()
+  matches "int a[]", "int b[4]" and "int c[a[0]]";
+
+ + +Matcher<TypeLoc>atomicTypeLocMatcher<AtomicTypeLoc>... +
Matches atomic types.
+
+Given
+  _Atomic(int) i;
+atomicType()
+  matches "_Atomic(int) i"
+
+ + +Matcher<TypeLoc>autoTypeLocMatcher<AutoTypeLoc>... +
Matches types nodes representing C++11 auto types.
+
+Given:
+  auto n = 4;
+  int v[] = { 2, 3 }
+  for (auto i : v) { }
+autoType()
+  matches "auto n" and "auto i"
+
+ + +Matcher<TypeLoc>blockPointerTypeLocMatcher<BlockPointerTypeLoc>... +
Matches block pointer types, i.e. types syntactically represented as
+"void (^)(int)".
+
+The pointee is always required to be a FunctionType.
+
+ + +Matcher<TypeLoc>builtinTypeLocMatcher<BuiltinTypeLoc>... +
Matches builtin Types.
+
+Given
+  struct A {};
+  A a;
+  int b;
+  float c;
+  bool d;
+builtinType()
+  matches "int b", "float c" and "bool d"
+
+ + +Matcher<TypeLoc>complexTypeLocMatcher<ComplexTypeLoc>... +
Matches C99 complex types.
+
+Given
+  _Complex float f;
+complexType()
+  matches "_Complex float f"
+
+ + +Matcher<TypeLoc>constantArrayTypeLocMatcher<ConstantArrayTypeLoc>... +
Matches C arrays with a specified constant size.
+
+Given
+  void() {
+    int a[2];
+    int b[] = { 2, 3 };
+    int c[b[0]];
+  }
+constantArrayType()
+  matches "int a[2]"
+
+ + +Matcher<TypeLoc>dependentSizedArrayTypeLocMatcher<DependentSizedArrayTypeLoc>... +
Matches C++ arrays whose size is a value-dependent expression.
+
+Given
+  template<typename T, int Size>
+  class array {
+    T data[Size];
+  };
+dependentSizedArrayType
+  matches "T data[Size]"
+
+ + +Matcher<TypeLoc>functionTypeLocMatcher<FunctionTypeLoc>... +
Matches FunctionType nodes.
+
+Given
+  int (*f)(int);
+  void g();
+functionType()
+  matches "int (*f)(int)" and the type of "g".
+
+ + +Matcher<TypeLoc>incompleteArrayTypeLocMatcher<IncompleteArrayTypeLoc>... +
Matches C arrays with unspecified size.
+
+Given
+  int a[] = { 2, 3 };
+  int b[42];
+  void f(int c[]) { int d[a[0]]; };
+incompleteArrayType()
+  matches "int a[]" and "int c[]"
+
+ + +Matcher<TypeLoc>memberPointerTypeLocMatcher<MemberPointerTypeLoc>... +
Matches member pointer types.
+Given
+  struct A { int i; }
+  A::* ptr = A::i;
+memberPointerType()
+  matches "A::* ptr"
+
+ + +Matcher<TypeLoc>pointerTypeLocMatcher<PointerTypeLoc>... +
Matches pointer types.
+
+Given
+  int *a;
+  int &b = *a;
+  int c = 5;
+pointerType()
+  matches "int *a"
+
+ + +Matcher<TypeLoc>referenceTypeLocMatcher<ReferenceTypeLoc>... +
Matches reference types.
+
+Given
+  int *a;
+  int &b = *a;
+  int c = 5;
+pointerType()
+  matches "int &b"
+
+ + Matcher<TypeLoc>typeLocMatcher<TypeLoc>... 
Matches TypeLocs in the clang AST.
+Matcher<TypeLoc>typedefTypeLocMatcher<TypedefTypeLoc>... +
Matches typedef types.
+
+Given
+  typedef int X;
+typedefType()
+  matches "typedef int X"
+
+ + +Matcher<TypeLoc>variableArrayTypeLocMatcher<VariableArrayTypeLoc>... +
Matches C arrays with a specified size that is not an
+integer-constant-expression.
+
+Given
+  void f() {
+    int a[] = { 2, 3 }
+    int b[42];
+    int c[a[0]];
+variableArrayType()
+  matches "int c[a[0]]"
+
+ + +Matcher<Type>arrayTypeMatcher<ArrayType>... +
Matches all kinds of arrays.
+
+Given
+  int a[] = { 2, 3 };
+  int b[4];
+  void f() { int c[a[0]]; }
+arrayType()
+  matches "int a[]", "int b[4]" and "int c[a[0]]";
+
+ + +Matcher<Type>atomicTypeMatcher<AtomicType>... +
Matches atomic types.
+
+Given
+  _Atomic(int) i;
+atomicType()
+  matches "_Atomic(int) i"
+
+ + +Matcher<Type>autoTypeMatcher<AutoType>... +
Matches types nodes representing C++11 auto types.
+
+Given:
+  auto n = 4;
+  int v[] = { 2, 3 }
+  for (auto i : v) { }
+autoType()
+  matches "auto n" and "auto i"
+
+ + +Matcher<Type>blockPointerTypeMatcher<BlockPointerType>... +
Matches block pointer types, i.e. types syntactically represented as
+"void (^)(int)".
+
+The pointee is always required to be a FunctionType.
+
+ + +Matcher<Type>builtinTypeMatcher<BuiltinType>... +
Matches builtin Types.
+
+Given
+  struct A {};
+  A a;
+  int b;
+  float c;
+  bool d;
+builtinType()
+  matches "int b", "float c" and "bool d"
+
+ + +Matcher<Type>complexTypeMatcher<ComplexType>... +
Matches C99 complex types.
+
+Given
+  _Complex float f;
+complexType()
+  matches "_Complex float f"
+
+ + +Matcher<Type>constantArrayTypeMatcher<ConstantArrayType>... +
Matches C arrays with a specified constant size.
+
+Given
+  void() {
+    int a[2];
+    int b[] = { 2, 3 };
+    int c[b[0]];
+  }
+constantArrayType()
+  matches "int a[2]"
+
+ + +Matcher<Type>dependentSizedArrayTypeMatcher<DependentSizedArrayType>... +
Matches C++ arrays whose size is a value-dependent expression.
+
+Given
+  template<typename T, int Size>
+  class array {
+    T data[Size];
+  };
+dependentSizedArrayType
+  matches "T data[Size]"
+
+ + +Matcher<Type>functionTypeMatcher<FunctionType>... +
Matches FunctionType nodes.
+
+Given
+  int (*f)(int);
+  void g();
+functionType()
+  matches "int (*f)(int)" and the type of "g".
+
+ + +Matcher<Type>incompleteArrayTypeMatcher<IncompleteArrayType>... +
Matches C arrays with unspecified size.
+
+Given
+  int a[] = { 2, 3 };
+  int b[42];
+  void f(int c[]) { int d[a[0]]; };
+incompleteArrayType()
+  matches "int a[]" and "int c[]"
+
+ + +Matcher<Type>memberPointerTypeMatcher<MemberPointerType>... +
Matches member pointer types.
+Given
+  struct A { int i; }
+  A::* ptr = A::i;
+memberPointerType()
+  matches "A::* ptr"
+
+ + +Matcher<Type>pointerTypeMatcher<PointerType>... +
Matches pointer types.
+
+Given
+  int *a;
+  int &b = *a;
+  int c = 5;
+pointerType()
+  matches "int *a"
+
+ + +Matcher<Type>referenceTypeMatcher<ReferenceType>... +
Matches reference types.
+
+Given
+  int *a;
+  int &b = *a;
+  int c = 5;
+pointerType()
+  matches "int &b"
+
+ + Matcher<Type>typeMatcher<Type>... 
Matches Types in the clang AST.
+ +Matcher<Type>typedefTypeMatcher<TypedefType>... +
Matches typedef types.
+
+Given
+  typedef int X;
+typedefType()
+  matches "typedef int X"
+
+ + +Matcher<Type>variableArrayTypeMatcher<VariableArrayType>... +
Matches C arrays with a specified size that is not an
+integer-constant-expression.
+
+Given
+  void f() {
+    int a[] = { 2, 3 }
+    int b[42];
+    int c[a[0]];
+variableArrayType()
+  matches "int c[a[0]]"
+
+ @@ -1145,8 +1518,8 @@ Example matches X (Name is one of "::a::b::X", "a::b::X", "b::X", "X") Matcher<NamedDecl>matchesNamestd::string RegExp -
Matches NamedDecl nodes whose full names partially match the
-given RegExp.
+
Matches NamedDecl nodes whose fully qualified names contain
+a substring matched by the given RegExp.
 
 Supports specifying enclosing namespaces or classes by
 prefixing the name with '<enclosing>::'.  Does not match typedefs
@@ -1423,6 +1796,78 @@ arraySubscriptExpression(hasIndex(integerLiteral()))
 

 
 
+Matcher<ArrayTypeLoc>hasElementTypeLocMatcher<TypeLoc>
+
Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+  struct A {};
+  A a[7];
+  int b[7];
+arrayType(hasElementType(builtinType()))
+  matches "int b[7]"
+
+Usable as: Matcher<ArrayType>, Matcher<ComplexType>
+

+
+
+Matcher<ArrayType>hasElementTypeMatcher<Type>
+
Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+  struct A {};
+  A a[7];
+  int b[7];
+arrayType(hasElementType(builtinType()))
+  matches "int b[7]"
+
+Usable as: Matcher<ArrayType>, Matcher<ComplexType>
+

+
+
+Matcher<AtomicTypeLoc>hasValueTypeLocMatcher<TypeLoc>
+
Matches atomic types with a specific value type.
+
+Given
+  _Atomic(int) i;
+  _Atomic(float) f;
+atomicType(hasValueType(isInteger()))
+ matches "_Atomic(int) i"
+
+Usable as: Matcher<AtomicType>
+

+
+
+Matcher<AtomicType>hasValueTypeMatcher<Type>
+
Matches atomic types with a specific value type.
+
+Given
+  _Atomic(int) i;
+  _Atomic(float) f;
+atomicType(hasValueType(isInteger()))
+ matches "_Atomic(int) i"
+
+Usable as: Matcher<AtomicType>
+

+
+
+Matcher<AutoType>hasDeducedTypeMatcher<Type>
+
Matches AutoType nodes where the deduced type is a specific type.
+
+Note: There is no TypeLoc for the deduced type and thus no
+getDeducedLoc() matcher.
+
+Given
+  auto a = 1;
+  auto b = 2.0;
+autoType(hasDeducedType(isInteger()))
+  matches "auto a"
+
+Usable as: Matcher<AutoType>
+

+
+
 Matcher<BinaryOperator>hasEitherOperandMatcher<Expr>  InnerMatcher
 
Matches if either the left hand side or the right hand side of a
 binary operator matches.
@@ -1445,6 +1890,38 @@ Example matches b (matcher = binaryOperator(hasRHS()))
 

 
 
+Matcher<BlockPointerTypeLoc>pointeeLocMatcher<TypeLoc>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
+Matcher<BlockPointerType>pointeeMatcher<Type>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
 Matcher<CXXConstructExpr>hasDeclarationMatcher<Decl>  InnerMatcher
 
Matches a type if the declaration of the type matches the given
 matcher.
@@ -1643,6 +2120,36 @@ classTemplateSpecializationDecl(hasTemplateArgument(
 

 
 
+Matcher<ComplexTypeLoc>hasElementTypeLocMatcher<TypeLoc>
+
Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+  struct A {};
+  A a[7];
+  int b[7];
+arrayType(hasElementType(builtinType()))
+  matches "int b[7]"
+
+Usable as: Matcher<ArrayType>, Matcher<ComplexType>
+

+
+
+Matcher<ComplexType>hasElementTypeMatcher<Type>
+
Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+  struct A {};
+  A a[7];
+  int b[7];
+arrayType(hasElementType(builtinType()))
+  matches "int b[7]"
+
+Usable as: Matcher<ArrayType>, Matcher<ComplexType>
+

+
+
 Matcher<CompoundStmt>hasAnySubstatementMatcher<Stmt> InnerMatcher
 
Matches compound statements where at least one substatement matches
 a given matcher.
@@ -1996,6 +2503,38 @@ memberExpr(member(hasName("first")))
 

 
 
+Matcher<MemberPointerTypeLoc>pointeeLocMatcher<TypeLoc>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
+Matcher<MemberPointerType>pointeeMatcher<Type>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
 Matcher<NestedNameSpecifierLoc>hasPrefixMatcher<NestedNameSpecifierLoc>  InnerMatcher
 
Matches on the prefix of a NestedNameSpecifierLoc.
 
@@ -2007,6 +2546,12 @@ nestedNameSpecifierLoc(hasPrefix(loc(specifiesType(asString("struct A")))))
 

 
 
+Matcher<NestedNameSpecifierLoc>locMatcher<NestedNameSpecifier>  InnerMatcher
+
Matches NestedNameSpecifierLocs for which the given inner
+NestedNameSpecifier-matcher matches.
+

+
+
 Matcher<NestedNameSpecifierLoc>specifiesTypeLocMatcher<TypeLoc> InnerMatcher
 
Matches nested name specifier locs that specify a type matching the
 given TypeLoc.
@@ -2055,6 +2600,38 @@ nestedNameSpecifier(specifiesType(hasDeclaration(recordDecl(hasName("A")))))
 

 
 
+Matcher<PointerTypeLoc>pointeeLocMatcher<TypeLoc>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
+Matcher<PointerType>pointeeMatcher<Type>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
 Matcher<QualType>hasDeclarationMatcher<Decl>  InnerMatcher
 
Matches a type if the declaration of the type matches the given
 matcher.
@@ -2074,6 +2651,38 @@ Usable as: Matcher<ReferenceTypeLoc>pointeeLocMatcher<TypeLoc>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
+Matcher<ReferenceType>pointeeMatcher<Type>
+
Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+  int *a;
+  int const *b;
+  float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+  matches "int const *b"
+
+Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
+  Matcher<PointerType>, Matcher<ReferenceType>
+

+
+
 Matcher<Stmt>alignOfExprMatcher<UnaryExprOrTypeTraitExpr>  InnerMatcher
 
Same as unaryExprOrTypeTraitExpr, but only matching
 alignof.
@@ -2113,6 +2722,12 @@ classTemplateSpecializationDecl(hasAnyTemplateArgument(
 

 
 
+Matcher<TypeLoc>locMatcher<QualType>  InnerMatcher
+
Matches TypeLocs for which the given inner
+QualType-matcher matches.
+

+
+
 Matcher<TypedefType>hasDeclMatcher<TypedefNameDecl> InnerMatcher
 
Matches TypedefTypes referring to a specific
 TypedefNameDecl.
diff --git a/clang/docs/tools/dump_ast_matchers.py b/clang/docs/tools/dump_ast_matchers.py
index bc5f1a64a5c6..cd7ab0b74f1e 100644
--- a/clang/docs/tools/dump_ast_matchers.py
+++ b/clang/docs/tools/dump_ast_matchers.py
@@ -133,17 +133,48 @@ def act_on_decl(declaration, comment, allowed_types):
   if declaration.strip():
     # Node matchers are defined by writing:
     #   VariadicDynCastAllOfMatcher name;
-    m = re.match(r""".*VariadicDynCastAllOfMatcher\s*<
-                       \s*([^\s,]+)\s*,
-                       \s*([^\s>]+)\s*>
+    m = re.match(r""".*Variadic(?:DynCast)?AllOfMatcher\s*<
+                       \s*([^\s,]+)\s*(?:,
+                       \s*([^\s>]+)\s*)?>
                        \s*([^\s;]+)\s*;\s*$""", declaration, flags=re.X)
     if m:
       result, inner, name = m.groups()
+      if not inner:
+        inner = result
       add_matcher(result, name, 'Matcher<%s>...' % inner,
                   comment, is_dyncast=True)
       return
 
     # Parse the various matcher definition macros.
+    m = re.match(""".*AST_TYPE_MATCHER\(
+                       \s*([^\s,]+\s*),
+                       \s*([^\s,]+\s*)
+                     \)\s*;\s*$""", declaration, flags=re.X)
+    if m:
+      inner, name = m.groups()
+      add_matcher('Type', name, 'Matcher<%s>...' % inner,
+                  comment, is_dyncast=True)
+      add_matcher('TypeLoc', '%sLoc' % name, 'Matcher<%sLoc>...' % inner,
+                  comment, is_dyncast=True)
+      return
+
+    m = re.match(""".*AST_TYPE(LOC)?_TRAVERSE_MATCHER\(
+                       \s*([^\s,]+\s*),
+                       \s*(?:[^\s,]+\s*)
+                     \)\s*;\s*$""", declaration, flags=re.X)
+    if m:
+      loc = m.group(1)
+      name = m.group(2)
+      result_types = extract_result_types(comment)
+      if not result_types:
+        raise Exception('Did not find allowed result types for: %s' % name)
+      for result_type in result_types:
+        add_matcher(result_type, name, 'Matcher', comment)
+        if loc:
+          add_matcher('%sLoc' % result_type, '%sLoc' % name, 'Matcher',
+                      comment)
+      return
+
     m = re.match(r"""^\s*AST_(POLYMORPHIC_)?MATCHER(_P)?(.?)\(
                        (?:\s*([^\s,]+)\s*,)?
                           \s*([^\s,]+)\s*
@@ -178,9 +209,9 @@ def act_on_decl(declaration, comment, allowed_types):
     if m:
       result, name, args = m.groups()
       args = ', '.join(p.strip() for p in args.split(','))
-      m = re.match(r'.*\s+internal::Matcher<([^>]+)>$', result)
+      m = re.match(r'.*\s+internal::(Bindable)?Matcher<([^>]+)>$', result)
       if m:
-        result_types = [m.group(1)]
+        result_types = [m.group(2)]
       else:
         result_types = extract_result_types(comment)
       if not result_types: