Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 1 | ====================== |
| 2 | Matching the Clang AST |
| 3 | ====================== |
| 4 | |
| 5 | This document explains how to use Clang's LibASTMatchers to match interesting |
| 6 | nodes of the AST and execute code that uses the matched nodes. Combined with |
| 7 | :doc:`LibTooling`, LibASTMatchers helps to write code-to-code transformation |
| 8 | tools or query tools. |
| 9 | |
Sean Silva | 159cc9e | 2013-01-02 13:07:47 +0000 | [diff] [blame] | 10 | We assume basic knowledge about the Clang AST. See the :doc:`Introduction |
| 11 | to the Clang AST <IntroductionToTheClangAST>` if you want to learn more |
| 12 | about how the AST is structured. |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 13 | |
| 14 | .. FIXME: create tutorial and link to the tutorial |
| 15 | |
| 16 | Introduction |
| 17 | ------------ |
| 18 | |
| 19 | LibASTMatchers provides a domain specific language to create predicates on |
| 20 | Clang's AST. This DSL is written in and can be used from C++, allowing users |
| 21 | to write a single program to both match AST nodes and access the node's C++ |
| 22 | interface to extract attributes, source locations, or any other information |
| 23 | provided on the AST level. |
| 24 | |
| 25 | AST matchers are predicates on nodes in the AST. Matchers are created by |
| 26 | calling creator functions that allow building up a tree of matchers, where |
| 27 | inner matchers are used to make the match more specific. |
| 28 | |
| 29 | For example, to create a matcher that matches all class or union declarations |
| 30 | in the AST of a translation unit, you can call `recordDecl() |
| 31 | <LibASTMatchersReference.html#recordDecl0Anchor>`_. To narrow the match down, |
| 32 | for example to find all class or union declarations with the name "``Foo``", |
| 33 | insert a `hasName <LibASTMatchersReference.html#hasName0Anchor>`_ matcher: the |
| 34 | call ``recordDecl(hasName("Foo"))`` returns a matcher that matches classes or |
| 35 | unions that are named "``Foo``", in any namespace. By default, matchers that |
| 36 | accept multiple inner matchers use an implicit `allOf() |
| 37 | <LibASTMatchersReference.html#allOf0Anchor>`_. This allows further narrowing |
| 38 | down the match, for example to match all classes that are derived from |
| 39 | "``Bar``": ``recordDecl(hasName("Foo"), isDerivedFrom("Bar"))``. |
| 40 | |
| 41 | How to create a matcher |
| 42 | ----------------------- |
| 43 | |
| 44 | With more than a thousand classes in the Clang AST, one can quickly get lost |
| 45 | when trying to figure out how to create a matcher for a specific pattern. This |
| 46 | section will teach you how to use a rigorous step-by-step pattern to build the |
| 47 | matcher you are interested in. Note that there will always be matchers missing |
| 48 | for some part of the AST. See the section about :ref:`how to write your own |
| 49 | AST matchers <astmatchers-writing>` later in this document. |
| 50 | |
| 51 | .. FIXME: why is it linking back to the same section?! |
| 52 | |
| 53 | The precondition to using the matchers is to understand how the AST for what you |
| 54 | want to match looks like. The |
Sean Silva | 159cc9e | 2013-01-02 13:07:47 +0000 | [diff] [blame] | 55 | :doc:`Introduction to the Clang AST <IntroductionToTheClangAST>` teaches you |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 56 | how to dump a translation unit's AST into a human readable format. |
| 57 | |
| 58 | .. FIXME: Introduce link to ASTMatchersTutorial.html |
| 59 | .. FIXME: Introduce link to ASTMatchersCookbook.html |
| 60 | |
| 61 | In general, the strategy to create the right matchers is: |
| 62 | |
| 63 | #. Find the outermost class in Clang's AST you want to match. |
| 64 | #. Look at the `AST Matcher Reference <LibASTMatchersReference.html>`_ for |
| 65 | matchers that either match the node you're interested in or narrow down |
| 66 | attributes on the node. |
| 67 | #. Create your outer match expression. Verify that it works as expected. |
| 68 | #. Examine the matchers for what the next inner node you want to match is. |
| 69 | #. Repeat until the matcher is finished. |
| 70 | |
| 71 | .. _astmatchers-bind: |
| 72 | |
| 73 | Binding nodes in match expressions |
| 74 | ---------------------------------- |
| 75 | |
| 76 | Matcher expressions allow you to specify which parts of the AST are interesting |
| 77 | for a certain task. Often you will want to then do something with the nodes |
| 78 | that were matched, like building source code transformations. |
| 79 | |
| 80 | To that end, matchers that match specific AST nodes (so called node matchers) |
| 81 | are bindable; for example, ``recordDecl(hasName("MyClass")).bind("id")`` will |
| 82 | bind the matched ``recordDecl`` node to the string "``id``", to be later |
| 83 | retrieved in the `match callback |
| 84 | <http://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html>`_. |
| 85 | |
| 86 | .. FIXME: Introduce link to ASTMatchersTutorial.html |
| 87 | .. FIXME: Introduce link to ASTMatchersCookbook.html |
| 88 | |
| 89 | Writing your own matchers |
| 90 | ------------------------- |
| 91 | |
| 92 | There are multiple different ways to define a matcher, depending on its type |
| 93 | and flexibility. |
| 94 | |
| 95 | ``VariadicDynCastAllOfMatcher<Base, Derived>`` |
| 96 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 97 | |
| 98 | Those match all nodes of type *Base* if they can be dynamically casted to |
| 99 | *Derived*. The names of those matchers are nouns, which closely resemble |
| 100 | *Derived*. ``VariadicDynCastAllOfMatchers`` are the backbone of the matcher |
| 101 | hierarchy. Most often, your match expression will start with one of them, and |
| 102 | you can :ref:`bind <astmatchers-bind>` the node they represent to ids for later |
| 103 | processing. |
| 104 | |
| 105 | ``VariadicDynCastAllOfMatchers`` are callable classes that model variadic |
| 106 | template functions in C++03. They take an aribtrary number of |
| 107 | ``Matcher<Derived>`` and return a ``Matcher<Base>``. |
| 108 | |
| 109 | ``AST_MATCHER_P(Type, Name, ParamType, Param)`` |
| 110 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 111 | |
| 112 | Most matcher definitions use the matcher creation macros. Those define both |
| 113 | the matcher of type ``Matcher<Type>`` itself, and a matcher-creation function |
| 114 | named *Name* that takes a parameter of type *ParamType* and returns the |
| 115 | corresponding matcher. |
| 116 | |
| 117 | There are multiple matcher definition macros that deal with polymorphic return |
| 118 | values and different parameter counts. See `ASTMatchersMacros.h |
| 119 | <http://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html>`_. |
| 120 | |
| 121 | .. _astmatchers-writing: |
| 122 | |
| 123 | Matcher creation functions |
| 124 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 125 | |
| 126 | Matchers are generated by nesting calls to matcher creation functions. Most of |
| 127 | the time those functions are either created by using |
| 128 | ``VariadicDynCastAllOfMatcher`` or the matcher creation macros (see below). |
| 129 | The free-standing functions are an indication that this matcher is just a |
| 130 | combination of other matchers, as is for example the case with `callee |
| 131 | <LibASTMatchersReference.html#callee1Anchor>`_. |
| 132 | |
| 133 | .. FIXME: "... macros (see below)" --- there isn't anything below |
| 134 | |