 |
|
 |
|
| Files: |
1 |
|
Branches Taken: |
0.0% |
0 / 0 |
| Generated: |
2010-02-10 01:31 |
|
Branches Executed: |
0.0% |
0 / 0 |
| |
|
Line Coverage: |
100.0% |
5 / 5 |
| |
 |
|
 |
1 : /*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
2 : |* *|
3 : |* The LLVM Compiler Infrastructure *|
4 : |* *|
5 : |* This file is distributed under the University of Illinois Open Source *|
6 : |* License. See LICENSE.TXT for details. *|
7 : |* *|
8 : |*===----------------------------------------------------------------------===*|
9 : |* *|
10 : |* This header provides a public inferface to a Clang library for extracting *|
11 : |* high-level symbol information from source files without exposing the full *|
12 : |* Clang C++ API. *|
13 : |* *|
14 : \*===----------------------------------------------------------------------===*/
15 :
16 : #ifndef CLANG_C_INDEX_H
17 : #define CLANG_C_INDEX_H
18 :
19 : #include <sys/stat.h>
20 : #include <time.h>
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : /* MSVC DLL import/export. */
27 : #ifdef _MSC_VER
28 : #ifdef _CINDEX_LIB_
29 : #define CINDEX_LINKAGE __declspec(dllexport)
30 : #else
31 : #define CINDEX_LINKAGE __declspec(dllimport)
32 : #endif
33 : #else
34 : #define CINDEX_LINKAGE
35 : #endif
36 :
37 : /** \defgroup CINDEX C Interface to Clang
38 : *
39 : * The C Interface to Clang provides a relatively small API that exposes
40 : * facilities for parsing source code into an abstract syntax tree (AST),
41 : * loading already-parsed ASTs, traversing the AST, associating
42 : * physical source locations with elements within the AST, and other
43 : * facilities that support Clang-based development tools.
44 : *
45 : * This C interface to Clang will never provide all of the information
46 : * representation stored in Clang's C++ AST, nor should it: the intent is to
47 : * maintain an API that is relatively stable from one release to the next,
48 : * providing only the basic functionality needed to support development tools.
49 : *
50 : * To avoid namespace pollution, data types are prefixed with "CX" and
51 : * functions are prefixed with "clang_".
52 : *
53 : * @{
54 : */
55 :
56 : /**
57 : * \brief An "index" that consists of a set of translation units that would
58 : * typically be linked together into an executable or library.
59 : */
60 : typedef void *CXIndex;
61 :
62 : /**
63 : * \brief A single translation unit, which resides in an index.
64 : */
65 : typedef void *CXTranslationUnit; /* A translation unit instance. */
66 :
67 : /**
68 : * \brief Opaque pointer representing client data that will be passed through
69 : * to various callbacks and visitors.
70 : */
71 : typedef void *CXClientData;
72 :
73 : /**
74 : * \brief Provides the contents of a file that has not yet been saved to disk.
75 : *
76 : * Each CXUnsavedFile instance provides the name of a file on the
77 : * system along with the current contents of that file that have not
78 : * yet been saved to disk.
79 : */
80 : struct CXUnsavedFile {
81 : /**
82 : * \brief The file whose contents have not yet been saved.
83 : *
84 : * This file must already exist in the file system.
85 : */
86 : const char *Filename;
87 :
88 : /**
89 : * \brief A null-terminated buffer containing the unsaved contents
90 : * of this file.
91 : */
92 : const char *Contents;
93 :
94 : /**
95 : * \brief The length of the unsaved contents of this buffer, not
96 : * counting the NULL at the end of the buffer.
97 : */
98 : unsigned long Length;
99 : };
100 :
101 : /**
102 : * \defgroup CINDEX_STRING String manipulation routines
103 : *
104 : * @{
105 : */
106 :
107 : /**
108 : * \brief A character string.
109 : *
110 : * The \c CXString type is used to return strings from the interface when
111 : * the ownership of that string might different from one call to the next.
112 : * Use \c clang_getCString() to retrieve the string data and, once finished
113 : * with the string data, call \c clang_disposeString() to free the string.
114 : */
115 : typedef struct {
116 : const char *Spelling;
117 : /* A 1 value indicates the clang_ indexing API needed to allocate the string
118 : (and it must be freed by clang_disposeString()). */
119 : int MustFreeString;
120 : } CXString;
121 :
122 : /**
123 : * \brief Retrieve the character data associated with the given string.
124 : */
125 : CINDEX_LINKAGE const char *clang_getCString(CXString string);
126 :
127 : /**
128 : * \brief Free the given string,
129 : */
130 : CINDEX_LINKAGE void clang_disposeString(CXString string);
131 :
132 : /**
133 : * @}
134 : */
135 :
136 : /**
137 : * \brief clang_createIndex() provides a shared context for creating
138 : * translation units. It provides two options:
139 : *
140 : * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
141 : * declarations (when loading any new translation units). A "local" declaration
142 : * is one that belongs in the translation unit itself and not in a precompiled
143 : * header that was used by the translation unit. If zero, all declarations
144 : * will be enumerated.
145 : *
146 : * Here is an example:
147 : *
148 : * // excludeDeclsFromPCH = 1
149 : * Idx = clang_createIndex(1);
150 : *
151 : * // IndexTest.pch was produced with the following command:
152 : * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
153 : * TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
154 : *
155 : * // This will load all the symbols from 'IndexTest.pch'
156 : * clang_visitChildren(clang_getTranslationUnitCursor(TU),
157 : * TranslationUnitVisitor, 0);
158 : * clang_disposeTranslationUnit(TU);
159 : *
160 : * // This will load all the symbols from 'IndexTest.c', excluding symbols
161 : * // from 'IndexTest.pch'.
162 : * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
163 : * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
164 : * 0, 0);
165 : * clang_visitChildren(clang_getTranslationUnitCursor(TU),
166 : * TranslationUnitVisitor, 0);
167 : * clang_disposeTranslationUnit(TU);
168 : *
169 : * This process of creating the 'pch', loading it separately, and using it (via
170 : * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
171 : * (which gives the indexer the same performance benefit as the compiler).
172 : */
173 : CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH);
174 :
175 : /**
176 : * \brief Destroy the given index.
177 : *
178 : * The index must not be destroyed until all of the translation units created
179 : * within that index have been destroyed.
180 : */
181 : CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
182 :
183 : /**
184 : * \brief Request that AST's be generated externally for API calls which parse
185 : * source code on the fly, e.g. \see createTranslationUnitFromSourceFile.
186 : *
187 : * Note: This is for debugging purposes only, and may be removed at a later
188 : * date.
189 : *
190 : * \param index - The index to update.
191 : * \param value - The new flag value.
192 : */
193 : CINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index,
194 : int value);
195 : /**
196 : * \defgroup CINDEX_FILES File manipulation routines
197 : *
198 : * @{
199 : */
200 :
201 : /**
202 : * \brief A particular source file that is part of a translation unit.
203 : */
204 : typedef void *CXFile;
205 :
206 :
207 : /**
208 : * \brief Retrieve the complete file and path name of the given file.
209 : */
210 : CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile);
211 :
212 : /**
213 : * \brief Retrieve the last modification time of the given file.
214 : */
215 : CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
216 :
217 : /**
218 : * \brief Retrieve a file handle within the given translation unit.
219 : *
220 : * \param tu the translation unit
221 : *
222 : * \param file_name the name of the file.
223 : *
224 : * \returns the file handle for the named file in the translation unit \p tu,
225 : * or a NULL file handle if the file was not a part of this translation unit.
226 : */
227 : CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu,
228 : const char *file_name);
229 :
230 : /**
231 : * @}
232 : */
233 :
234 : /**
235 : * \defgroup CINDEX_LOCATIONS Physical source locations
236 : *
237 : * Clang represents physical source locations in its abstract syntax tree in
238 : * great detail, with file, line, and column information for the majority of
239 : * the tokens parsed in the source code. These data types and functions are
240 : * used to represent source location information, either for a particular
241 : * point in the program or for a range of points in the program, and extract
242 : * specific location information from those data types.
243 : *
244 : * @{
245 : */
246 :
247 : /**
248 : * \brief Identifies a specific source location within a translation
249 : * unit.
250 : *
251 : * Use clang_getInstantiationLocation() to map a source location to a
252 : * particular file, line, and column.
253 : */
254 : typedef struct {
255 : void *ptr_data[2];
256 : unsigned int_data;
257 3: } CXSourceLocation;
258 :
259 : /**
260 : * \brief Identifies a range of source locations in the source code.
261 : *
262 : * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
263 : * starting and end locations from a source range, respectively.
264 : */
265 : typedef struct {
266 : void *ptr_data[2];
267 : unsigned begin_int_data;
268 : unsigned end_int_data;
269 : } CXSourceRange;
270 :
271 : /**
272 : * \brief Retrieve a NULL (invalid) source location.
273 : */
274 : CINDEX_LINKAGE CXSourceLocation clang_getNullLocation();
275 :
276 : /**
277 : * \determine Determine whether two source locations, which must refer into
278 : * the same translation unit, refer to exactly the same point in the source
279 : * code.
280 : *
281 : * \returns non-zero if the source locations refer to the same location, zero
282 : * if they refer to different locations.
283 : */
284 : CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1,
285 : CXSourceLocation loc2);
286 :
287 : /**
288 : * \brief Retrieves the source location associated with a given file/line/column
289 : * in a particular translation unit.
290 : */
291 : CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu,
292 : CXFile file,
293 : unsigned line,
294 : unsigned column);
295 :
296 : /**
297 : * \brief Retrieve a NULL (invalid) source range.
298 : */
299 : CINDEX_LINKAGE CXSourceRange clang_getNullRange();
300 :
301 : /**
302 : * \brief Retrieve a source range given the beginning and ending source
303 : * locations.
304 : */
305 : CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin,
306 : CXSourceLocation end);
307 :
308 : /**
309 : * \brief Retrieve the file, line, column, and offset represented by
310 : * the given source location.
311 : *
312 : * \param location the location within a source file that will be decomposed
313 : * into its parts.
314 : *
315 : * \param file [out] if non-NULL, will be set to the file to which the given
316 : * source location points.
317 : *
318 : * \param line [out] if non-NULL, will be set to the line to which the given
319 : * source location points.
320 : *
321 : * \param column [out] if non-NULL, will be set to the column to which the given
322 : * source location points.
323 : *
324 : * \param offset [out] if non-NULL, will be set to the offset into the
325 : * buffer to which the given source location points.
326 : */
327 : CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location,
328 : CXFile *file,
329 : unsigned *line,
330 : unsigned *column,
331 : unsigned *offset);
332 :
333 : /**
334 : * \brief Retrieve a source location representing the first character within a
335 : * source range.
336 : */
337 : CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
338 :
339 : /**
340 : * \brief Retrieve a source location representing the last character within a
341 : * source range.
342 : */
343 : CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
344 :
345 : /**
346 : * @}
347 : */
348 :
349 : /**
350 : * \defgroup CINDEX_DIAG Diagnostic reporting
351 : *
352 : * @{
353 : */
354 :
355 : /**
356 : * \brief Describes the severity of a particular diagnostic.
357 : */
358 : enum CXDiagnosticSeverity {
359 : /**
360 : * \brief A diagnostic that has been suppressed, e.g., by a command-line
361 : * option.
362 : */
363 : CXDiagnostic_Ignored = 0,
364 :
365 : /**
366 : * \brief This diagnostic is a note that should be attached to the
367 : * previous (non-note) diagnostic.
368 : */
369 : CXDiagnostic_Note = 1,
370 :
371 : /**
372 : * \brief This diagnostic indicates suspicious code that may not be
373 : * wrong.
374 : */
375 : CXDiagnostic_Warning = 2,
376 :
377 : /**
378 : * \brief This diagnostic indicates that the code is ill-formed.
379 : */
380 : CXDiagnostic_Error = 3,
381 :
382 : /**
383 : * \brief This diagnostic indicates that the code is ill-formed such
384 : * that future parser recovery is unlikely to produce useful
385 : * results.
386 : */
387 : CXDiagnostic_Fatal = 4
388 : };
389 :
390 : /**
391 : * \brief Describes the kind of fix-it hint expressed within a
392 : * diagnostic.
393 : */
394 : enum CXFixItKind {
395 : /**
396 : * \brief A fix-it hint that inserts code at a particular position.
397 : */
398 : CXFixIt_Insertion = 0,
399 :
400 : /**
401 : * \brief A fix-it hint that removes code within a range.
402 : */
403 : CXFixIt_Removal = 1,
404 :
405 : /**
406 : * \brief A fix-it hint that replaces the code within a range with another
407 : * string.
408 : */
409 : CXFixIt_Replacement = 2
410 : };
411 :
412 : /**
413 : * \brief A single diagnostic, containing the diagnostic's severity,
414 : * location, text, source ranges, and fix-it hints.
415 : */
416 : typedef void *CXDiagnostic;
417 :
418 : /**
419 : * \brief Callback function invoked for each diagnostic emitted during
420 : * translation.
421 : *
422 : * \param Diagnostic the diagnostic emitted during translation. This
423 : * diagnostic pointer is only valid during the execution of the
424 : * callback.
425 : *
426 : * \param ClientData the callback client data.
427 : */
428 : typedef void (*CXDiagnosticCallback)(CXDiagnostic Diagnostic,
429 : CXClientData ClientData);
430 :
431 : /**
432 : * \brief Determine the severity of the given diagnostic.
433 : */
434 : CINDEX_LINKAGE enum CXDiagnosticSeverity
435 : clang_getDiagnosticSeverity(CXDiagnostic);
436 :
437 : /**
438 : * \brief Retrieve the source location of the given diagnostic.
439 : *
440 : * This location is where Clang would print the caret ('^') when
441 : * displaying the diagnostic on the command line.
442 : */
443 : CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);
444 :
445 : /**
446 : * \brief Retrieve the text of the given diagnostic.
447 : */
448 : CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);
449 :
450 : /**
451 : * \brief Determine the number of source ranges associated with the given
452 : * diagnostic.
453 : */
454 : CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
455 :
456 : /**
457 : * \brief Retrieve a source range associated with the diagnostic.
458 : *
459 : * A diagnostic's source ranges highlight important elements in the source
460 : * code. On the command line, Clang displays source ranges by
461 : * underlining them with '~' characters.
462 : *
463 : * \param Diagnostic the diagnostic whose range is being extracted.
464 : *
465 : * \param Range the zero-based index specifying which range to
466 : *
467 : * \returns the requested source range.
468 : */
469 : CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,
470 : unsigned Range);
471 :
472 : /**
473 : * \brief Determine the number of fix-it hints associated with the
474 : * given diagnostic.
475 : */
476 : CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
477 :
478 : /**
479 : * \brief Retrieve the kind of the given fix-it.
480 : *
481 : * \param Diagnostic the diagnostic whose fix-its are being queried.
482 : *
483 : * \param FixIt the zero-based index of the fix-it to query.
484 : */
485 : CINDEX_LINKAGE enum CXFixItKind
486 : clang_getDiagnosticFixItKind(CXDiagnostic Diagnostic, unsigned FixIt);
487 :
488 : /**
489 : * \brief Retrieve the insertion information for an insertion fix-it.
490 : *
491 : * For a fix-it that describes an insertion into a text buffer,
492 : * retrieve the source location where the text should be inserted and
493 : * the text to be inserted.
494 : *
495 : * \param Diagnostic the diagnostic whose fix-its are being queried.
496 : *
497 : * \param FixIt the zero-based index of the insertion fix-it.
498 : *
499 : * \param Location will be set to the location where text should be
500 : * inserted.
501 : *
502 : * \returns the text string to insert at the given location.
503 : */
504 : CINDEX_LINKAGE CXString
505 : clang_getDiagnosticFixItInsertion(CXDiagnostic Diagnostic, unsigned FixIt,
506 : CXSourceLocation *Location);
507 :
508 : /**
509 : * \brief Retrieve the removal information for a removal fix-it.
510 : *
511 : * For a fix-it that describes a removal from a text buffer, retrieve
512 : * the source range that should be removed.
513 : *
514 : * \param Diagnostic the diagnostic whose fix-its are being queried.
515 : *
516 : * \param FixIt the zero-based index of the removal fix-it.
517 : *
518 : * \returns a source range describing the text that should be removed
519 : * from the buffer.
520 : */
521 : CINDEX_LINKAGE CXSourceRange
522 : clang_getDiagnosticFixItRemoval(CXDiagnostic Diagnostic, unsigned FixIt);
523 :
524 : /**
525 : * \brief Retrieve the replacement information for an replacement fix-it.
526 : *
527 : * For a fix-it that describes replacement of text in the text buffer
528 : * with alternative text.
529 : *
530 : * \param Diagnostic the diagnostic whose fix-its are being queried.
531 : *
532 : * \param FixIt the zero-based index of the replacement fix-it.
533 : *
534 : * \param Range will be set to the source range whose text should be
535 : * replaced with the returned text.
536 : *
537 : * \returns the text string to use as replacement text.
538 : */
539 : CINDEX_LINKAGE CXString
540 : clang_getDiagnosticFixItReplacement(CXDiagnostic Diagnostic, unsigned FixIt,
541 : CXSourceRange *Range);
542 :
543 : /**
544 : * @}
545 : */
546 :
547 : /**
548 : * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
549 : *
550 : * The routines in this group provide the ability to create and destroy
551 : * translation units from files, either by parsing the contents of the files or
552 : * by reading in a serialized representation of a translation unit.
553 : *
554 : * @{
555 : */
556 :
557 : /**
558 : * \brief Get the original translation unit source file name.
559 : */
560 : CINDEX_LINKAGE CXString
561 : clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
562 :
563 : /**
564 : * \brief Return the CXTranslationUnit for a given source file and the provided
565 : * command line arguments one would pass to the compiler.
566 : *
567 : * Note: The 'source_filename' argument is optional. If the caller provides a
568 : * NULL pointer, the name of the source file is expected to reside in the
569 : * specified command line arguments.
570 : *
571 : * Note: When encountered in 'clang_command_line_args', the following options
572 : * are ignored:
573 : *
574 : * '-c'
575 : * '-emit-ast'
576 : * '-fsyntax-only'
577 : * '-o <output file>' (both '-o' and '<output file>' are ignored)
578 : *
579 : *
580 : * \param source_filename - The name of the source file to load, or NULL if the
581 : * source file is included in clang_command_line_args.
582 : *
583 : * \param num_unsaved_files the number of unsaved file entries in \p
584 : * unsaved_files.
585 : *
586 : * \param unsaved_files the files that have not yet been saved to disk
587 : * but may be required for code completion, including the contents of
588 : * those files.
589 : *
590 : * \param diag_callback callback function that will receive any diagnostics
591 : * emitted while processing this source file. If NULL, diagnostics will be
592 : * suppressed.
593 : *
594 : * \param diag_client_data client data that will be passed to the diagnostic
595 : * callback function.
596 : */
597 : CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
598 : CXIndex CIdx,
599 : const char *source_filename,
600 : int num_clang_command_line_args,
601 : const char **clang_command_line_args,
602 : unsigned num_unsaved_files,
603 : struct CXUnsavedFile *unsaved_files,
604 : CXDiagnosticCallback diag_callback,
605 : CXClientData diag_client_data);
606 :
607 : /**
608 : * \brief Create a translation unit from an AST file (-emit-ast).
609 : */
610 : CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex,
611 : const char *ast_filename,
612 : CXDiagnosticCallback diag_callback,
613 : CXClientData diag_client_data);
614 :
615 : /**
616 : * \brief Destroy the specified CXTranslationUnit object.
617 : */
618 : CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
619 :
620 : /**
621 : * @}
622 : */
623 :
624 : /**
625 : * \brief Describes the kind of entity that a cursor refers to.
626 : */
627 : enum CXCursorKind {
628 : /* Declarations */
629 : CXCursor_FirstDecl = 1,
630 : /**
631 : * \brief A declaration whose specific kind is not exposed via this
632 : * interface.
633 : *
634 : * Unexposed declarations have the same operations as any other kind
635 : * of declaration; one can extract their location information,
636 : * spelling, find their definitions, etc. However, the specific kind
637 : * of the declaration is not reported.
638 : */
639 : CXCursor_UnexposedDecl = 1,
640 : /** \brief A C or C++ struct. */
641 : CXCursor_StructDecl = 2,
642 : /** \brief A C or C++ union. */
643 : CXCursor_UnionDecl = 3,
644 : /** \brief A C++ class. */
645 : CXCursor_ClassDecl = 4,
646 : /** \brief An enumeration. */
647 : CXCursor_EnumDecl = 5,
648 : /**
649 : * \brief A field (in C) or non-static data member (in C++) in a
650 : * struct, union, or C++ class.
651 : */
652 : CXCursor_FieldDecl = 6,
653 : /** \brief An enumerator constant. */
654 : CXCursor_EnumConstantDecl = 7,
655 : /** \brief A function. */
656 : CXCursor_FunctionDecl = 8,
657 : /** \brief A variable. */
658 : CXCursor_VarDecl = 9,
659 : /** \brief A function or method parameter. */
660 : CXCursor_ParmDecl = 10,
661 : /** \brief An Objective-C @interface. */
662 : CXCursor_ObjCInterfaceDecl = 11,
663 : /** \brief An Objective-C @interface for a category. */
664 : CXCursor_ObjCCategoryDecl = 12,
665 : /** \brief An Objective-C @protocol declaration. */
666 : CXCursor_ObjCProtocolDecl = 13,
667 : /** \brief An Objective-C @property declaration. */
668 : CXCursor_ObjCPropertyDecl = 14,
669 : /** \brief An Objective-C instance variable. */
670 : CXCursor_ObjCIvarDecl = 15,
671 : /** \brief An Objective-C instance method. */
672 : CXCursor_ObjCInstanceMethodDecl = 16,
673 : /** \brief An Objective-C class method. */
674 : CXCursor_ObjCClassMethodDecl = 17,
675 : /** \brief An Objective-C @implementation. */
676 : CXCursor_ObjCImplementationDecl = 18,
677 : /** \brief An Objective-C @implementation for a category. */
678 : CXCursor_ObjCCategoryImplDecl = 19,
679 : /** \brief A typedef */
680 : CXCursor_TypedefDecl = 20,
681 : CXCursor_LastDecl = 20,
682 :
683 : /* References */
684 : CXCursor_FirstRef = 40, /* Decl references */
685 : CXCursor_ObjCSuperClassRef = 40,
686 : CXCursor_ObjCProtocolRef = 41,
687 : CXCursor_ObjCClassRef = 42,
688 : /**
689 : * \brief A reference to a type declaration.
690 : *
691 : * A type reference occurs anywhere where a type is named but not
692 : * declared. For example, given:
693 : *
694 : * \code
695 : * typedef unsigned size_type;
696 : * size_type size;
697 : * \endcode
698 : *
699 : * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
700 : * while the type of the variable "size" is referenced. The cursor
701 : * referenced by the type of size is the typedef for size_type.
702 : */
703 : CXCursor_TypeRef = 43,
704 : CXCursor_LastRef = 43,
705 :
706 : /* Error conditions */
707 : CXCursor_FirstInvalid = 70,
708 : CXCursor_InvalidFile = 70,
709 : CXCursor_NoDeclFound = 71,
710 : CXCursor_NotImplemented = 72,
711 : CXCursor_LastInvalid = 72,
712 :
713 : /* Expressions */
714 : CXCursor_FirstExpr = 100,
715 :
716 : /**
717 : * \brief An expression whose specific kind is not exposed via this
718 : * interface.
719 : *
720 : * Unexposed expressions have the same operations as any other kind
721 : * of expression; one can extract their location information,
722 : * spelling, children, etc. However, the specific kind of the
723 : * expression is not reported.
724 : */
725 : CXCursor_UnexposedExpr = 100,
726 :
727 : /**
728 : * \brief An expression that refers to some value declaration, such
729 : * as a function, varible, or enumerator.
730 : */
731 : CXCursor_DeclRefExpr = 101,
732 :
733 : /**
734 : * \brief An expression that refers to a member of a struct, union,
735 : * class, Objective-C class, etc.
736 : */
737 : CXCursor_MemberRefExpr = 102,
738 :
739 : /** \brief An expression that calls a function. */
740 : CXCursor_CallExpr = 103,
741 :
742 : /** \brief An expression that sends a message to an Objective-C
743 : object or class. */
744 : CXCursor_ObjCMessageExpr = 104,
745 : CXCursor_LastExpr = 104,
746 :
747 : /* Statements */
748 : CXCursor_FirstStmt = 200,
749 : /**
750 : * \brief A statement whose specific kind is not exposed via this
751 : * interface.
752 : *
753 : * Unexposed statements have the same operations as any other kind of
754 : * statement; one can extract their location information, spelling,
755 : * children, etc. However, the specific kind of the statement is not
756 : * reported.
757 : */
758 : CXCursor_UnexposedStmt = 200,
759 : CXCursor_LastStmt = 200,
760 :
761 : /**
762 : * \brief Cursor that represents the translation unit itself.
763 : *
764 : * The translation unit cursor exists primarily to act as the root
765 : * cursor for traversing the contents of a translation unit.
766 : */
767 : CXCursor_TranslationUnit = 300
768 : };
769 :
770 : /**
771 : * \brief A cursor representing some element in the abstract syntax tree for
772 : * a translation unit.
773 : *
774 : * The cursor abstraction unifies the different kinds of entities in a
775 : * program--declaration, statements, expressions, references to declarations,
776 : * etc.--under a single "cursor" abstraction with a common set of operations.
777 : * Common operation for a cursor include: getting the physical location in
778 : * a source file where the cursor points, getting the name associated with a
779 : * cursor, and retrieving cursors for any child nodes of a particular cursor.
780 : *
781 : * Cursors can be produced in two specific ways.
782 : * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
783 : * from which one can use clang_visitChildren() to explore the rest of the
784 : * translation unit. clang_getCursor() maps from a physical source location
785 : * to the entity that resides at that location, allowing one to map from the
786 : * source code into the AST.
787 : */
788 : typedef struct {
789 : enum CXCursorKind kind;
790 : void *data[3];
791 13: } CXCursor;
792 :
793 : /**
794 : * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
795 : *
796 : * @{
797 : */
798 :
799 : /**
800 : * \brief Retrieve the NULL cursor, which represents no entity.
801 : */
802 : CINDEX_LINKAGE CXCursor clang_getNullCursor(void);
803 :
804 : /**
805 : * \brief Retrieve the cursor that represents the given translation unit.
806 : *
807 : * The translation unit cursor can be used to start traversing the
808 : * various declarations within the given translation unit.
809 : */
810 : CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit);
811 :
812 : /**
813 : * \brief Determine whether two cursors are equivalent.
814 : */
815 : CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor);
816 :
817 : /**
818 : * \brief Retrieve the kind of the given cursor.
819 : */
820 : CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
821 :
822 : /**
823 : * \brief Determine whether the given cursor kind represents a declaration.
824 : */
825 : CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
826 :
827 : /**
828 : * \brief Determine whether the given cursor kind represents a simple
829 : * reference.
830 : *
831 : * Note that other kinds of cursors (such as expressions) can also refer to
832 : * other cursors. Use clang_getCursorReferenced() to determine whether a
833 : * particular cursor refers to another entity.
834 : */
835 : CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
836 :
837 : /**
838 : * \brief Determine whether the given cursor kind represents an expression.
839 : */
840 : CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind);
841 :
842 : /**
843 : * \brief Determine whether the given cursor kind represents a statement.
844 : */
845 : CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind);
846 :
847 : /**
848 : * \brief Determine whether the given cursor kind represents an invalid
849 : * cursor.
850 : */
851 : CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
852 :
853 : /**
854 : * \brief Determine whether the given cursor kind represents a translation
855 : * unit.
856 : */
857 : CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind);
858 :
859 : /**
860 : * @}
861 : */
862 :
863 : /**
864 : * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
865 : *
866 : * Cursors represent a location within the Abstract Syntax Tree (AST). These
867 : * routines help map between cursors and the physical locations where the
868 : * described entities occur in the source code. The mapping is provided in
869 : * both directions, so one can map from source code to the AST and back.
870 : *
871 : * @{
872 : */
873 :
874 : /**
875 : * \brief Map a source location to the cursor that describes the entity at that
876 : * location in the source code.
877 : *
878 : * clang_getCursor() maps an arbitrary source location within a translation
879 : * unit down to the most specific cursor that describes the entity at that
880 : * location. For example, given an expression \c x + y, invoking
881 : * clang_getCursor() with a source location pointing to "x" will return the
882 : * cursor for "x"; similarly for "y". If the cursor points anywhere between
883 : * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
884 : * will return a cursor referring to the "+" expression.
885 : *
886 : * \returns a cursor representing the entity at the given source location, or
887 : * a NULL cursor if no such entity can be found.
888 : */
889 : CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation);
890 :
891 : /**
892 : * \brief Retrieve the physical location of the source constructor referenced
893 : * by the given cursor.
894 : *
895 : * The location of a declaration is typically the location of the name of that
896 : * declaration, where the name of that declaration would occur if it is
897 : * unnamed, or some keyword that introduces that particular declaration.
898 : * The location of a reference is where that reference occurs within the
899 : * source code.
900 : */
901 : CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor);
902 :
903 : /**
904 : * \brief Retrieve the physical extent of the source construct referenced by
905 : * the given cursor.
906 : *
907 : * The extent of a cursor starts with the file/line/column pointing at the
908 : * first character within the source construct that the cursor refers to and
909 : * ends with the last character withinin that source construct. For a
910 : * declaration, the extent covers the declaration itself. For a reference,
911 : * the extent covers the location of the reference (e.g., where the referenced
912 : * entity was actually used).
913 : */
914 : CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor);
915 :
916 : /**
917 : * @}
918 : */
919 :
920 : /**
921 : * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
922 : *
923 : * These routines provide the ability to traverse the abstract syntax tree
924 : * using cursors.
925 : *
926 : * @{
927 : */
928 :
929 : /**
930 : * \brief Describes how the traversal of the children of a particular
931 : * cursor should proceed after visiting a particular child cursor.
932 : *
933 : * A value of this enumeration type should be returned by each
934 : * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
935 : */
936 : enum CXChildVisitResult {
937 : /**
938 : * \brief Terminates the cursor traversal.
939 : */
940 : CXChildVisit_Break,
941 : /**
942 : * \brief Continues the cursor traversal with the next sibling of
943 : * the cursor just visited, without visiting its children.
944 : */
945 : CXChildVisit_Continue,
946 : /**
947 : * \brief Recursively traverse the children of this cursor, using
948 : * the same visitor and client data.
949 : */
950 : CXChildVisit_Recurse
951 : };
952 :
953 : /**
954 : * \brief Visitor invoked for each cursor found by a traversal.
955 : *
956 : * This visitor function will be invoked for each cursor found by
957 : * clang_visitCursorChildren(). Its first argument is the cursor being
958 : * visited, its second argument is the parent visitor for that cursor,
959 : * and its third argument is the client data provided to
960 : * clang_visitCursorChildren().
961 : *
962 : * The visitor should return one of the \c CXChildVisitResult values
963 : * to direct clang_visitCursorChildren().
964 : */
965 : typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor,
966 : CXCursor parent,
967 : CXClientData client_data);
968 :
969 : /**
970 : * \brief Visit the children of a particular cursor.
971 : *
972 : * This function visits all the direct children of the given cursor,
973 : * invoking the given \p visitor function with the cursors of each
974 : * visited child. The traversal may be recursive, if the visitor returns
975 : * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
976 : * the visitor returns \c CXChildVisit_Break.
977 : *
978 : * \param parent the cursor whose child may be visited. All kinds of
979 : * cursors can be visited, including invalid cursors (which, by
980 : * definition, have no children).
981 : *
982 : * \param visitor the visitor function that will be invoked for each
983 : * child of \p parent.
984 : *
985 : * \param client_data pointer data supplied by the client, which will
986 : * be passed to the visitor each time it is invoked.
987 : *
988 : * \returns a non-zero value if the traversal was terminated
989 : * prematurely by the visitor returning \c CXChildVisit_Break.
990 : */
991 : CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent,
992 : CXCursorVisitor visitor,
993 : CXClientData client_data);
994 :
995 : /**
996 : * @}
997 : */
998 :
999 : /**
1000 : * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
1001 : *
1002 : * These routines provide the ability to determine references within and
1003 : * across translation units, by providing the names of the entities referenced
1004 : * by cursors, follow reference cursors to the declarations they reference,
1005 : * and associate declarations with their definitions.
1006 : *
1007 : * @{
1008 : */
1009 :
1010 : /**
1011 : * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced
1012 : * by the given cursor.
1013 : *
1014 : * A Unified Symbol Resolution (USR) is a string that identifies a particular
1015 : * entity (function, class, variable, etc.) within a program. USRs can be
1016 : * compared across translation units to determine, e.g., when references in
1017 : * one translation refer to an entity defined in another translation unit.
1018 : */
1019 : CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor);
1020 :
1021 : /**
1022 : * \brief Retrieve a name for the entity referenced by this cursor.
1023 : */
1024 : CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
1025 :
1026 : /** \brief For a cursor that is a reference, retrieve a cursor representing the
1027 : * entity that it references.
1028 : *
1029 : * Reference cursors refer to other entities in the AST. For example, an
1030 : * Objective-C superclass reference cursor refers to an Objective-C class.
1031 : * This function produces the cursor for the Objective-C class from the
1032 : * cursor for the superclass reference. If the input cursor is a declaration or
1033 : * definition, it returns that declaration or definition unchanged.
1034 : * Otherwise, returns the NULL cursor.
1035 : */
1036 : CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor);
1037 :
1038 : /**
1039 : * \brief For a cursor that is either a reference to or a declaration
1040 : * of some entity, retrieve a cursor that describes the definition of
1041 : * that entity.
1042 : *
1043 : * Some entities can be declared multiple times within a translation
1044 : * unit, but only one of those declarations can also be a
1045 : * definition. For example, given:
1046 : *
1047 : * \code
1048 : * int f(int, int);
1049 : * int g(int x, int y) { return f(x, y); }
1050 : * int f(int a, int b) { return a + b; }
1051 : * int f(int, int);
1052 : * \endcode
1053 : *
1054 : * there are three declarations of the function "f", but only the
1055 : * second one is a definition. The clang_getCursorDefinition()
1056 : * function will take any cursor pointing to a declaration of "f"
1057 : * (the first or fourth lines of the example) or a cursor referenced
1058 : * that uses "f" (the call to "f' inside "g") and will return a
1059 : * declaration cursor pointing to the definition (the second "f"
1060 : * declaration).
1061 : *
1062 : * If given a cursor for which there is no corresponding definition,
1063 : * e.g., because there is no definition of that entity within this
1064 : * translation unit, returns a NULL cursor.
1065 : */
1066 : CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor);
1067 :
1068 : /**
1069 : * \brief Determine whether the declaration pointed to by this cursor
1070 : * is also a definition of that entity.
1071 : */
1072 : CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor);
1073 :
1074 : /**
1075 : * @}
1076 : */
1077 :
1078 : /**
1079 : * \defgroup CINDEX_LEX Token extraction and manipulation
1080 : *
1081 : * The routines in this group provide access to the tokens within a
1082 : * translation unit, along with a semantic mapping of those tokens to
1083 : * their corresponding cursors.
1084 : *
1085 : * @{
1086 : */
1087 :
1088 : /**
1089 : * \brief Describes a kind of token.
1090 : */
1091 : typedef enum CXTokenKind {
1092 : /**
1093 : * \brief A token that contains some kind of punctuation.
1094 : */
1095 : CXToken_Punctuation,
1096 :
1097 : /**
1098 : * \brief A language keyword.
1099 : */
1100 : CXToken_Keyword,
1101 :
1102 : /**
1103 : * \brief An identifier (that is not a keyword).
1104 : */
1105 : CXToken_Identifier,
1106 :
1107 : /**
1108 : * \brief A numeric, string, or character literal.
1109 : */
1110 : CXToken_Literal,
1111 :
1112 : /**
1113 : * \brief A comment.
1114 : */
1115 : CXToken_Comment
1116 : } CXTokenKind;
1117 :
1118 : /**
1119 : * \brief Describes a single preprocessing token.
1120 : */
1121 : typedef struct {
1122 : unsigned int_data[4];
1123 : void *ptr_data;
1124 83: } CXToken;
1125 :
1126 : /**
1127 : * \brief Determine the kind of the given token.
1128 : */
1129 : CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken);
1130 :
1131 : /**
1132 : * \brief Determine the spelling of the given token.
1133 : *
1134 : * The spelling of a token is the textual representation of that token, e.g.,
1135 : * the text of an identifier or keyword.
1136 : */
1137 : CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken);
1138 :
1139 : /**
1140 : * \brief Retrieve the source location of the given token.
1141 : */
1142 : CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit,
1143 : CXToken);
1144 :
1145 : /**
1146 : * \brief Retrieve a source range that covers the given token.
1147 : */
1148 : CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken);
1149 :
1150 : /**
1151 : * \brief Tokenize the source code described by the given range into raw
1152 : * lexical tokens.
1153 : *
1154 : * \param TU the translation unit whose text is being tokenized.
1155 : *
1156 : * \param Range the source range in which text should be tokenized. All of the
1157 : * tokens produced by tokenization will fall within this source range,
1158 : *
1159 : * \param Tokens this pointer will be set to point to the array of tokens
1160 : * that occur within the given source range. The returned pointer must be
1161 : * freed with clang_disposeTokens() before the translation unit is destroyed.
1162 : *
1163 : * \param NumTokens will be set to the number of tokens in the \c *Tokens
1164 : * array.
1165 : *
1166 : */
1167 : CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range,
1168 : CXToken **Tokens, unsigned *NumTokens);
1169 :
1170 : /**
1171 : * \brief Annotate the given set of tokens by providing cursors for each token
1172 : * that can be mapped to a specific entity within the abstract syntax tree.
1173 : *
1174 : * This token-annotation routine is equivalent to invoking
1175 : * clang_getCursor() for the source locations of each of the
1176 : * tokens. The cursors provided are filtered, so that only those
1177 : * cursors that have a direct correspondence to the token are
1178 : * accepted. For example, given a function call \c f(x),
1179 : * clang_getCursor() would provide the following cursors:
1180 : *
1181 : * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
1182 : * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
1183 : * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
1184 : *
1185 : * Only the first and last of these cursors will occur within the
1186 : * annotate, since the tokens "f" and "x' directly refer to a function
1187 : * and a variable, respectively, but the parentheses are just a small
1188 : * part of the full syntax of the function call expression, which is
1189 : * not provided as an annotation.
1190 : *
1191 : * \param TU the translation unit that owns the given tokens.
1192 : *
1193 : * \param Tokens the set of tokens to annotate.
1194 : *
1195 : * \param NumTokens the number of tokens in \p Tokens.
1196 : *
1197 : * \param Cursors an array of \p NumTokens cursors, whose contents will be
1198 : * replaced with the cursors corresponding to each token.
1199 : */
1200 : CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU,
1201 : CXToken *Tokens, unsigned NumTokens,
1202 : CXCursor *Cursors);
1203 :
1204 : /**
1205 : * \brief Free the given set of tokens.
1206 : */
1207 : CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU,
1208 : CXToken *Tokens, unsigned NumTokens);
1209 :
1210 : /**
1211 : * @}
1212 : */
1213 :
1214 : /**
1215 : * \defgroup CINDEX_DEBUG Debugging facilities
1216 : *
1217 : * These routines are used for testing and debugging, only, and should not
1218 : * be relied upon.
1219 : *
1220 : * @{
1221 : */
1222 :
1223 : /* for debug/testing */
1224 : CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind);
1225 : CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor,
1226 : const char **startBuf,
1227 : const char **endBuf,
1228 : unsigned *startLine,
1229 : unsigned *startColumn,
1230 : unsigned *endLine,
1231 : unsigned *endColumn);
1232 :
1233 : /**
1234 : * @}
1235 : */
1236 :
1237 : /**
1238 : * \defgroup CINDEX_CODE_COMPLET Code completion
1239 : *
1240 : * Code completion involves taking an (incomplete) source file, along with
1241 : * knowledge of where the user is actively editing that file, and suggesting
1242 : * syntactically- and semantically-valid constructs that the user might want to
1243 : * use at that particular point in the source code. These data structures and
1244 : * routines provide support for code completion.
1245 : *
1246 : * @{
1247 : */
1248 :
1249 : /**
1250 : * \brief A semantic string that describes a code-completion result.
1251 : *
1252 : * A semantic string that describes the formatting of a code-completion
1253 : * result as a single "template" of text that should be inserted into the
1254 : * source buffer when a particular code-completion result is selected.
1255 : * Each semantic string is made up of some number of "chunks", each of which
1256 : * contains some text along with a description of what that text means, e.g.,
1257 : * the name of the entity being referenced, whether the text chunk is part of
1258 : * the template, or whether it is a "placeholder" that the user should replace
1259 : * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
1260 : * description of the different kinds of chunks.
1261 : */
1262 : typedef void *CXCompletionString;
1263 :
1264 : /**
1265 : * \brief A single result of code completion.
1266 : */
1267 : typedef struct {
1268 : /**
1269 : * \brief The kind of entity that this completion refers to.
1270 : *
1271 : * The cursor kind will be a macro, keyword, or a declaration (one of the
1272 : * *Decl cursor kinds), describing the entity that the completion is
1273 : * referring to.
1274 : *
1275 : * \todo In the future, we would like to provide a full cursor, to allow
1276 : * the client to extract additional information from declaration.
1277 : */
1278 : enum CXCursorKind CursorKind;
1279 :
1280 : /**
1281 : * \brief The code-completion string that describes how to insert this
1282 : * code-completion result into the editing buffer.
1283 : */
1284 : CXCompletionString CompletionString;
1285 4147: } CXCompletionResult;
1286 :
1287 : /**
1288 : * \brief Describes a single piece of text within a code-completion string.
1289 : *
1290 : * Each "chunk" within a code-completion string (\c CXCompletionString) is
1291 : * either a piece of text with a specific "kind" that describes how that text
1292 : * should be interpreted by the client or is another completion string.
1293 : */
1294 : enum CXCompletionChunkKind {
1295 : /**
1296 : * \brief A code-completion string that describes "optional" text that
1297 : * could be a part of the template (but is not required).
1298 : *
1299 : * The Optional chunk is the only kind of chunk that has a code-completion
1300 : * string for its representation, which is accessible via
1301 : * \c clang_getCompletionChunkCompletionString(). The code-completion string
1302 : * describes an additional part of the template that is completely optional.
1303 : * For example, optional chunks can be used to describe the placeholders for
1304 : * arguments that match up with defaulted function parameters, e.g. given:
1305 : *
1306 : * \code
1307 : * void f(int x, float y = 3.14, double z = 2.71828);
1308 : * \endcode
1309 : *
1310 : * The code-completion string for this function would contain:
1311 : * - a TypedText chunk for "f".
1312 : * - a LeftParen chunk for "(".
1313 : * - a Placeholder chunk for "int x"
1314 : * - an Optional chunk containing the remaining defaulted arguments, e.g.,
1315 : * - a Comma chunk for ","
1316 : * - a Placeholder chunk for "float x"
1317 : * - an Optional chunk containing the last defaulted argument:
1318 : * - a Comma chunk for ","
1319 : * - a Placeholder chunk for "double z"
1320 : * - a RightParen chunk for ")"
1321 : *
1322 : * There are many ways two handle Optional chunks. Two simple approaches are:
1323 : * - Completely ignore optional chunks, in which case the template for the
1324 : * function "f" would only include the first parameter ("int x").
1325 : * - Fully expand all optional chunks, in which case the template for the
1326 : * function "f" would have all of the parameters.
1327 : */
1328 : CXCompletionChunk_Optional,
1329 : /**
1330 : * \brief Text that a user would be expected to type to get this
1331 : * code-completion result.
1332 : *
1333 : * There will be exactly one "typed text" chunk in a semantic string, which
1334 : * will typically provide the spelling of a keyword or the name of a
1335 : * declaration that could be used at the current code point. Clients are
1336 : * expected to filter the code-completion results based on the text in this
1337 : * chunk.
1338 : */
1339 : CXCompletionChunk_TypedText,
1340 : /**
1341 : * \brief Text that should be inserted as part of a code-completion result.
1342 : *
1343 : * A "text" chunk represents text that is part of the template to be
1344 : * inserted into user code should this particular code-completion result
1345 : * be selected.
1346 : */
1347 : CXCompletionChunk_Text,
1348 : /**
1349 : * \brief Placeholder text that should be replaced by the user.
1350 : *
1351 : * A "placeholder" chunk marks a place where the user should insert text
1352 : * into the code-completion template. For example, placeholders might mark
1353 : * the function parameters for a function declaration, to indicate that the
1354 : * user should provide arguments for each of those parameters. The actual
1355 : * text in a placeholder is a suggestion for the text to display before
1356 : * the user replaces the placeholder with real code.
1357 : */
1358 : CXCompletionChunk_Placeholder,
1359 : /**
1360 : * \brief Informative text that should be displayed but never inserted as
1361 : * part of the template.
1362 : *
1363 : * An "informative" chunk contains annotations that can be displayed to
1364 : * help the user decide whether a particular code-completion result is the
1365 : * right option, but which is not part of the actual template to be inserted
1366 : * by code completion.
1367 : */
1368 : CXCompletionChunk_Informative,
1369 : /**
1370 : * \brief Text that describes the current parameter when code-completion is
1371 : * referring to function call, message send, or template specialization.
1372 : *
1373 : * A "current parameter" chunk occurs when code-completion is providing
1374 : * information about a parameter corresponding to the argument at the
1375 : * code-completion point. For example, given a function
1376 : *
1377 : * \code
1378 : * int add(int x, int y);
1379 : * \endcode
1380 : *
1381 : * and the source code \c add(, where the code-completion point is after the
1382 : * "(", the code-completion string will contain a "current parameter" chunk
1383 : * for "int x", indicating that the current argument will initialize that
1384 : * parameter. After typing further, to \c add(17, (where the code-completion
1385 : * point is after the ","), the code-completion string will contain a
1386 : * "current paremeter" chunk to "int y".
1387 : */
1388 : CXCompletionChunk_CurrentParameter,
1389 : /**
1390 : * \brief A left parenthesis ('('), used to initiate a function call or
1391 : * signal the beginning of a function parameter list.
1392 : */
1393 : CXCompletionChunk_LeftParen,
1394 : /**
1395 : * \brief A right parenthesis (')'), used to finish a function call or
1396 : * signal the end of a function parameter list.
1397 : */
1398 : CXCompletionChunk_RightParen,
1399 : /**
1400 : * \brief A left bracket ('[').
1401 : */
1402 : CXCompletionChunk_LeftBracket,
1403 : /**
1404 : * \brief A right bracket (']').
1405 : */
1406 : CXCompletionChunk_RightBracket,
1407 : /**
1408 : * \brief A left brace ('{').
1409 : */
1410 : CXCompletionChunk_LeftBrace,
1411 : /**
1412 : * \brief A right brace ('}').
1413 : */
1414 : CXCompletionChunk_RightBrace,
1415 : /**
1416 : * \brief A left angle bracket ('<').
1417 : */
1418 : CXCompletionChunk_LeftAngle,
1419 : /**
1420 : * \brief A right angle bracket ('>').
1421 : */
1422 : CXCompletionChunk_RightAngle,
1423 : /**
1424 : * \brief A comma separator (',').
1425 : */
1426 : CXCompletionChunk_Comma,
1427 : /**
1428 : * \brief Text that specifies the result type of a given result.
1429 : *
1430 : * This special kind of informative chunk is not meant to be inserted into
1431 : * the text buffer. Rather, it is meant to illustrate the type that an
1432 : * expression using the given completion string would have.
1433 : */
1434 : CXCompletionChunk_ResultType,
1435 : /**
1436 : * \brief A colon (':').
1437 : */
1438 : CXCompletionChunk_Colon,
1439 : /**
1440 : * \brief A semicolon (';').
1441 : */
1442 : CXCompletionChunk_SemiColon,
1443 : /**
1444 : * \brief An '=' sign.
1445 : */
1446 : CXCompletionChunk_Equal,
1447 : /**
1448 : * Horizontal space (' ').
1449 : */
1450 : CXCompletionChunk_HorizontalSpace,
1451 : /**
1452 : * Vertical space ('\n'), after which it is generally a good idea to
1453 : * perform indentation.
1454 : */
1455 : CXCompletionChunk_VerticalSpace
1456 : };
1457 :
1458 : /**
1459 : * \brief Determine the kind of a particular chunk within a completion string.
1460 : *
1461 : * \param completion_string the completion string to query.
1462 : *
1463 : * \param chunk_number the 0-based index of the chunk in the completion string.
1464 : *
1465 : * \returns the kind of the chunk at the index \c chunk_number.
1466 : */
1467 : CINDEX_LINKAGE enum CXCompletionChunkKind
1468 : clang_getCompletionChunkKind(CXCompletionString completion_string,
1469 : unsigned chunk_number);
1470 :
1471 : /**
1472 : * \brief Retrieve the text associated with a particular chunk within a
1473 : * completion string.
1474 : *
1475 : * \param completion_string the completion string to query.
1476 : *
1477 : * \param chunk_number the 0-based index of the chunk in the completion string.
1478 : *
1479 : * \returns the text associated with the chunk at index \c chunk_number.
1480 : */
1481 : CINDEX_LINKAGE const char *
1482 : clang_getCompletionChunkText(CXCompletionString completion_string,
1483 : unsigned chunk_number);
1484 :
1485 : /**
1486 : * \brief Retrieve the completion string associated with a particular chunk
1487 : * within a completion string.
1488 : *
1489 : * \param completion_string the completion string to query.
1490 : *
1491 : * \param chunk_number the 0-based index of the chunk in the completion string.
1492 : *
1493 : * \returns the completion string associated with the chunk at index
1494 : * \c chunk_number, or NULL if that chunk is not represented by a completion
1495 : * string.
1496 : */
1497 : CINDEX_LINKAGE CXCompletionString
1498 : clang_getCompletionChunkCompletionString(CXCompletionString completion_string,
1499 : unsigned chunk_number);
1500 :
1501 : /**
1502 : * \brief Retrieve the number of chunks in the given code-completion string.
1503 : */
1504 : CINDEX_LINKAGE unsigned
1505 : clang_getNumCompletionChunks(CXCompletionString completion_string);
1506 :
1507 : /**
1508 : * \brief Contains the results of code-completion.
1509 : *
1510 : * This data structure contains the results of code completion, as
1511 : * produced by \c clang_codeComplete. Its contents must be freed by
1512 : * \c clang_disposeCodeCompleteResults.
1513 : */
1514 : typedef struct {
1515 : /**
1516 : * \brief The code-completion results.
1517 : */
1518 : CXCompletionResult *Results;
1519 :
1520 : /**
1521 : * \brief The number of code-completion results stored in the
1522 : * \c Results array.
1523 : */
1524 : unsigned NumResults;
1525 51: } CXCodeCompleteResults;
1526 :
1527 : /**
1528 : * \brief Perform code completion at a given location in a source file.
1529 : *
1530 : * This function performs code completion at a particular file, line, and
1531 : * column within source code, providing results that suggest potential
1532 : * code snippets based on the context of the completion. The basic model
1533 : * for code completion is that Clang will parse a complete source file,
1534 : * performing syntax checking up to the location where code-completion has
1535 : * been requested. At that point, a special code-completion token is passed
1536 : * to the parser, which recognizes this token and determines, based on the
1537 : * current location in the C/Objective-C/C++ grammar and the state of
1538 : * semantic analysis, what completions to provide. These completions are
1539 : * returned via a new \c CXCodeCompleteResults structure.
1540 : *
1541 : * Code completion itself is meant to be triggered by the client when the
1542 : * user types punctuation characters or whitespace, at which point the
1543 : * code-completion location will coincide with the cursor. For example, if \c p
1544 : * is a pointer, code-completion might be triggered after the "-" and then
1545 : * after the ">" in \c p->. When the code-completion location is afer the ">",
1546 : * the completion results will provide, e.g., the members of the struct that
1547 : * "p" points to. The client is responsible for placing the cursor at the
1548 : * beginning of the token currently being typed, then filtering the results
1549 : * based on the contents of the token. For example, when code-completing for
1550 : * the expression \c p->get, the client should provide the location just after
1551 : * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
1552 : * client can filter the results based on the current token text ("get"), only
1553 : * showing those results that start with "get". The intent of this interface
1554 : * is to separate the relatively high-latency acquisition of code-completion
1555 : * results from the filtering of results on a per-character basis, which must
1556 : * have a lower latency.
1557 : *
1558 : * \param CIdx the \c CXIndex instance that will be used to perform code
1559 : * completion.
1560 : *
1561 : * \param source_filename the name of the source file that should be parsed to
1562 : * perform code-completion. This source file must be the same as or include the
1563 : * filename described by \p complete_filename, or no code-completion results
1564 : * will be produced. NOTE: One can also specify NULL for this argument if the
1565 : * source file is included in command_line_args.
1566 : *
1567 : * \param num_command_line_args the number of command-line arguments stored in
1568 : * \p command_line_args.
1569 : *
1570 : * \param command_line_args the command-line arguments to pass to the Clang
1571 : * compiler to build the given source file. This should include all of the
1572 : * necessary include paths, language-dialect switches, precompiled header
1573 : * includes, etc., but should not include any information specific to
1574 : * code completion.
1575 : *
1576 : * \param num_unsaved_files the number of unsaved file entries in \p
1577 : * unsaved_files.
1578 : *
1579 : * \param unsaved_files the files that have not yet been saved to disk
1580 : * but may be required for code completion, including the contents of
1581 : * those files.
1582 : *
1583 : * \param complete_filename the name of the source file where code completion
1584 : * should be performed. In many cases, this name will be the same as the
1585 : * source filename. However, the completion filename may also be a file
1586 : * included by the source file, which is required when producing
1587 : * code-completion results for a header.
1588 : *
1589 : * \param complete_line the line at which code-completion should occur.
1590 : *
1591 : * \param complete_column the column at which code-completion should occur.
1592 : * Note that the column should point just after the syntactic construct that
1593 : * initiated code completion, and not in the middle of a lexical token.
1594 : *
1595 : * \param diag_callback callback function that will receive any diagnostics
1596 : * emitted while processing this source file. If NULL, diagnostics will be
1597 : * suppressed.
1598 : *
1599 : * \param diag_client_data client data that will be passed to the diagnostic
1600 : * callback function.
1601 : *
1602 : * \returns if successful, a new CXCodeCompleteResults structure
1603 : * containing code-completion results, which should eventually be
1604 : * freed with \c clang_disposeCodeCompleteResults(). If code
1605 : * completion fails, returns NULL.
1606 : */
1607 : CINDEX_LINKAGE
1608 : CXCodeCompleteResults *clang_codeComplete(CXIndex CIdx,
1609 : const char *source_filename,
1610 : int num_command_line_args,
1611 : const char **command_line_args,
1612 : unsigned num_unsaved_files,
1613 : struct CXUnsavedFile *unsaved_files,
1614 : const char *complete_filename,
1615 : unsigned complete_line,
1616 : unsigned complete_column,
1617 : CXDiagnosticCallback diag_callback,
1618 : CXClientData diag_client_data);
1619 :
1620 : /**
1621 : * \brief Free the given set of code-completion results.
1622 : */
1623 : CINDEX_LINKAGE
1624 : void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results);
1625 :
1626 : /**
1627 : * @}
1628 : */
1629 :
1630 :
1631 : /**
1632 : * \defgroup CINDEX_MISC Miscellaneous utility functions
1633 : *
1634 : * @{
1635 : */
1636 :
1637 : /**
1638 : * \brief Return a version string, suitable for showing to a user, but not
1639 : * intended to be parsed (the format is not guaranteed to be stable).
1640 : */
1641 : CINDEX_LINKAGE const char *clang_getClangVersion();
1642 :
1643 : /**
1644 : * \brief Return a version string, suitable for showing to a user, but not
1645 : * intended to be parsed (the format is not guaranteed to be stable).
1646 : */
1647 :
1648 :
1649 : /**
1650 : * \brief Visitor invoked for each file in a translation unit
1651 : * (used with clang_getInclusions()).
1652 : *
1653 : * This visitor function will be invoked by clang_getInclusions() for each
1654 : * file included (either at the top-level or by #include directives) within
1655 : * a translation unit. The first argument is the file being included, and
1656 : * the second and third arguments provide the inclusion stack. The
1657 : * array is sorted in order of immediate inclusion. For example,
1658 : * the first element refers to the location that included 'included_file'.
1659 : */
1660 : typedef void (*CXInclusionVisitor)(CXFile included_file,
1661 : CXSourceLocation* inclusion_stack,
1662 : unsigned include_len,
1663 : CXClientData client_data);
1664 :
1665 : /**
1666 : * \brief Visit the set of preprocessor inclusions in a translation unit.
1667 : * The visitor function is called with the provided data for every included
1668 : * file. This does not include headers included by the PCH file (unless one
1669 : * is inspecting the inclusions in the PCH file itself).
1670 : */
1671 : CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu,
1672 : CXInclusionVisitor visitor,
1673 : CXClientData client_data);
1674 :
1675 : /**
1676 : * @}
1677 : */
1678 :
1679 : /**
1680 : * @}
1681 : */
1682 :
1683 : #ifdef __cplusplus
1684 : }
1685 : #endif
1686 : #endif
1687 :
Generated: 2010-02-10 01:31 by zcov