clang.Index source code

1 /**
2 Copyright: Copyright (c) 2011-2016 Jacob Carlborg. All rights reserved.
3 Authors: Jacob Carlborg, Joakim Brännström (joakim.brannstrom dottli gmx.com)
4 Version: 1.1+
5 License: $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost Software License 1.0)
6 
7 History:
8   1.0 initial release. 2011$(BR)
9     Jacob Carlborg
10   1.1+ additional documentation
11     Joakim Brännström
12 */
13 module clang.Index;
14 
15 import clang.c.Index;
16 
17 /** An "index" that consists of a set of translation units that would typically
18  * be linked together into an executable or library.
19  *
20  * Provides a shared context for creating translation units.
21  *
22  * It provides two options:
23  *
24  * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
25  * declarations (when loading any new translation units). A "local" declaration
26  * is one that belongs in the translation unit itself and not in a precompiled
27  * header that was used by the translation unit. If zero, all declarations
28  * will be enumerated.
29  *
30  * Here is an example:
31  *
32  * Example:
33  * ---
34  *   // excludeDeclsFromPCH = 1, displayDiagnostics=1
35  *   Idx = clang_createIndex(1, 1);
36  *
37  *   // IndexTest.pch was produced with the following command:
38  *   // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
39  *   TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
40  *
41  *   // This will load all the symbols from 'IndexTest.pch'
42  *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
43  *                       TranslationUnitVisitor, 0);
44  *   clang_disposeTranslationUnit(TU);
45  *
46  *   // This will load all the symbols from 'IndexTest.c', excluding symbols
47  *   // from 'IndexTest.pch'.
48  *   char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
49  *   TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
50  *                                                  0, 0);
51  *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
52  *                       TranslationUnitVisitor, 0);
53  *   clang_disposeTranslationUnit(TU);
54  * ---
55  *
56  * This process of creating the 'pch', loading it separately, and using it (via
57  * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
58  * (which gives the indexer the same performance benefit as the compiler).
59  */
60 struct Index {
61     import my.gc.refc;
62     import clang.Util;
63 
64     static private struct ContainIndex {
65         mixin CX!("Index");
66         CXTranslationUnit[] tunits;
67 
68         void put(CXTranslationUnit t) @safe pure nothrow {
69             tunits ~= t;
70         }
71 
72         ~this() @trusted {
73             if (cx is null)
74                 return;
75 
76             foreach (a; tunits)
77                 clang_disposeTranslationUnit(a);
78             dispose();
79         }
80     }
81 
82     RefCounted!ContainIndex cx;
83 
84     ref ContainIndex get() @safe {
85         return cx.get;
86     }
87 
88     alias get this;
89 
90     this(bool excludeDeclarationsFromPCH, bool displayDiagnostics) @trusted {
91         cx = ContainIndex(clang_createIndex(excludeDeclarationsFromPCH ? 1 : 0,
92                 displayDiagnostics ? 1 : 0));
93     }
94 }