/usr/share/doc/clang-3.9-doc/html/LibASTMatchers.html is in clang-3.9-doc 1:3.9.1-9.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Matching the Clang AST — Clang 3.9 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.9',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Clang 3.9 documentation" href="index.html" />
<link rel="next" title="How To Setup Clang Tooling For LLVM" href="HowToSetupToolingForLLVM.html" />
<link rel="prev" title="Tutorial for building tools using LibTooling and LibASTMatchers" href="LibASTMatchersTutorial.html" />
</head>
<body role="document">
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>Clang 3.9 documentation</span></a></h1>
<h2 class="heading"><span>Matching the Clang AST</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>  »
</p>
</div>
<div class="content">
<div class="section" id="matching-the-clang-ast">
<h1>Matching the Clang AST<a class="headerlink" href="#matching-the-clang-ast" title="Permalink to this headline">¶</a></h1>
<p>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
<a class="reference internal" href="LibTooling.html"><span class="doc">LibTooling</span></a>, LibASTMatchers helps to write code-to-code transformation
tools or query tools.</p>
<p>We assume basic knowledge about the Clang AST. See the <a class="reference internal" href="IntroductionToTheClangAST.html"><span class="doc">Introduction
to the Clang AST</span></a> if you want to learn more
about how the AST is structured.</p>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>For example, to create a matcher that matches all class or union declarations
in the AST of a translation unit, you can call <a class="reference external" href="LibASTMatchersReference.html#recordDecl0Anchor">recordDecl()</a>. To narrow the match down,
for example to find all class or union declarations with the name “<code class="docutils literal"><span class="pre">Foo</span></code>”,
insert a <a class="reference external" href="LibASTMatchersReference.html#hasName0Anchor">hasName</a> matcher: the
call <code class="docutils literal"><span class="pre">recordDecl(hasName("Foo"))</span></code> returns a matcher that matches classes or
unions that are named “<code class="docutils literal"><span class="pre">Foo</span></code>”, in any namespace. By default, matchers that
accept multiple inner matchers use an implicit <a class="reference external" href="LibASTMatchersReference.html#allOf0Anchor">allOf()</a>. This allows further narrowing
down the match, for example to match all classes that are derived from
“<code class="docutils literal"><span class="pre">Bar</span></code>”: <code class="docutils literal"><span class="pre">recordDecl(hasName("Foo"),</span> <span class="pre">isDerivedFrom("Bar"))</span></code>.</p>
</div>
<div class="section" id="how-to-create-a-matcher">
<h2>How to create a matcher<a class="headerlink" href="#how-to-create-a-matcher" title="Permalink to this headline">¶</a></h2>
<p>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 <a class="reference internal" href="#astmatchers-writing"><span class="std std-ref">how to write your own
AST matchers</span></a> later in this document.</p>
<p>The precondition to using the matchers is to understand how the AST for what you
want to match looks like. The
<a class="reference internal" href="IntroductionToTheClangAST.html"><span class="doc">Introduction to the Clang AST</span></a> teaches you
how to dump a translation unit’s AST into a human readable format.</p>
<p>In general, the strategy to create the right matchers is:</p>
<ol class="arabic simple">
<li>Find the outermost class in Clang’s AST you want to match.</li>
<li>Look at the <a class="reference external" href="LibASTMatchersReference.html">AST Matcher Reference</a> for
matchers that either match the node you’re interested in or narrow down
attributes on the node.</li>
<li>Create your outer match expression. Verify that it works as expected.</li>
<li>Examine the matchers for what the next inner node you want to match is.</li>
<li>Repeat until the matcher is finished.</li>
</ol>
</div>
<div class="section" id="binding-nodes-in-match-expressions">
<span id="astmatchers-bind"></span><h2>Binding nodes in match expressions<a class="headerlink" href="#binding-nodes-in-match-expressions" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>To that end, matchers that match specific AST nodes (so called node matchers)
are bindable; for example, <code class="docutils literal"><span class="pre">recordDecl(hasName("MyClass")).bind("id")</span></code> will
bind the matched <code class="docutils literal"><span class="pre">recordDecl</span></code> node to the string “<code class="docutils literal"><span class="pre">id</span></code>”, to be later
retrieved in the <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html">match callback</a>.</p>
</div>
<div class="section" id="writing-your-own-matchers">
<h2>Writing your own matchers<a class="headerlink" href="#writing-your-own-matchers" title="Permalink to this headline">¶</a></h2>
<p>There are multiple different ways to define a matcher, depending on its type
and flexibility.</p>
<div class="section" id="variadicdyncastallofmatcher-base-derived">
<h3><code class="docutils literal"><span class="pre">VariadicDynCastAllOfMatcher<Base,</span> <span class="pre">Derived></span></code><a class="headerlink" href="#variadicdyncastallofmatcher-base-derived" title="Permalink to this headline">¶</a></h3>
<p>Those match all nodes of type <em>Base</em> if they can be dynamically casted to
<em>Derived</em>. The names of those matchers are nouns, which closely resemble
<em>Derived</em>. <code class="docutils literal"><span class="pre">VariadicDynCastAllOfMatchers</span></code> are the backbone of the matcher
hierarchy. Most often, your match expression will start with one of them, and
you can <a class="reference internal" href="#astmatchers-bind"><span class="std std-ref">bind</span></a> the node they represent to ids for later
processing.</p>
<p><code class="docutils literal"><span class="pre">VariadicDynCastAllOfMatchers</span></code> are callable classes that model variadic
template functions in C++03. They take an aribtrary number of
<code class="docutils literal"><span class="pre">Matcher<Derived></span></code> and return a <code class="docutils literal"><span class="pre">Matcher<Base></span></code>.</p>
</div>
<div class="section" id="ast-matcher-p-type-name-paramtype-param">
<h3><code class="docutils literal"><span class="pre">AST_MATCHER_P(Type,</span> <span class="pre">Name,</span> <span class="pre">ParamType,</span> <span class="pre">Param)</span></code><a class="headerlink" href="#ast-matcher-p-type-name-paramtype-param" title="Permalink to this headline">¶</a></h3>
<p>Most matcher definitions use the matcher creation macros. Those define both
the matcher of type <code class="docutils literal"><span class="pre">Matcher<Type></span></code> itself, and a matcher-creation function
named <em>Name</em> that takes a parameter of type <em>ParamType</em> and returns the
corresponding matcher.</p>
<p>There are multiple matcher definition macros that deal with polymorphic return
values and different parameter counts. See <a class="reference external" href="http://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html">ASTMatchersMacros.h</a>.</p>
</div>
<div class="section" id="matcher-creation-functions">
<span id="astmatchers-writing"></span><h3>Matcher creation functions<a class="headerlink" href="#matcher-creation-functions" title="Permalink to this headline">¶</a></h3>
<p>Matchers are generated by nesting calls to matcher creation functions. Most of
the time those functions are either created by using
<code class="docutils literal"><span class="pre">VariadicDynCastAllOfMatcher</span></code> 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 <a class="reference external" href="LibASTMatchersReference.html#callee1Anchor">callee</a>.</p>
</div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2007-2017, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9.
</div>
</body>
</html>
|