IntroductionToTheClangAST.rst source code [clang_source_code/docs/IntroductionToTheClangAST.rst]

1	=============================
2	Introduction to the Clang AST
3	=============================
4
5	This document gives a gentle introduction to the mysteries of the Clang
6	AST. It is targeted at developers who either want to contribute to
7	Clang, or use tools that work based on Clang's AST, like the AST
8	matchers.
9
10	.. raw:: html
11
12	<center><iframe width="560" height="315" src="https://www.youtube.com/embed/VqCkCDFLSsc?vq=hd720" frameborder="0" allowfullscreen></iframe></center>
13
14	`Slides <https://llvm.org/devmtg/2013-04/klimek-slides.pdf>`_
15
16	Introduction
17	============
18
19	Clang's AST is different from ASTs produced by some other compilers in
20	that it closely resembles both the written C++ code and the C++
21	standard. For example, parenthesis expressions and compile time
22	constants are available in an unreduced form in the AST. This makes
23	Clang's AST a good fit for refactoring tools.
24
25	Documentation for all Clang AST nodes is available via the generated
26	`Doxygen <https://clang.llvm.org/doxygen>`_. The doxygen online
27	documentation is also indexed by your favorite search engine, which will
28	make a search for clang and the AST node's class name usually turn up
29	the doxygen of the class you're looking for (for example, search for:
30	clang ParenExpr).
31
32	Examining the AST
33	=================
34
35	A good way to familarize yourself with the Clang AST is to actually look
36	at it on some simple example code. Clang has a builtin AST-dump mode,
37	which can be enabled with the flag ``-ast-dump``.
38
39	Let's look at a simple example AST:
40
41	::
42
43	$ cat test.cc
44	int f(int x) {
45	int result = (x / 42);
46	return result;
47	}
48
49	# Clang by default is a frontend for many tools; -Xclang is used to pass
50	# options directly to the C++ frontend.
51	$ clang -Xclang -ast-dump -fsyntax-only test.cc
52	TranslationUnitDecl 0x5aea0d0 <<invalid sloc>>
53	... cutting out internal declarations of clang ...
54	`-FunctionDecl 0x5aeab50 <test.cc:1:1, line:4:1> f 'int (int)'
55	\|-ParmVarDecl 0x5aeaa90 <line:1:7, col:11> x 'int'
56	`-CompoundStmt 0x5aead88 <col:14, line:4:1>
57	\|-DeclStmt 0x5aead10 <line:2:3, col:24>
58	\| `-VarDecl 0x5aeac10 <col:3, col:23> result 'int'
59	\| `-ParenExpr 0x5aeacf0 <col:16, col:23> 'int'
60	\| `-BinaryOperator 0x5aeacc8 <col:17, col:21> 'int' '/'
61	\| \|-ImplicitCastExpr 0x5aeacb0 <col:17> 'int' <LValueToRValue>
62	\| \| `-DeclRefExpr 0x5aeac68 <col:17> 'int' lvalue ParmVar 0x5aeaa90 'x' 'int'
63	\| `-IntegerLiteral 0x5aeac90 <col:21> 'int' 42
64	`-ReturnStmt 0x5aead68 <line:3:3, col:10>
65	`-ImplicitCastExpr 0x5aead50 <col:10> 'int' <LValueToRValue>
66	`-DeclRefExpr 0x5aead28 <col:10> 'int' lvalue Var 0x5aeac10 'result' 'int'
67
68	The toplevel declaration in
69	a translation unit is always the `translation unit
70	declaration <https://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_.
71	In this example, our first user written declaration is the `function
72	declaration <https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html>`_
73	of "``f``". The body of "``f``" is a `compound
74	statement <https://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html>`_,
75	whose child nodes are a `declaration
76	statement <https://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html>`_
77	that declares our result variable, and the `return
78	statement <https://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html>`_.
79
80	AST Context
81	===========
82
83	All information about the AST for a translation unit is bundled up in
84	the class
85	`ASTContext <https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html>`_.
86	It allows traversal of the whole translation unit starting from
87	`getTranslationUnitDecl <https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64>`_,
88	or to access Clang's `table of
89	identifiers <https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4>`_
90	for the parsed translation unit.
91
92	AST Nodes
93	=========
94
95	Clang's AST nodes are modeled on a class hierarchy that does not have a
96	common ancestor. Instead, there are multiple larger hierarchies for
97	basic node types like
98	`Decl <https://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_ and
99	`Stmt <https://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_. Many
100	important AST nodes derive from
101	`Type <https://clang.llvm.org/doxygen/classclang_1_1Type.html>`_,
102	`Decl <https://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_,
103	`DeclContext <https://clang.llvm.org/doxygen/classclang_1_1DeclContext.html>`_
104	or `Stmt <https://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_, with
105	some classes deriving from both Decl and DeclContext.
106
107	There are also a multitude of nodes in the AST that are not part of a
108	larger hierarchy, and are only reachable from specific other nodes, like
109	`CXXBaseSpecifier <https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html>`_.
110
111	Thus, to traverse the full AST, one starts from the
112	`TranslationUnitDecl <https://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_
113	and then recursively traverses everything that can be reached from that
114	node - this information has to be encoded for each specific node type.
115	This algorithm is encoded in the
116	`RecursiveASTVisitor <https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html>`_.
117	See the `RecursiveASTVisitor
118	tutorial <https://clang.llvm.org/docs/RAVFrontendAction.html>`_.
119
120	The two most basic nodes in the Clang AST are statements
121	(`Stmt <https://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_) and
122	declarations
123	(`Decl <https://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_). Note
124	that expressions
125	(`Expr <https://clang.llvm.org/doxygen/classclang_1_1Expr.html>`_) are
126	also statements in Clang's AST.
127

Clang Project