[cfe-commits] r163387 - /cfe/trunk/docs/LibASTMatchers.html

Fri Sep 7 06:13:53 PDT 2012

Author: klimek
Date: Fri Sep  7 08:13:53 2012
New Revision: 163387

URL: http://llvm.org/viewvc/llvm-project?rev=163387&view=rev
Log:
Adds a first iteration of the basic AST matcher documentation landing page.

Added:
    cfe/trunk/docs/LibASTMatchers.html

Added: cfe/trunk/docs/LibASTMatchers.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibASTMatchers.html?rev=163387&view=auto
==============================================================================

--- cfe/trunk/docs/LibASTMatchers.html (added)
+++ cfe/trunk/docs/LibASTMatchers.html Fri Sep  7 08:13:53 2012
@@ -0,0 +1,130 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+          "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>Matching the Clang AST</title>
+<link type="text/css" rel="stylesheet" href="../menu.css" />
+<link type="text/css" rel="stylesheet" href="../content.css" />
+</head>
+<body>
+
+<!--#include virtual="../menu.html.incl"-->
+
+<div id="content">
+
+<h1>Matching the Clang AST</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 href="LibTooling.html">LibTooling</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 href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a> if
+you want to learn more about how the AST is structured.</p>
+
+<!-- FIXME: create tutorial and link to the tutorial -->
+
+<!-- ======================================================================= -->
+<h2 id="intro">Introduction</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 href="LibASTMatchersReference.html#recordDecl0Anchor">recordDecl()</a>.
+To narrow the match down, for example to find all class or union declarations with the name "Foo",
+insert a <a href="LibASTMatchersReference.html#hasName0Anchor">hasName</a>
+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 <a href="LibASTMatchersReference.html#allOf0Anchor">allOf()</a>.
+This allows further narrowing down the match, for example to match all classes
+that are derived from "Bar": recordDecl(hasName("Foo"), isDerivedFrom("Bar")).</p>
+
+<!-- ======================================================================= -->
+<h2 id="writing">How to create a matcher</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 href="#writing">how to write
+your own AST matchers</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 href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a>
+teaches you how to dump a translation unit's AST into a human readable format.</p>
+
+<!-- FIXME: Introduce link to ASTMatchersTutorial.html -->
+<!-- FIXME: Introduce link to ASTMatchersCookbook.html -->
+
+<p>In general, the strategy to create the right matchers is:</p>
+<ol>
+<li>Find the outermost class in Clang's AST you want to match.</li>
+<li>Look at the <a 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>
+
+<!-- ======================================================================= -->
+<h2 id="binding">Binding nodes in match expressions</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, recordDecl(hasName("MyClass")).bind("id") will bind
+the matched recordDecl node to the string "id", to be later retrieved in the
+<a href="http://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html">match callback</a>.</p>
+
+<!-- FIXME: Introduce link to ASTMatchersTutorial.html -->
+<!-- FIXME: Introduce link to ASTMatchersCookbook.html -->
+
+<!-- ======================================================================= -->
+<h2 id="writing">Writing your own matchers</h2>
+<!-- ======================================================================= -->
+
+<p>There are multiple different ways to define a matcher, depending on its
+type and flexibility.</p>
+<ul>
+<li><b>VariadicDynCastAllOfMatcher&ltBase, Derived></b><p>Those match all nodes
+of type <i>Base</i> if they can be dynamically casted to <i>Derived</i>. The
+names of those matchers are nouns, which closely resemble <i>Derived</i>.
+VariadicDynCastAllOfMatchers are the backbone of the matcher hierarchy. Most
+often, your match expression will start with one of them, and you can
+<a href="#binding">bind</a> the node they represent to ids for later processing.</p>
+<p>VariadicDynCastAllOfMatchers are callable classes that model variadic
+template functions in C++03. They take an aribtrary number of Matcher<Derived>
+and return a Matcher<Base>.</p></li>
+<li><b>AST_MATCHER_P(Type, Name, ParamType, Param)</b><p> Most matcher definitions
+use the matcher creation macros. Those define both the matcher of type Matcher<Type>
+itself, and a matcher-creation function named <i>Name</i> that takes a parameter
+of type <i>ParamType</i> 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 href="http://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html">ASTMatchersMacros.h</a>.
+</p></li>
+<li><b>Matcher creation functions</b><p>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
+<a href="LibASTMatchersReference.html#callee1Anchor">callee</a>.</p></li>
+</ul>
+
+</div>
+</body>
+</html>
+



