head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RC5:1.1.1.3 netbsd-11-0-RC4:1.1.1.3 netbsd-11-0-RC3:1.1.1.3 netbsd-11-0-RC2:1.1.1.3 netbsd-11-0-RC1:1.1.1.3 perseant-exfatfs-base-20250801:1.1.1.3 netbsd-11:1.1.1.3.0.10 netbsd-11-base:1.1.1.3 netbsd-10-1-RELEASE:1.1.1.3 perseant-exfatfs-base-20240630:1.1.1.3 perseant-exfatfs:1.1.1.3.0.8 perseant-exfatfs-base:1.1.1.3 netbsd-8-3-RELEASE:1.1.1.2 netbsd-9-4-RELEASE:1.1.1.2 netbsd-10-0-RELEASE:1.1.1.3 netbsd-10-0-RC6:1.1.1.3 netbsd-10-0-RC5:1.1.1.3 netbsd-10-0-RC4:1.1.1.3 netbsd-10-0-RC3:1.1.1.3 netbsd-10-0-RC2:1.1.1.3 netbsd-10-0-RC1:1.1.1.3 netbsd-10:1.1.1.3.0.6 netbsd-10-base:1.1.1.3 netbsd-9-3-RELEASE:1.1.1.2 cjep_sun2x:1.1.1.3.0.4 cjep_sun2x-base:1.1.1.3 cjep_staticlib_x-base1:1.1.1.3 netbsd-9-2-RELEASE:1.1.1.2 cjep_staticlib_x:1.1.1.3.0.2 cjep_staticlib_x-base:1.1.1.3 netbsd-9-1-RELEASE:1.1.1.2 phil-wifi-20200421:1.1.1.3 phil-wifi-20200411:1.1.1.3 phil-wifi-20200406:1.1.1.3 netbsd-8-2-RELEASE:1.1.1.2 netbsd-9-0-RELEASE:1.1.1.2 netbsd-9-0-RC2:1.1.1.2 netbsd-9-0-RC1:1.1.1.2 netbsd-9:1.1.1.2.0.16 netbsd-9-base:1.1.1.2 phil-wifi-20190609:1.1.1.2 netbsd-8-1-RELEASE:1.1.1.2 netbsd-8-1-RC1:1.1.1.2 pgoyette-compat-merge-20190127:1.1.1.2 pgoyette-compat-20190127:1.1.1.2 pgoyette-compat-20190118:1.1.1.2 pgoyette-compat-1226:1.1.1.2 pgoyette-compat-1126:1.1.1.2 pgoyette-compat-1020:1.1.1.2 pgoyette-compat-0930:1.1.1.2 pgoyette-compat-0906:1.1.1.2 netbsd-7-2-RELEASE:1.1.1.1 pgoyette-compat-0728:1.1.1.2 clang-337282:1.1.1.2 netbsd-8-0-RELEASE:1.1.1.2 phil-wifi:1.1.1.2.0.14 phil-wifi-base:1.1.1.2 pgoyette-compat-0625:1.1.1.2 netbsd-8-0-RC2:1.1.1.2 pgoyette-compat-0521:1.1.1.2 pgoyette-compat-0502:1.1.1.2 pgoyette-compat-0422:1.1.1.2 netbsd-8-0-RC1:1.1.1.2 pgoyette-compat-0415:1.1.1.2 pgoyette-compat-0407:1.1.1.2 pgoyette-compat-0330:1.1.1.2 pgoyette-compat-0322:1.1.1.2 pgoyette-compat-0315:1.1.1.2 netbsd-7-1-2-RELEASE:1.1.1.1 pgoyette-compat:1.1.1.2.0.12 pgoyette-compat-base:1.1.1.2 netbsd-7-1-1-RELEASE:1.1.1.1 clang-319952:1.1.1.2 matt-nb8-mediatek:1.1.1.2.0.10 matt-nb8-mediatek-base:1.1.1.2 clang-309604:1.1.1.2 perseant-stdc-iso10646:1.1.1.2.0.8 perseant-stdc-iso10646-base:1.1.1.2 netbsd-8:1.1.1.2.0.6 netbsd-8-base:1.1.1.2 prg-localcount2-base3:1.1.1.2 prg-localcount2-base2:1.1.1.2 prg-localcount2-base1:1.1.1.2 prg-localcount2:1.1.1.2.0.4 prg-localcount2-base:1.1.1.2 pgoyette-localcount-20170426:1.1.1.2 bouyer-socketcan-base1:1.1.1.2 pgoyette-localcount-20170320:1.1.1.2 netbsd-7-1:1.1.1.1.0.16 netbsd-7-1-RELEASE:1.1.1.1 netbsd-7-1-RC2:1.1.1.1 clang-294123:1.1.1.2 netbsd-7-nhusb-base-20170116:1.1.1.1 bouyer-socketcan:1.1.1.2.0.2 bouyer-socketcan-base:1.1.1.2 clang-291444:1.1.1.2 pgoyette-localcount-20170107:1.1.1.1 netbsd-7-1-RC1:1.1.1.1 pgoyette-localcount-20161104:1.1.1.1 netbsd-7-0-2-RELEASE:1.1.1.1 localcount-20160914:1.1.1.1 netbsd-7-nhusb:1.1.1.1.0.14 netbsd-7-nhusb-base:1.1.1.1 clang-280599:1.1.1.1 pgoyette-localcount-20160806:1.1.1.1 pgoyette-localcount-20160726:1.1.1.1 pgoyette-localcount:1.1.1.1.0.12 pgoyette-localcount-base:1.1.1.1 netbsd-7-0-1-RELEASE:1.1.1.1 clang-261930:1.1.1.1 netbsd-7-0:1.1.1.1.0.10 netbsd-7-0-RELEASE:1.1.1.1 netbsd-7-0-RC3:1.1.1.1 netbsd-7-0-RC2:1.1.1.1 netbsd-7-0-RC1:1.1.1.1 clang-237755:1.1.1.1 clang-232565:1.1.1.1 clang-227398:1.1.1.1 tls-maxphys-base:1.1.1.1 tls-maxphys:1.1.1.1.0.8 netbsd-7:1.1.1.1.0.6 netbsd-7-base:1.1.1.1 clang-215315:1.1.1.1 clang-209886:1.1.1.1 yamt-pagecache:1.1.1.1.0.4 yamt-pagecache-base9:1.1.1.1 tls-earlyentropy:1.1.1.1.0.2 tls-earlyentropy-base:1.1.1.1 riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.1 riastradh-drm2-base3:1.1.1.1 clang-202566:1.1.1.1 clang-201163:1.1.1.1 clang-199312:1.1.1.1 clang-198450:1.1.1.1 clang-196603:1.1.1.1 clang-195771:1.1.1.1 LLVM:1.1.1; locks; strict; comment @# @; 1.1 date 2013.11.28.14.14.47; author joerg; state Exp; branches 1.1.1.1; next ; commitid ow8OybrawrB1f3fx; 1.1.1.1 date 2013.11.28.14.14.47; author joerg; state Exp; branches 1.1.1.1.4.1 1.1.1.1.8.1 1.1.1.1.12.1; next 1.1.1.2; commitid ow8OybrawrB1f3fx; 1.1.1.2 date 2017.01.11.10.40.28; author joerg; state Exp; branches 1.1.1.2.14.1; next 1.1.1.3; commitid CNnUNfII1jgNmxBz; 1.1.1.3 date 2019.11.13.22.19.10; author joerg; state dead; branches; next ; commitid QD8YATxuNG34YJKB; 1.1.1.1.4.1 date 2013.11.28.14.14.47; author yamt; state dead; branches; next 1.1.1.1.4.2; commitid WSrDtL5nYAUyiyBx; 1.1.1.1.4.2 date 2014.05.22.16.18.19; author yamt; state Exp; branches; next ; commitid WSrDtL5nYAUyiyBx; 1.1.1.1.8.1 date 2013.11.28.14.14.47; author tls; state dead; branches; next 1.1.1.1.8.2; commitid jTnpym9Qu0o4R1Nx; 1.1.1.1.8.2 date 2014.08.19.23.47.19; author tls; state Exp; branches; next ; commitid jTnpym9Qu0o4R1Nx; 1.1.1.1.12.1 date 2017.03.20.06.52.30; author pgoyette; state Exp; branches; next ; commitid jjw7cAwgyKq7RfKz; 1.1.1.2.14.1 date 2020.04.13.07.46.20; author martin; state dead; branches; next ; commitid X01YhRUPVUDaec4C; desc @@ 1.1 log @Initial revision @ text @====================== Matching the Clang AST ====================== This document explains how to use Clang's LibASTMatchers to match interesting nodes of the AST and execute code that uses the matched nodes. Combined with :doc:`LibTooling`, LibASTMatchers helps to write code-to-code transformation tools or query tools. We assume basic knowledge about the Clang AST. See the :doc:`Introduction to the Clang AST ` if you want to learn more about how the AST is structured. .. FIXME: create tutorial and link to the tutorial Introduction ------------ LibASTMatchers provides a domain specific language to create predicates on Clang's AST. This DSL is written in and can be used from C++, allowing users to write a single program to both match AST nodes and access the node's C++ interface to extract attributes, source locations, or any other information provided on the AST level. AST matchers are predicates on nodes in the AST. Matchers are created by calling creator functions that allow building up a tree of matchers, where inner matchers are used to make the match more specific. For example, to create a matcher that matches all class or union declarations in the AST of a translation unit, you can call `recordDecl() `_. To narrow the match down, for example to find all class or union declarations with the name "``Foo``", insert a `hasName `_ matcher: the call ``recordDecl(hasName("Foo"))`` returns a matcher that matches classes or unions that are named "``Foo``", in any namespace. By default, matchers that accept multiple inner matchers use an implicit `allOf() `_. This allows further narrowing down the match, for example to match all classes that are derived from "``Bar``": ``recordDecl(hasName("Foo"), isDerivedFrom("Bar"))``. How to create a matcher ----------------------- With more than a thousand classes in the Clang AST, one can quickly get lost when trying to figure out how to create a matcher for a specific pattern. This section will teach you how to use a rigorous step-by-step pattern to build the matcher you are interested in. Note that there will always be matchers missing for some part of the AST. See the section about :ref:`how to write your own AST matchers ` later in this document. .. FIXME: why is it linking back to the same section?! The precondition to using the matchers is to understand how the AST for what you want to match looks like. The :doc:`Introduction to the Clang AST ` teaches you how to dump a translation unit's AST into a human readable format. .. FIXME: Introduce link to ASTMatchersTutorial.html .. FIXME: Introduce link to ASTMatchersCookbook.html In general, the strategy to create the right matchers is: #. Find the outermost class in Clang's AST you want to match. #. Look at the `AST Matcher Reference `_ for matchers that either match the node you're interested in or narrow down attributes on the node. #. Create your outer match expression. Verify that it works as expected. #. Examine the matchers for what the next inner node you want to match is. #. Repeat until the matcher is finished. .. _astmatchers-bind: Binding nodes in match expressions ---------------------------------- Matcher expressions allow you to specify which parts of the AST are interesting for a certain task. Often you will want to then do something with the nodes that were matched, like building source code transformations. To that end, matchers that match specific AST nodes (so called node matchers) are bindable; for example, ``recordDecl(hasName("MyClass")).bind("id")`` will bind the matched ``recordDecl`` node to the string "``id``", to be later retrieved in the `match callback `_. .. FIXME: Introduce link to ASTMatchersTutorial.html .. FIXME: Introduce link to ASTMatchersCookbook.html Writing your own matchers ------------------------- There are multiple different ways to define a matcher, depending on its type and flexibility. ``VariadicDynCastAllOfMatcher`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Those match all nodes of type *Base* if they can be dynamically casted to *Derived*. The names of those matchers are nouns, which closely resemble *Derived*. ``VariadicDynCastAllOfMatchers`` are the backbone of the matcher hierarchy. Most often, your match expression will start with one of them, and you can :ref:`bind ` the node they represent to ids for later processing. ``VariadicDynCastAllOfMatchers`` are callable classes that model variadic template functions in C++03. They take an aribtrary number of ``Matcher`` and return a ``Matcher``. ``AST_MATCHER_P(Type, Name, ParamType, Param)`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Most matcher definitions use the matcher creation macros. Those define both the matcher of type ``Matcher`` itself, and a matcher-creation function named *Name* that takes a parameter of type *ParamType* and returns the corresponding matcher. There are multiple matcher definition macros that deal with polymorphic return values and different parameter counts. See `ASTMatchersMacros.h `_. .. _astmatchers-writing: Matcher creation functions ^^^^^^^^^^^^^^^^^^^^^^^^^^ Matchers are generated by nesting calls to matcher creation functions. Most of the time those functions are either created by using ``VariadicDynCastAllOfMatcher`` or the matcher creation macros (see below). The free-standing functions are an indication that this matcher is just a combination of other matchers, as is for example the case with `callee `_. .. FIXME: "... macros (see below)" --- there isn't anything below @ 1.1.1.1 log @Import Clang 3.4rc1 r195771. @ text @@ 1.1.1.1.12.1 log @Sync with HEAD @ text @d106 1 a106 1 template functions in C++03. They take an arbitrary number of @ 1.1.1.2 log @Import Clang pre-4.0.0 r291444. @ text @d106 1 a106 1 template functions in C++03. They take an arbitrary number of @ 1.1.1.2.14.1 log @Mostly merge changes from HEAD upto 20200411 @ text @@ 1.1.1.3 log @Mark old LLVM instance as dead. @ text @@ 1.1.1.1.8.1 log @file LibASTMatchers.rst was added on branch tls-maxphys on 2014-08-19 23:47:19 +0000 @ text @d1 134 @ 1.1.1.1.8.2 log @Rebase to HEAD as of a few days ago. @ text @a0 134 ====================== Matching the Clang AST ====================== This document explains how to use Clang's LibASTMatchers to match interesting nodes of the AST and execute code that uses the matched nodes. Combined with :doc:`LibTooling`, LibASTMatchers helps to write code-to-code transformation tools or query tools. We assume basic knowledge about the Clang AST. See the :doc:`Introduction to the Clang AST ` if you want to learn more about how the AST is structured. .. FIXME: create tutorial and link to the tutorial Introduction ------------ LibASTMatchers provides a domain specific language to create predicates on Clang's AST. This DSL is written in and can be used from C++, allowing users to write a single program to both match AST nodes and access the node's C++ interface to extract attributes, source locations, or any other information provided on the AST level. AST matchers are predicates on nodes in the AST. Matchers are created by calling creator functions that allow building up a tree of matchers, where inner matchers are used to make the match more specific. For example, to create a matcher that matches all class or union declarations in the AST of a translation unit, you can call `recordDecl() `_. To narrow the match down, for example to find all class or union declarations with the name "``Foo``", insert a `hasName `_ matcher: the call ``recordDecl(hasName("Foo"))`` returns a matcher that matches classes or unions that are named "``Foo``", in any namespace. By default, matchers that accept multiple inner matchers use an implicit `allOf() `_. This allows further narrowing down the match, for example to match all classes that are derived from "``Bar``": ``recordDecl(hasName("Foo"), isDerivedFrom("Bar"))``. How to create a matcher ----------------------- With more than a thousand classes in the Clang AST, one can quickly get lost when trying to figure out how to create a matcher for a specific pattern. This section will teach you how to use a rigorous step-by-step pattern to build the matcher you are interested in. Note that there will always be matchers missing for some part of the AST. See the section about :ref:`how to write your own AST matchers ` later in this document. .. FIXME: why is it linking back to the same section?! The precondition to using the matchers is to understand how the AST for what you want to match looks like. The :doc:`Introduction to the Clang AST ` teaches you how to dump a translation unit's AST into a human readable format. .. FIXME: Introduce link to ASTMatchersTutorial.html .. FIXME: Introduce link to ASTMatchersCookbook.html In general, the strategy to create the right matchers is: #. Find the outermost class in Clang's AST you want to match. #. Look at the `AST Matcher Reference `_ for matchers that either match the node you're interested in or narrow down attributes on the node. #. Create your outer match expression. Verify that it works as expected. #. Examine the matchers for what the next inner node you want to match is. #. Repeat until the matcher is finished. .. _astmatchers-bind: Binding nodes in match expressions ---------------------------------- Matcher expressions allow you to specify which parts of the AST are interesting for a certain task. Often you will want to then do something with the nodes that were matched, like building source code transformations. To that end, matchers that match specific AST nodes (so called node matchers) are bindable; for example, ``recordDecl(hasName("MyClass")).bind("id")`` will bind the matched ``recordDecl`` node to the string "``id``", to be later retrieved in the `match callback `_. .. FIXME: Introduce link to ASTMatchersTutorial.html .. FIXME: Introduce link to ASTMatchersCookbook.html Writing your own matchers ------------------------- There are multiple different ways to define a matcher, depending on its type and flexibility. ``VariadicDynCastAllOfMatcher`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Those match all nodes of type *Base* if they can be dynamically casted to *Derived*. The names of those matchers are nouns, which closely resemble *Derived*. ``VariadicDynCastAllOfMatchers`` are the backbone of the matcher hierarchy. Most often, your match expression will start with one of them, and you can :ref:`bind ` the node they represent to ids for later processing. ``VariadicDynCastAllOfMatchers`` are callable classes that model variadic template functions in C++03. They take an aribtrary number of ``Matcher`` and return a ``Matcher``. ``AST_MATCHER_P(Type, Name, ParamType, Param)`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Most matcher definitions use the matcher creation macros. Those define both the matcher of type ``Matcher`` itself, and a matcher-creation function named *Name* that takes a parameter of type *ParamType* and returns the corresponding matcher. There are multiple matcher definition macros that deal with polymorphic return values and different parameter counts. See `ASTMatchersMacros.h `_. .. _astmatchers-writing: Matcher creation functions ^^^^^^^^^^^^^^^^^^^^^^^^^^ Matchers are generated by nesting calls to matcher creation functions. Most of the time those functions are either created by using ``VariadicDynCastAllOfMatcher`` or the matcher creation macros (see below). The free-standing functions are an indication that this matcher is just a combination of other matchers, as is for example the case with `callee `_. .. FIXME: "... macros (see below)" --- there isn't anything below @ 1.1.1.1.4.1 log @file LibASTMatchers.rst was added on branch yamt-pagecache on 2014-05-22 16:18:19 +0000 @ text @d1 134 @ 1.1.1.1.4.2 log @sync with head. for a reference, the tree before this commit was tagged as yamt-pagecache-tag8. this commit was splitted into small chunks to avoid a limitation of cvs. ("Protocol error: too many arguments") @ text @a0 134 ====================== Matching the Clang AST ====================== This document explains how to use Clang's LibASTMatchers to match interesting nodes of the AST and execute code that uses the matched nodes. Combined with :doc:`LibTooling`, LibASTMatchers helps to write code-to-code transformation tools or query tools. We assume basic knowledge about the Clang AST. See the :doc:`Introduction to the Clang AST ` if you want to learn more about how the AST is structured. .. FIXME: create tutorial and link to the tutorial Introduction ------------ LibASTMatchers provides a domain specific language to create predicates on Clang's AST. This DSL is written in and can be used from C++, allowing users to write a single program to both match AST nodes and access the node's C++ interface to extract attributes, source locations, or any other information provided on the AST level. AST matchers are predicates on nodes in the AST. Matchers are created by calling creator functions that allow building up a tree of matchers, where inner matchers are used to make the match more specific. For example, to create a matcher that matches all class or union declarations in the AST of a translation unit, you can call `recordDecl() `_. To narrow the match down, for example to find all class or union declarations with the name "``Foo``", insert a `hasName `_ matcher: the call ``recordDecl(hasName("Foo"))`` returns a matcher that matches classes or unions that are named "``Foo``", in any namespace. By default, matchers that accept multiple inner matchers use an implicit `allOf() `_. This allows further narrowing down the match, for example to match all classes that are derived from "``Bar``": ``recordDecl(hasName("Foo"), isDerivedFrom("Bar"))``. How to create a matcher ----------------------- With more than a thousand classes in the Clang AST, one can quickly get lost when trying to figure out how to create a matcher for a specific pattern. This section will teach you how to use a rigorous step-by-step pattern to build the matcher you are interested in. Note that there will always be matchers missing for some part of the AST. See the section about :ref:`how to write your own AST matchers ` later in this document. .. FIXME: why is it linking back to the same section?! The precondition to using the matchers is to understand how the AST for what you want to match looks like. The :doc:`Introduction to the Clang AST ` teaches you how to dump a translation unit's AST into a human readable format. .. FIXME: Introduce link to ASTMatchersTutorial.html .. FIXME: Introduce link to ASTMatchersCookbook.html In general, the strategy to create the right matchers is: #. Find the outermost class in Clang's AST you want to match. #. Look at the `AST Matcher Reference `_ for matchers that either match the node you're interested in or narrow down attributes on the node. #. Create your outer match expression. Verify that it works as expected. #. Examine the matchers for what the next inner node you want to match is. #. Repeat until the matcher is finished. .. _astmatchers-bind: Binding nodes in match expressions ---------------------------------- Matcher expressions allow you to specify which parts of the AST are interesting for a certain task. Often you will want to then do something with the nodes that were matched, like building source code transformations. To that end, matchers that match specific AST nodes (so called node matchers) are bindable; for example, ``recordDecl(hasName("MyClass")).bind("id")`` will bind the matched ``recordDecl`` node to the string "``id``", to be later retrieved in the `match callback `_. .. FIXME: Introduce link to ASTMatchersTutorial.html .. FIXME: Introduce link to ASTMatchersCookbook.html Writing your own matchers ------------------------- There are multiple different ways to define a matcher, depending on its type and flexibility. ``VariadicDynCastAllOfMatcher`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Those match all nodes of type *Base* if they can be dynamically casted to *Derived*. The names of those matchers are nouns, which closely resemble *Derived*. ``VariadicDynCastAllOfMatchers`` are the backbone of the matcher hierarchy. Most often, your match expression will start with one of them, and you can :ref:`bind ` the node they represent to ids for later processing. ``VariadicDynCastAllOfMatchers`` are callable classes that model variadic template functions in C++03. They take an aribtrary number of ``Matcher`` and return a ``Matcher``. ``AST_MATCHER_P(Type, Name, ParamType, Param)`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Most matcher definitions use the matcher creation macros. Those define both the matcher of type ``Matcher`` itself, and a matcher-creation function named *Name* that takes a parameter of type *ParamType* and returns the corresponding matcher. There are multiple matcher definition macros that deal with polymorphic return values and different parameter counts. See `ASTMatchersMacros.h `_. .. _astmatchers-writing: Matcher creation functions ^^^^^^^^^^^^^^^^^^^^^^^^^^ Matchers are generated by nesting calls to matcher creation functions. Most of the time those functions are either created by using ``VariadicDynCastAllOfMatcher`` or the matcher creation macros (see below). The free-standing functions are an indication that this matcher is just a combination of other matchers, as is for example the case with `callee `_. .. FIXME: "... macros (see below)" --- there isn't anything below @