Index.h revision 212904
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#include <stdio.h>
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
27/* MSVC DLL import/export. */
28#ifdef _MSC_VER
29  #ifdef _CINDEX_LIB_
30    #define CINDEX_LINKAGE __declspec(dllexport)
31  #else
32    #define CINDEX_LINKAGE __declspec(dllimport)
33  #endif
34#else
35  #define CINDEX_LINKAGE
36#endif
37
38/** \defgroup CINDEX C Interface to Clang
39 *
40 * The C Interface to Clang provides a relatively small API that exposes
41 * facilities for parsing source code into an abstract syntax tree (AST),
42 * loading already-parsed ASTs, traversing the AST, associating
43 * physical source locations with elements within the AST, and other
44 * facilities that support Clang-based development tools.
45 *
46 * This C interface to Clang will never provide all of the information
47 * representation stored in Clang's C++ AST, nor should it: the intent is to
48 * maintain an API that is relatively stable from one release to the next,
49 * providing only the basic functionality needed to support development tools.
50 *
51 * To avoid namespace pollution, data types are prefixed with "CX" and
52 * functions are prefixed with "clang_".
53 *
54 * @{
55 */
56
57/**
58 * \brief An "index" that consists of a set of translation units that would
59 * typically be linked together into an executable or library.
60 */
61typedef void *CXIndex;
62
63/**
64 * \brief A single translation unit, which resides in an index.
65 */
66typedef void *CXTranslationUnit;  /* A translation unit instance. */
67
68/**
69 * \brief Opaque pointer representing client data that will be passed through
70 * to various callbacks and visitors.
71 */
72typedef void *CXClientData;
73
74/**
75 * \brief Provides the contents of a file that has not yet been saved to disk.
76 *
77 * Each CXUnsavedFile instance provides the name of a file on the
78 * system along with the current contents of that file that have not
79 * yet been saved to disk.
80 */
81struct CXUnsavedFile {
82  /**
83   * \brief The file whose contents have not yet been saved.
84   *
85   * This file must already exist in the file system.
86   */
87  const char *Filename;
88
89  /**
90   * \brief A buffer containing the unsaved contents of this file.
91   */
92  const char *Contents;
93
94  /**
95   * \brief The length of the unsaved contents of this buffer.
96   */
97  unsigned long Length;
98};
99
100/**
101 * \brief Describes the availability of a particular entity, which indicates
102 * whether the use of this entity will result in a warning or error due to
103 * it being deprecated or unavailable.
104 */
105enum CXAvailabilityKind {
106  /**
107   * \brief The entity is available.
108   */
109  CXAvailability_Available,
110  /**
111   * \brief The entity is available, but has been deprecated (and its use is
112   * not recommended).
113   */
114  CXAvailability_Deprecated,
115  /**
116   * \brief The entity is not available; any use of it will be an error.
117   */
118  CXAvailability_NotAvailable
119};
120
121/**
122 * \defgroup CINDEX_STRING String manipulation routines
123 *
124 * @{
125 */
126
127/**
128 * \brief A character string.
129 *
130 * The \c CXString type is used to return strings from the interface when
131 * the ownership of that string might different from one call to the next.
132 * Use \c clang_getCString() to retrieve the string data and, once finished
133 * with the string data, call \c clang_disposeString() to free the string.
134 */
135typedef struct {
136  const char *Spelling;
137  /* A 1 value indicates the clang_ indexing API needed to allocate the string
138     (and it must be freed by clang_disposeString()). */
139  int MustFreeString;
140} CXString;
141
142/**
143 * \brief Retrieve the character data associated with the given string.
144 */
145CINDEX_LINKAGE const char *clang_getCString(CXString string);
146
147/**
148 * \brief Free the given string,
149 */
150CINDEX_LINKAGE void clang_disposeString(CXString string);
151
152/**
153 * @}
154 */
155
156/**
157 * \brief clang_createIndex() provides a shared context for creating
158 * translation units. It provides two options:
159 *
160 * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
161 * declarations (when loading any new translation units). A "local" declaration
162 * is one that belongs in the translation unit itself and not in a precompiled
163 * header that was used by the translation unit. If zero, all declarations
164 * will be enumerated.
165 *
166 * Here is an example:
167 *
168 *   // excludeDeclsFromPCH = 1, displayDiagnostics=1
169 *   Idx = clang_createIndex(1, 1);
170 *
171 *   // IndexTest.pch was produced with the following command:
172 *   // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
173 *   TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
174 *
175 *   // This will load all the symbols from 'IndexTest.pch'
176 *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
177 *                       TranslationUnitVisitor, 0);
178 *   clang_disposeTranslationUnit(TU);
179 *
180 *   // This will load all the symbols from 'IndexTest.c', excluding symbols
181 *   // from 'IndexTest.pch'.
182 *   char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
183 *   TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
184 *                                                  0, 0);
185 *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
186 *                       TranslationUnitVisitor, 0);
187 *   clang_disposeTranslationUnit(TU);
188 *
189 * This process of creating the 'pch', loading it separately, and using it (via
190 * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
191 * (which gives the indexer the same performance benefit as the compiler).
192 */
193CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
194                                         int displayDiagnostics);
195
196/**
197 * \brief Destroy the given index.
198 *
199 * The index must not be destroyed until all of the translation units created
200 * within that index have been destroyed.
201 */
202CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
203
204/**
205 * \brief Request that AST's be generated externally for API calls which parse
206 * source code on the fly, e.g. \see createTranslationUnitFromSourceFile.
207 *
208 * Note: This is for debugging purposes only, and may be removed at a later
209 * date.
210 *
211 * \param index - The index to update.
212 * \param value - The new flag value.
213 */
214CINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index,
215                                                      int value);
216/**
217 * \defgroup CINDEX_FILES File manipulation routines
218 *
219 * @{
220 */
221
222/**
223 * \brief A particular source file that is part of a translation unit.
224 */
225typedef void *CXFile;
226
227
228/**
229 * \brief Retrieve the complete file and path name of the given file.
230 */
231CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile);
232
233/**
234 * \brief Retrieve the last modification time of the given file.
235 */
236CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
237
238/**
239 * \brief Retrieve a file handle within the given translation unit.
240 *
241 * \param tu the translation unit
242 *
243 * \param file_name the name of the file.
244 *
245 * \returns the file handle for the named file in the translation unit \p tu,
246 * or a NULL file handle if the file was not a part of this translation unit.
247 */
248CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu,
249                                    const char *file_name);
250
251/**
252 * @}
253 */
254
255/**
256 * \defgroup CINDEX_LOCATIONS Physical source locations
257 *
258 * Clang represents physical source locations in its abstract syntax tree in
259 * great detail, with file, line, and column information for the majority of
260 * the tokens parsed in the source code. These data types and functions are
261 * used to represent source location information, either for a particular
262 * point in the program or for a range of points in the program, and extract
263 * specific location information from those data types.
264 *
265 * @{
266 */
267
268/**
269 * \brief Identifies a specific source location within a translation
270 * unit.
271 *
272 * Use clang_getInstantiationLocation() to map a source location to a
273 * particular file, line, and column.
274 */
275typedef struct {
276  void *ptr_data[2];
277  unsigned int_data;
278} CXSourceLocation;
279
280/**
281 * \brief Identifies a half-open character range in the source code.
282 *
283 * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
284 * starting and end locations from a source range, respectively.
285 */
286typedef struct {
287  void *ptr_data[2];
288  unsigned begin_int_data;
289  unsigned end_int_data;
290} CXSourceRange;
291
292/**
293 * \brief Retrieve a NULL (invalid) source location.
294 */
295CINDEX_LINKAGE CXSourceLocation clang_getNullLocation();
296
297/**
298 * \determine Determine whether two source locations, which must refer into
299 * the same translation unit, refer to exactly the same point in the source
300 * code.
301 *
302 * \returns non-zero if the source locations refer to the same location, zero
303 * if they refer to different locations.
304 */
305CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1,
306                                             CXSourceLocation loc2);
307
308/**
309 * \brief Retrieves the source location associated with a given file/line/column
310 * in a particular translation unit.
311 */
312CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu,
313                                                  CXFile file,
314                                                  unsigned line,
315                                                  unsigned column);
316
317/**
318 * \brief Retrieve a NULL (invalid) source range.
319 */
320CINDEX_LINKAGE CXSourceRange clang_getNullRange();
321
322/**
323 * \brief Retrieve a source range given the beginning and ending source
324 * locations.
325 */
326CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin,
327                                            CXSourceLocation end);
328
329/**
330 * \brief Retrieve the file, line, column, and offset represented by
331 * the given source location.
332 *
333 * \param location the location within a source file that will be decomposed
334 * into its parts.
335 *
336 * \param file [out] if non-NULL, will be set to the file to which the given
337 * source location points.
338 *
339 * \param line [out] if non-NULL, will be set to the line to which the given
340 * source location points.
341 *
342 * \param column [out] if non-NULL, will be set to the column to which the given
343 * source location points.
344 *
345 * \param offset [out] if non-NULL, will be set to the offset into the
346 * buffer to which the given source location points.
347 */
348CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location,
349                                                   CXFile *file,
350                                                   unsigned *line,
351                                                   unsigned *column,
352                                                   unsigned *offset);
353
354/**
355 * \brief Retrieve a source location representing the first character within a
356 * source range.
357 */
358CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
359
360/**
361 * \brief Retrieve a source location representing the last character within a
362 * source range.
363 */
364CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
365
366/**
367 * @}
368 */
369
370/**
371 * \defgroup CINDEX_DIAG Diagnostic reporting
372 *
373 * @{
374 */
375
376/**
377 * \brief Describes the severity of a particular diagnostic.
378 */
379enum CXDiagnosticSeverity {
380  /**
381   * \brief A diagnostic that has been suppressed, e.g., by a command-line
382   * option.
383   */
384  CXDiagnostic_Ignored = 0,
385
386  /**
387   * \brief This diagnostic is a note that should be attached to the
388   * previous (non-note) diagnostic.
389   */
390  CXDiagnostic_Note    = 1,
391
392  /**
393   * \brief This diagnostic indicates suspicious code that may not be
394   * wrong.
395   */
396  CXDiagnostic_Warning = 2,
397
398  /**
399   * \brief This diagnostic indicates that the code is ill-formed.
400   */
401  CXDiagnostic_Error   = 3,
402
403  /**
404   * \brief This diagnostic indicates that the code is ill-formed such
405   * that future parser recovery is unlikely to produce useful
406   * results.
407   */
408  CXDiagnostic_Fatal   = 4
409};
410
411/**
412 * \brief A single diagnostic, containing the diagnostic's severity,
413 * location, text, source ranges, and fix-it hints.
414 */
415typedef void *CXDiagnostic;
416
417/**
418 * \brief Determine the number of diagnostics produced for the given
419 * translation unit.
420 */
421CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit);
422
423/**
424 * \brief Retrieve a diagnostic associated with the given translation unit.
425 *
426 * \param Unit the translation unit to query.
427 * \param Index the zero-based diagnostic number to retrieve.
428 *
429 * \returns the requested diagnostic. This diagnostic must be freed
430 * via a call to \c clang_disposeDiagnostic().
431 */
432CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit,
433                                                unsigned Index);
434
435/**
436 * \brief Destroy a diagnostic.
437 */
438CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);
439
440/**
441 * \brief Options to control the display of diagnostics.
442 *
443 * The values in this enum are meant to be combined to customize the
444 * behavior of \c clang_displayDiagnostic().
445 */
446enum CXDiagnosticDisplayOptions {
447  /**
448   * \brief Display the source-location information where the
449   * diagnostic was located.
450   *
451   * When set, diagnostics will be prefixed by the file, line, and
452   * (optionally) column to which the diagnostic refers. For example,
453   *
454   * \code
455   * test.c:28: warning: extra tokens at end of #endif directive
456   * \endcode
457   *
458   * This option corresponds to the clang flag \c -fshow-source-location.
459   */
460  CXDiagnostic_DisplaySourceLocation = 0x01,
461
462  /**
463   * \brief If displaying the source-location information of the
464   * diagnostic, also include the column number.
465   *
466   * This option corresponds to the clang flag \c -fshow-column.
467   */
468  CXDiagnostic_DisplayColumn = 0x02,
469
470  /**
471   * \brief If displaying the source-location information of the
472   * diagnostic, also include information about source ranges in a
473   * machine-parsable format.
474   *
475   * This option corresponds to the clang flag
476   * \c -fdiagnostics-print-source-range-info.
477   */
478  CXDiagnostic_DisplaySourceRanges = 0x04
479};
480
481/**
482 * \brief Format the given diagnostic in a manner that is suitable for display.
483 *
484 * This routine will format the given diagnostic to a string, rendering
485 * the diagnostic according to the various options given. The
486 * \c clang_defaultDiagnosticDisplayOptions() function returns the set of
487 * options that most closely mimics the behavior of the clang compiler.
488 *
489 * \param Diagnostic The diagnostic to print.
490 *
491 * \param Options A set of options that control the diagnostic display,
492 * created by combining \c CXDiagnosticDisplayOptions values.
493 *
494 * \returns A new string containing for formatted diagnostic.
495 */
496CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,
497                                               unsigned Options);
498
499/**
500 * \brief Retrieve the set of display options most similar to the
501 * default behavior of the clang compiler.
502 *
503 * \returns A set of display options suitable for use with \c
504 * clang_displayDiagnostic().
505 */
506CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void);
507
508/**
509 * \brief Print a diagnostic to the given file.
510 */
511
512/**
513 * \brief Determine the severity of the given diagnostic.
514 */
515CINDEX_LINKAGE enum CXDiagnosticSeverity
516clang_getDiagnosticSeverity(CXDiagnostic);
517
518/**
519 * \brief Retrieve the source location of the given diagnostic.
520 *
521 * This location is where Clang would print the caret ('^') when
522 * displaying the diagnostic on the command line.
523 */
524CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);
525
526/**
527 * \brief Retrieve the text of the given diagnostic.
528 */
529CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);
530
531/**
532 * \brief Determine the number of source ranges associated with the given
533 * diagnostic.
534 */
535CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
536
537/**
538 * \brief Retrieve a source range associated with the diagnostic.
539 *
540 * A diagnostic's source ranges highlight important elements in the source
541 * code. On the command line, Clang displays source ranges by
542 * underlining them with '~' characters.
543 *
544 * \param Diagnostic the diagnostic whose range is being extracted.
545 *
546 * \param Range the zero-based index specifying which range to
547 *
548 * \returns the requested source range.
549 */
550CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,
551                                                      unsigned Range);
552
553/**
554 * \brief Determine the number of fix-it hints associated with the
555 * given diagnostic.
556 */
557CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
558
559/**
560 * \brief Retrieve the replacement information for a given fix-it.
561 *
562 * Fix-its are described in terms of a source range whose contents
563 * should be replaced by a string. This approach generalizes over
564 * three kinds of operations: removal of source code (the range covers
565 * the code to be removed and the replacement string is empty),
566 * replacement of source code (the range covers the code to be
567 * replaced and the replacement string provides the new code), and
568 * insertion (both the start and end of the range point at the
569 * insertion location, and the replacement string provides the text to
570 * insert).
571 *
572 * \param Diagnostic The diagnostic whose fix-its are being queried.
573 *
574 * \param FixIt The zero-based index of the fix-it.
575 *
576 * \param ReplacementRange The source range whose contents will be
577 * replaced with the returned replacement string. Note that source
578 * ranges are half-open ranges [a, b), so the source code should be
579 * replaced from a and up to (but not including) b.
580 *
581 * \returns A string containing text that should be replace the source
582 * code indicated by the \c ReplacementRange.
583 */
584CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic,
585                                                 unsigned FixIt,
586                                               CXSourceRange *ReplacementRange);
587
588/**
589 * @}
590 */
591
592/**
593 * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
594 *
595 * The routines in this group provide the ability to create and destroy
596 * translation units from files, either by parsing the contents of the files or
597 * by reading in a serialized representation of a translation unit.
598 *
599 * @{
600 */
601
602/**
603 * \brief Get the original translation unit source file name.
604 */
605CINDEX_LINKAGE CXString
606clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
607
608/**
609 * \brief Return the CXTranslationUnit for a given source file and the provided
610 * command line arguments one would pass to the compiler.
611 *
612 * Note: The 'source_filename' argument is optional.  If the caller provides a
613 * NULL pointer, the name of the source file is expected to reside in the
614 * specified command line arguments.
615 *
616 * Note: When encountered in 'clang_command_line_args', the following options
617 * are ignored:
618 *
619 *   '-c'
620 *   '-emit-ast'
621 *   '-fsyntax-only'
622 *   '-o <output file>'  (both '-o' and '<output file>' are ignored)
623 *
624 *
625 * \param source_filename - The name of the source file to load, or NULL if the
626 * source file is included in clang_command_line_args.
627 *
628 * \param num_unsaved_files the number of unsaved file entries in \p
629 * unsaved_files.
630 *
631 * \param unsaved_files the files that have not yet been saved to disk
632 * but may be required for code completion, including the contents of
633 * those files.  The contents and name of these files (as specified by
634 * CXUnsavedFile) are copied when necessary, so the client only needs to
635 * guarantee their validity until the call to this function returns.
636 *
637 * \param diag_callback callback function that will receive any diagnostics
638 * emitted while processing this source file. If NULL, diagnostics will be
639 * suppressed.
640 *
641 * \param diag_client_data client data that will be passed to the diagnostic
642 * callback function.
643 */
644CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
645                                         CXIndex CIdx,
646                                         const char *source_filename,
647                                         int num_clang_command_line_args,
648                                   const char * const *clang_command_line_args,
649                                         unsigned num_unsaved_files,
650                                         struct CXUnsavedFile *unsaved_files);
651
652/**
653 * \brief Create a translation unit from an AST file (-emit-ast).
654 */
655CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex,
656                                             const char *ast_filename);
657
658/**
659 * \brief Flags that control the creation of translation units.
660 *
661 * The enumerators in this enumeration type are meant to be bitwise
662 * ORed together to specify which options should be used when
663 * constructing the translation unit.
664 */
665enum CXTranslationUnit_Flags {
666  /**
667   * \brief Used to indicate that no special translation-unit options are
668   * needed.
669   */
670  CXTranslationUnit_None = 0x0,
671
672  /**
673   * \brief Used to indicate that the parser should construct a "detailed"
674   * preprocessing record, including all macro definitions and instantiations.
675   *
676   * Constructing a detailed preprocessing record requires more memory
677   * and time to parse, since the information contained in the record
678   * is usually not retained. However, it can be useful for
679   * applications that require more detailed information about the
680   * behavior of the preprocessor.
681   */
682  CXTranslationUnit_DetailedPreprocessingRecord = 0x01,
683
684  /**
685   * \brief Used to indicate that the translation unit is incomplete.
686   *
687   * When a translation unit is considered "incomplete", semantic
688   * analysis that is typically performed at the end of the
689   * translation unit will be suppressed. For example, this suppresses
690   * the completion of tentative declarations in C and of
691   * instantiation of implicitly-instantiation function templates in
692   * C++. This option is typically used when parsing a header with the
693   * intent of producing a precompiled header.
694   */
695  CXTranslationUnit_Incomplete = 0x02,
696
697  /**
698   * \brief Used to indicate that the translation unit should be built with an
699   * implicit precompiled header for the preamble.
700   *
701   * An implicit precompiled header is used as an optimization when a
702   * particular translation unit is likely to be reparsed many times
703   * when the sources aren't changing that often. In this case, an
704   * implicit precompiled header will be built containing all of the
705   * initial includes at the top of the main file (what we refer to as
706   * the "preamble" of the file). In subsequent parses, if the
707   * preamble or the files in it have not changed, \c
708   * clang_reparseTranslationUnit() will re-use the implicit
709   * precompiled header to improve parsing performance.
710   */
711  CXTranslationUnit_PrecompiledPreamble = 0x04,
712
713  /**
714   * \brief Used to indicate that the translation unit should cache some
715   * code-completion results with each reparse of the source file.
716   *
717   * Caching of code-completion results is a performance optimization that
718   * introduces some overhead to reparsing but improves the performance of
719   * code-completion operations.
720   */
721  CXTranslationUnit_CacheCompletionResults = 0x08
722};
723
724/**
725 * \brief Returns the set of flags that is suitable for parsing a translation
726 * unit that is being edited.
727 *
728 * The set of flags returned provide options for \c clang_parseTranslationUnit()
729 * to indicate that the translation unit is likely to be reparsed many times,
730 * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly
731 * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag
732 * set contains an unspecified set of optimizations (e.g., the precompiled
733 * preamble) geared toward improving the performance of these routines. The
734 * set of optimizations enabled may change from one version to the next.
735 */
736CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
737
738/**
739 * \brief Parse the given source file and the translation unit corresponding
740 * to that file.
741 *
742 * This routine is the main entry point for the Clang C API, providing the
743 * ability to parse a source file into a translation unit that can then be
744 * queried by other functions in the API. This routine accepts a set of
745 * command-line arguments so that the compilation can be configured in the same
746 * way that the compiler is configured on the command line.
747 *
748 * \param CIdx The index object with which the translation unit will be
749 * associated.
750 *
751 * \param source_filename The name of the source file to load, or NULL if the
752 * source file is included in \p clang_command_line_args.
753 *
754 * \param command_line_args The command-line arguments that would be
755 * passed to the \c clang executable if it were being invoked out-of-process.
756 * These command-line options will be parsed and will affect how the translation
757 * unit is parsed. Note that the following options are ignored: '-c',
758 * '-emit-ast', '-fsyntex-only' (which is the default), and '-o <output file>'.
759 *
760 * \param num_command_line_args The number of command-line arguments in
761 * \p command_line_args.
762 *
763 * \param unsaved_files the files that have not yet been saved to disk
764 * but may be required for parsing, including the contents of
765 * those files.  The contents and name of these files (as specified by
766 * CXUnsavedFile) are copied when necessary, so the client only needs to
767 * guarantee their validity until the call to this function returns.
768 *
769 * \param num_unsaved_files the number of unsaved file entries in \p
770 * unsaved_files.
771 *
772 * \param options A bitmask of options that affects how the translation unit
773 * is managed but not its compilation. This should be a bitwise OR of the
774 * CXTranslationUnit_XXX flags.
775 *
776 * \returns A new translation unit describing the parsed code and containing
777 * any diagnostics produced by the compiler. If there is a failure from which
778 * the compiler cannot recover, returns NULL.
779 */
780CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx,
781                                                    const char *source_filename,
782                                         const char * const *command_line_args,
783                                                      int num_command_line_args,
784                                            struct CXUnsavedFile *unsaved_files,
785                                                     unsigned num_unsaved_files,
786                                                            unsigned options);
787
788/**
789 * \brief Flags that control how translation units are saved.
790 *
791 * The enumerators in this enumeration type are meant to be bitwise
792 * ORed together to specify which options should be used when
793 * saving the translation unit.
794 */
795enum CXSaveTranslationUnit_Flags {
796  /**
797   * \brief Used to indicate that no special saving options are needed.
798   */
799  CXSaveTranslationUnit_None = 0x0
800};
801
802/**
803 * \brief Returns the set of flags that is suitable for saving a translation
804 * unit.
805 *
806 * The set of flags returned provide options for
807 * \c clang_saveTranslationUnit() by default. The returned flag
808 * set contains an unspecified set of options that save translation units with
809 * the most commonly-requested data.
810 */
811CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU);
812
813/**
814 * \brief Saves a translation unit into a serialized representation of
815 * that translation unit on disk.
816 *
817 * Any translation unit that was parsed without error can be saved
818 * into a file. The translation unit can then be deserialized into a
819 * new \c CXTranslationUnit with \c clang_createTranslationUnit() or,
820 * if it is an incomplete translation unit that corresponds to a
821 * header, used as a precompiled header when parsing other translation
822 * units.
823 *
824 * \param TU The translation unit to save.
825 *
826 * \param FileName The file to which the translation unit will be saved.
827 *
828 * \param options A bitmask of options that affects how the translation unit
829 * is saved. This should be a bitwise OR of the
830 * CXSaveTranslationUnit_XXX flags.
831 *
832 * \returns Zero if the translation unit was saved successfully, a
833 * non-zero value otherwise.
834 */
835CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU,
836                                             const char *FileName,
837                                             unsigned options);
838
839/**
840 * \brief Destroy the specified CXTranslationUnit object.
841 */
842CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
843
844/**
845 * \brief Flags that control the reparsing of translation units.
846 *
847 * The enumerators in this enumeration type are meant to be bitwise
848 * ORed together to specify which options should be used when
849 * reparsing the translation unit.
850 */
851enum CXReparse_Flags {
852  /**
853   * \brief Used to indicate that no special reparsing options are needed.
854   */
855  CXReparse_None = 0x0
856};
857
858/**
859 * \brief Returns the set of flags that is suitable for reparsing a translation
860 * unit.
861 *
862 * The set of flags returned provide options for
863 * \c clang_reparseTranslationUnit() by default. The returned flag
864 * set contains an unspecified set of optimizations geared toward common uses
865 * of reparsing. The set of optimizations enabled may change from one version
866 * to the next.
867 */
868CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU);
869
870/**
871 * \brief Reparse the source files that produced this translation unit.
872 *
873 * This routine can be used to re-parse the source files that originally
874 * created the given translation unit, for example because those source files
875 * have changed (either on disk or as passed via \p unsaved_files). The
876 * source code will be reparsed with the same command-line options as it
877 * was originally parsed.
878 *
879 * Reparsing a translation unit invalidates all cursors and source locations
880 * that refer into that translation unit. This makes reparsing a translation
881 * unit semantically equivalent to destroying the translation unit and then
882 * creating a new translation unit with the same command-line arguments.
883 * However, it may be more efficient to reparse a translation
884 * unit using this routine.
885 *
886 * \param TU The translation unit whose contents will be re-parsed. The
887 * translation unit must originally have been built with
888 * \c clang_createTranslationUnitFromSourceFile().
889 *
890 * \param num_unsaved_files The number of unsaved file entries in \p
891 * unsaved_files.
892 *
893 * \param unsaved_files The files that have not yet been saved to disk
894 * but may be required for parsing, including the contents of
895 * those files.  The contents and name of these files (as specified by
896 * CXUnsavedFile) are copied when necessary, so the client only needs to
897 * guarantee their validity until the call to this function returns.
898 *
899 * \param options A bitset of options composed of the flags in CXReparse_Flags.
900 * The function \c clang_defaultReparseOptions() produces a default set of
901 * options recommended for most uses, based on the translation unit.
902 *
903 * \returns 0 if the sources could be reparsed. A non-zero value will be
904 * returned if reparsing was impossible, such that the translation unit is
905 * invalid. In such cases, the only valid call for \p TU is
906 * \c clang_disposeTranslationUnit(TU).
907 */
908CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU,
909                                                unsigned num_unsaved_files,
910                                          struct CXUnsavedFile *unsaved_files,
911                                                unsigned options);
912
913/**
914 * @}
915 */
916
917/**
918 * \brief Describes the kind of entity that a cursor refers to.
919 */
920enum CXCursorKind {
921  /* Declarations */
922  /**
923   * \brief A declaration whose specific kind is not exposed via this
924   * interface.
925   *
926   * Unexposed declarations have the same operations as any other kind
927   * of declaration; one can extract their location information,
928   * spelling, find their definitions, etc. However, the specific kind
929   * of the declaration is not reported.
930   */
931  CXCursor_UnexposedDecl                 = 1,
932  /** \brief A C or C++ struct. */
933  CXCursor_StructDecl                    = 2,
934  /** \brief A C or C++ union. */
935  CXCursor_UnionDecl                     = 3,
936  /** \brief A C++ class. */
937  CXCursor_ClassDecl                     = 4,
938  /** \brief An enumeration. */
939  CXCursor_EnumDecl                      = 5,
940  /**
941   * \brief A field (in C) or non-static data member (in C++) in a
942   * struct, union, or C++ class.
943   */
944  CXCursor_FieldDecl                     = 6,
945  /** \brief An enumerator constant. */
946  CXCursor_EnumConstantDecl              = 7,
947  /** \brief A function. */
948  CXCursor_FunctionDecl                  = 8,
949  /** \brief A variable. */
950  CXCursor_VarDecl                       = 9,
951  /** \brief A function or method parameter. */
952  CXCursor_ParmDecl                      = 10,
953  /** \brief An Objective-C @interface. */
954  CXCursor_ObjCInterfaceDecl             = 11,
955  /** \brief An Objective-C @interface for a category. */
956  CXCursor_ObjCCategoryDecl              = 12,
957  /** \brief An Objective-C @protocol declaration. */
958  CXCursor_ObjCProtocolDecl              = 13,
959  /** \brief An Objective-C @property declaration. */
960  CXCursor_ObjCPropertyDecl              = 14,
961  /** \brief An Objective-C instance variable. */
962  CXCursor_ObjCIvarDecl                  = 15,
963  /** \brief An Objective-C instance method. */
964  CXCursor_ObjCInstanceMethodDecl        = 16,
965  /** \brief An Objective-C class method. */
966  CXCursor_ObjCClassMethodDecl           = 17,
967  /** \brief An Objective-C @implementation. */
968  CXCursor_ObjCImplementationDecl        = 18,
969  /** \brief An Objective-C @implementation for a category. */
970  CXCursor_ObjCCategoryImplDecl          = 19,
971  /** \brief A typedef */
972  CXCursor_TypedefDecl                   = 20,
973  /** \brief A C++ class method. */
974  CXCursor_CXXMethod                     = 21,
975  /** \brief A C++ namespace. */
976  CXCursor_Namespace                     = 22,
977  /** \brief A linkage specification, e.g. 'extern "C"'. */
978  CXCursor_LinkageSpec                   = 23,
979  /** \brief A C++ constructor. */
980  CXCursor_Constructor                   = 24,
981  /** \brief A C++ destructor. */
982  CXCursor_Destructor                    = 25,
983  /** \brief A C++ conversion function. */
984  CXCursor_ConversionFunction            = 26,
985  /** \brief A C++ template type parameter. */
986  CXCursor_TemplateTypeParameter         = 27,
987  /** \brief A C++ non-type template parameter. */
988  CXCursor_NonTypeTemplateParameter      = 28,
989  /** \brief A C++ template template parameter. */
990  CXCursor_TemplateTemplateParameter     = 29,
991  /** \brief A C++ function template. */
992  CXCursor_FunctionTemplate              = 30,
993  /** \brief A C++ class template. */
994  CXCursor_ClassTemplate                 = 31,
995  /** \brief A C++ class template partial specialization. */
996  CXCursor_ClassTemplatePartialSpecialization = 32,
997  /** \brief A C++ namespace alias declaration. */
998  CXCursor_NamespaceAlias                = 33,
999  /** \brief A C++ using directive. */
1000  CXCursor_UsingDirective                = 34,
1001  /** \brief A using declaration. */
1002  CXCursor_UsingDeclaration              = 35,
1003
1004  CXCursor_FirstDecl                     = CXCursor_UnexposedDecl,
1005  CXCursor_LastDecl                      = CXCursor_UsingDeclaration,
1006
1007  /* References */
1008  CXCursor_FirstRef                      = 40, /* Decl references */
1009  CXCursor_ObjCSuperClassRef             = 40,
1010  CXCursor_ObjCProtocolRef               = 41,
1011  CXCursor_ObjCClassRef                  = 42,
1012  /**
1013   * \brief A reference to a type declaration.
1014   *
1015   * A type reference occurs anywhere where a type is named but not
1016   * declared. For example, given:
1017   *
1018   * \code
1019   * typedef unsigned size_type;
1020   * size_type size;
1021   * \endcode
1022   *
1023   * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
1024   * while the type of the variable "size" is referenced. The cursor
1025   * referenced by the type of size is the typedef for size_type.
1026   */
1027  CXCursor_TypeRef                       = 43,
1028  CXCursor_CXXBaseSpecifier              = 44,
1029  /**
1030   * \brief A reference to a class template, function template, or template
1031   * template parameter.
1032   */
1033  CXCursor_TemplateRef                   = 45,
1034  /**
1035   * \brief A reference to a namespace or namespace alias.
1036   */
1037  CXCursor_NamespaceRef                  = 46,
1038  CXCursor_LastRef                       = CXCursor_NamespaceRef,
1039
1040  /* Error conditions */
1041  CXCursor_FirstInvalid                  = 70,
1042  CXCursor_InvalidFile                   = 70,
1043  CXCursor_NoDeclFound                   = 71,
1044  CXCursor_NotImplemented                = 72,
1045  CXCursor_InvalidCode                   = 73,
1046  CXCursor_LastInvalid                   = CXCursor_InvalidCode,
1047
1048  /* Expressions */
1049  CXCursor_FirstExpr                     = 100,
1050
1051  /**
1052   * \brief An expression whose specific kind is not exposed via this
1053   * interface.
1054   *
1055   * Unexposed expressions have the same operations as any other kind
1056   * of expression; one can extract their location information,
1057   * spelling, children, etc. However, the specific kind of the
1058   * expression is not reported.
1059   */
1060  CXCursor_UnexposedExpr                 = 100,
1061
1062  /**
1063   * \brief An expression that refers to some value declaration, such
1064   * as a function, varible, or enumerator.
1065   */
1066  CXCursor_DeclRefExpr                   = 101,
1067
1068  /**
1069   * \brief An expression that refers to a member of a struct, union,
1070   * class, Objective-C class, etc.
1071   */
1072  CXCursor_MemberRefExpr                 = 102,
1073
1074  /** \brief An expression that calls a function. */
1075  CXCursor_CallExpr                      = 103,
1076
1077  /** \brief An expression that sends a message to an Objective-C
1078   object or class. */
1079  CXCursor_ObjCMessageExpr               = 104,
1080
1081  /** \brief An expression that represents a block literal. */
1082  CXCursor_BlockExpr                     = 105,
1083
1084  CXCursor_LastExpr                      = 105,
1085
1086  /* Statements */
1087  CXCursor_FirstStmt                     = 200,
1088  /**
1089   * \brief A statement whose specific kind is not exposed via this
1090   * interface.
1091   *
1092   * Unexposed statements have the same operations as any other kind of
1093   * statement; one can extract their location information, spelling,
1094   * children, etc. However, the specific kind of the statement is not
1095   * reported.
1096   */
1097  CXCursor_UnexposedStmt                 = 200,
1098  CXCursor_LastStmt                      = 200,
1099
1100  /**
1101   * \brief Cursor that represents the translation unit itself.
1102   *
1103   * The translation unit cursor exists primarily to act as the root
1104   * cursor for traversing the contents of a translation unit.
1105   */
1106  CXCursor_TranslationUnit               = 300,
1107
1108  /* Attributes */
1109  CXCursor_FirstAttr                     = 400,
1110  /**
1111   * \brief An attribute whose specific kind is not exposed via this
1112   * interface.
1113   */
1114  CXCursor_UnexposedAttr                 = 400,
1115
1116  CXCursor_IBActionAttr                  = 401,
1117  CXCursor_IBOutletAttr                  = 402,
1118  CXCursor_IBOutletCollectionAttr        = 403,
1119  CXCursor_LastAttr                      = CXCursor_IBOutletCollectionAttr,
1120
1121  /* Preprocessing */
1122  CXCursor_PreprocessingDirective        = 500,
1123  CXCursor_MacroDefinition               = 501,
1124  CXCursor_MacroInstantiation            = 502,
1125  CXCursor_FirstPreprocessing            = CXCursor_PreprocessingDirective,
1126  CXCursor_LastPreprocessing             = CXCursor_MacroInstantiation
1127};
1128
1129/**
1130 * \brief A cursor representing some element in the abstract syntax tree for
1131 * a translation unit.
1132 *
1133 * The cursor abstraction unifies the different kinds of entities in a
1134 * program--declaration, statements, expressions, references to declarations,
1135 * etc.--under a single "cursor" abstraction with a common set of operations.
1136 * Common operation for a cursor include: getting the physical location in
1137 * a source file where the cursor points, getting the name associated with a
1138 * cursor, and retrieving cursors for any child nodes of a particular cursor.
1139 *
1140 * Cursors can be produced in two specific ways.
1141 * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
1142 * from which one can use clang_visitChildren() to explore the rest of the
1143 * translation unit. clang_getCursor() maps from a physical source location
1144 * to the entity that resides at that location, allowing one to map from the
1145 * source code into the AST.
1146 */
1147typedef struct {
1148  enum CXCursorKind kind;
1149  void *data[3];
1150} CXCursor;
1151
1152/**
1153 * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
1154 *
1155 * @{
1156 */
1157
1158/**
1159 * \brief Retrieve the NULL cursor, which represents no entity.
1160 */
1161CINDEX_LINKAGE CXCursor clang_getNullCursor(void);
1162
1163/**
1164 * \brief Retrieve the cursor that represents the given translation unit.
1165 *
1166 * The translation unit cursor can be used to start traversing the
1167 * various declarations within the given translation unit.
1168 */
1169CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit);
1170
1171/**
1172 * \brief Determine whether two cursors are equivalent.
1173 */
1174CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor);
1175
1176/**
1177 * \brief Retrieve the kind of the given cursor.
1178 */
1179CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
1180
1181/**
1182 * \brief Determine whether the given cursor kind represents a declaration.
1183 */
1184CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
1185
1186/**
1187 * \brief Determine whether the given cursor kind represents a simple
1188 * reference.
1189 *
1190 * Note that other kinds of cursors (such as expressions) can also refer to
1191 * other cursors. Use clang_getCursorReferenced() to determine whether a
1192 * particular cursor refers to another entity.
1193 */
1194CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
1195
1196/**
1197 * \brief Determine whether the given cursor kind represents an expression.
1198 */
1199CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind);
1200
1201/**
1202 * \brief Determine whether the given cursor kind represents a statement.
1203 */
1204CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind);
1205
1206/**
1207 * \brief Determine whether the given cursor kind represents an invalid
1208 * cursor.
1209 */
1210CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
1211
1212/**
1213 * \brief Determine whether the given cursor kind represents a translation
1214 * unit.
1215 */
1216CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind);
1217
1218/***
1219 * \brief Determine whether the given cursor represents a preprocessing
1220 * element, such as a preprocessor directive or macro instantiation.
1221 */
1222CINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind);
1223
1224/***
1225 * \brief Determine whether the given cursor represents a currently
1226 *  unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).
1227 */
1228CINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind);
1229
1230/**
1231 * \brief Describe the linkage of the entity referred to by a cursor.
1232 */
1233enum CXLinkageKind {
1234  /** \brief This value indicates that no linkage information is available
1235   * for a provided CXCursor. */
1236  CXLinkage_Invalid,
1237  /**
1238   * \brief This is the linkage for variables, parameters, and so on that
1239   *  have automatic storage.  This covers normal (non-extern) local variables.
1240   */
1241  CXLinkage_NoLinkage,
1242  /** \brief This is the linkage for static variables and static functions. */
1243  CXLinkage_Internal,
1244  /** \brief This is the linkage for entities with external linkage that live
1245   * in C++ anonymous namespaces.*/
1246  CXLinkage_UniqueExternal,
1247  /** \brief This is the linkage for entities with true, external linkage. */
1248  CXLinkage_External
1249};
1250
1251/**
1252 * \brief Determine the linkage of the entity referred to by a given cursor.
1253 */
1254CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor);
1255
1256/**
1257 * \brief Determine the availability of the entity that this cursor refers to.
1258 *
1259 * \param cursor The cursor to query.
1260 *
1261 * \returns The availability of the cursor.
1262 */
1263CINDEX_LINKAGE enum CXAvailabilityKind
1264clang_getCursorAvailability(CXCursor cursor);
1265
1266/**
1267 * \brief Describe the "language" of the entity referred to by a cursor.
1268 */
1269CINDEX_LINKAGE enum CXLanguageKind {
1270  CXLanguage_Invalid = 0,
1271  CXLanguage_C,
1272  CXLanguage_ObjC,
1273  CXLanguage_CPlusPlus
1274};
1275
1276/**
1277 * \brief Determine the "language" of the entity referred to by a given cursor.
1278 */
1279CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor);
1280
1281/**
1282 * @}
1283 */
1284
1285/**
1286 * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
1287 *
1288 * Cursors represent a location within the Abstract Syntax Tree (AST). These
1289 * routines help map between cursors and the physical locations where the
1290 * described entities occur in the source code. The mapping is provided in
1291 * both directions, so one can map from source code to the AST and back.
1292 *
1293 * @{
1294 */
1295
1296/**
1297 * \brief Map a source location to the cursor that describes the entity at that
1298 * location in the source code.
1299 *
1300 * clang_getCursor() maps an arbitrary source location within a translation
1301 * unit down to the most specific cursor that describes the entity at that
1302 * location. For example, given an expression \c x + y, invoking
1303 * clang_getCursor() with a source location pointing to "x" will return the
1304 * cursor for "x"; similarly for "y". If the cursor points anywhere between
1305 * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
1306 * will return a cursor referring to the "+" expression.
1307 *
1308 * \returns a cursor representing the entity at the given source location, or
1309 * a NULL cursor if no such entity can be found.
1310 */
1311CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation);
1312
1313/**
1314 * \brief Retrieve the physical location of the source constructor referenced
1315 * by the given cursor.
1316 *
1317 * The location of a declaration is typically the location of the name of that
1318 * declaration, where the name of that declaration would occur if it is
1319 * unnamed, or some keyword that introduces that particular declaration.
1320 * The location of a reference is where that reference occurs within the
1321 * source code.
1322 */
1323CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor);
1324
1325/**
1326 * \brief Retrieve the physical extent of the source construct referenced by
1327 * the given cursor.
1328 *
1329 * The extent of a cursor starts with the file/line/column pointing at the
1330 * first character within the source construct that the cursor refers to and
1331 * ends with the last character withinin that source construct. For a
1332 * declaration, the extent covers the declaration itself. For a reference,
1333 * the extent covers the location of the reference (e.g., where the referenced
1334 * entity was actually used).
1335 */
1336CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor);
1337
1338/**
1339 * @}
1340 */
1341
1342/**
1343 * \defgroup CINDEX_TYPES Type information for CXCursors
1344 *
1345 * @{
1346 */
1347
1348/**
1349 * \brief Describes the kind of type
1350 */
1351enum CXTypeKind {
1352  /**
1353   * \brief Reprents an invalid type (e.g., where no type is available).
1354   */
1355  CXType_Invalid = 0,
1356
1357  /**
1358   * \brief A type whose specific kind is not exposed via this
1359   * interface.
1360   */
1361  CXType_Unexposed = 1,
1362
1363  /* Builtin types */
1364  CXType_Void = 2,
1365  CXType_Bool = 3,
1366  CXType_Char_U = 4,
1367  CXType_UChar = 5,
1368  CXType_Char16 = 6,
1369  CXType_Char32 = 7,
1370  CXType_UShort = 8,
1371  CXType_UInt = 9,
1372  CXType_ULong = 10,
1373  CXType_ULongLong = 11,
1374  CXType_UInt128 = 12,
1375  CXType_Char_S = 13,
1376  CXType_SChar = 14,
1377  CXType_WChar = 15,
1378  CXType_Short = 16,
1379  CXType_Int = 17,
1380  CXType_Long = 18,
1381  CXType_LongLong = 19,
1382  CXType_Int128 = 20,
1383  CXType_Float = 21,
1384  CXType_Double = 22,
1385  CXType_LongDouble = 23,
1386  CXType_NullPtr = 24,
1387  CXType_Overload = 25,
1388  CXType_Dependent = 26,
1389  CXType_ObjCId = 27,
1390  CXType_ObjCClass = 28,
1391  CXType_ObjCSel = 29,
1392  CXType_FirstBuiltin = CXType_Void,
1393  CXType_LastBuiltin  = CXType_ObjCSel,
1394
1395  CXType_Complex = 100,
1396  CXType_Pointer = 101,
1397  CXType_BlockPointer = 102,
1398  CXType_LValueReference = 103,
1399  CXType_RValueReference = 104,
1400  CXType_Record = 105,
1401  CXType_Enum = 106,
1402  CXType_Typedef = 107,
1403  CXType_ObjCInterface = 108,
1404  CXType_ObjCObjectPointer = 109,
1405  CXType_FunctionNoProto = 110,
1406  CXType_FunctionProto = 111
1407};
1408
1409/**
1410 * \brief The type of an element in the abstract syntax tree.
1411 *
1412 */
1413typedef struct {
1414  enum CXTypeKind kind;
1415  void *data[2];
1416} CXType;
1417
1418/**
1419 * \brief Retrieve the type of a CXCursor (if any).
1420 */
1421CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C);
1422
1423/**
1424 * \determine Determine whether two CXTypes represent the same type.
1425 *
1426 * \returns non-zero if the CXTypes represent the same type and
1427            zero otherwise.
1428 */
1429CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B);
1430
1431/**
1432 * \brief Return the canonical type for a CXType.
1433 *
1434 * Clang's type system explicitly models typedefs and all the ways
1435 * a specific type can be represented.  The canonical type is the underlying
1436 * type with all the "sugar" removed.  For example, if 'T' is a typedef
1437 * for 'int', the canonical type for 'T' would be 'int'.
1438 */
1439CINDEX_LINKAGE CXType clang_getCanonicalType(CXType T);
1440
1441/**
1442 * \brief For pointer types, returns the type of the pointee.
1443 *
1444 */
1445CINDEX_LINKAGE CXType clang_getPointeeType(CXType T);
1446
1447/**
1448 * \brief Return the cursor for the declaration of the given type.
1449 */
1450CINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T);
1451
1452
1453/**
1454 * \brief Retrieve the spelling of a given CXTypeKind.
1455 */
1456CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K);
1457
1458/**
1459 * \brief Retrieve the result type associated with a function type.
1460 */
1461CINDEX_LINKAGE CXType clang_getResultType(CXType T);
1462
1463/**
1464 * \brief Retrieve the result type associated with a given cursor.  This only
1465 *  returns a valid type of the cursor refers to a function or method.
1466 */
1467CINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C);
1468
1469/**
1470 * \brief Return 1 if the CXType is a POD (plain old data) type, and 0
1471 *  otherwise.
1472 */
1473CINDEX_LINKAGE unsigned clang_isPODType(CXType T);
1474
1475/**
1476 * \brief Returns 1 if the base class specified by the cursor with kind
1477 *   CX_CXXBaseSpecifier is virtual.
1478 */
1479CINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor);
1480
1481/**
1482 * \brief Represents the C++ access control level to a base class for a
1483 * cursor with kind CX_CXXBaseSpecifier.
1484 */
1485enum CX_CXXAccessSpecifier {
1486  CX_CXXInvalidAccessSpecifier,
1487  CX_CXXPublic,
1488  CX_CXXProtected,
1489  CX_CXXPrivate
1490};
1491
1492/**
1493 * \brief Returns the access control level for the C++ base specifier
1494 *  represented by a cursor with kind CX_CXXBaseSpecifier.
1495 */
1496CINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor);
1497
1498/**
1499 * @}
1500 */
1501
1502/**
1503 * \defgroup CINDEX_ATTRIBUTES Information for attributes
1504 *
1505 * @{
1506 */
1507
1508
1509/**
1510 * \brief For cursors representing an iboutletcollection attribute,
1511 *  this function returns the collection element type.
1512 *
1513 */
1514CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor);
1515
1516/**
1517 * @}
1518 */
1519
1520/**
1521 * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
1522 *
1523 * These routines provide the ability to traverse the abstract syntax tree
1524 * using cursors.
1525 *
1526 * @{
1527 */
1528
1529/**
1530 * \brief Describes how the traversal of the children of a particular
1531 * cursor should proceed after visiting a particular child cursor.
1532 *
1533 * A value of this enumeration type should be returned by each
1534 * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
1535 */
1536enum CXChildVisitResult {
1537  /**
1538   * \brief Terminates the cursor traversal.
1539   */
1540  CXChildVisit_Break,
1541  /**
1542   * \brief Continues the cursor traversal with the next sibling of
1543   * the cursor just visited, without visiting its children.
1544   */
1545  CXChildVisit_Continue,
1546  /**
1547   * \brief Recursively traverse the children of this cursor, using
1548   * the same visitor and client data.
1549   */
1550  CXChildVisit_Recurse
1551};
1552
1553/**
1554 * \brief Visitor invoked for each cursor found by a traversal.
1555 *
1556 * This visitor function will be invoked for each cursor found by
1557 * clang_visitCursorChildren(). Its first argument is the cursor being
1558 * visited, its second argument is the parent visitor for that cursor,
1559 * and its third argument is the client data provided to
1560 * clang_visitCursorChildren().
1561 *
1562 * The visitor should return one of the \c CXChildVisitResult values
1563 * to direct clang_visitCursorChildren().
1564 */
1565typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor,
1566                                                   CXCursor parent,
1567                                                   CXClientData client_data);
1568
1569/**
1570 * \brief Visit the children of a particular cursor.
1571 *
1572 * This function visits all the direct children of the given cursor,
1573 * invoking the given \p visitor function with the cursors of each
1574 * visited child. The traversal may be recursive, if the visitor returns
1575 * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
1576 * the visitor returns \c CXChildVisit_Break.
1577 *
1578 * \param parent the cursor whose child may be visited. All kinds of
1579 * cursors can be visited, including invalid cursors (which, by
1580 * definition, have no children).
1581 *
1582 * \param visitor the visitor function that will be invoked for each
1583 * child of \p parent.
1584 *
1585 * \param client_data pointer data supplied by the client, which will
1586 * be passed to the visitor each time it is invoked.
1587 *
1588 * \returns a non-zero value if the traversal was terminated
1589 * prematurely by the visitor returning \c CXChildVisit_Break.
1590 */
1591CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent,
1592                                            CXCursorVisitor visitor,
1593                                            CXClientData client_data);
1594
1595/**
1596 * @}
1597 */
1598
1599/**
1600 * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
1601 *
1602 * These routines provide the ability to determine references within and
1603 * across translation units, by providing the names of the entities referenced
1604 * by cursors, follow reference cursors to the declarations they reference,
1605 * and associate declarations with their definitions.
1606 *
1607 * @{
1608 */
1609
1610/**
1611 * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced
1612 * by the given cursor.
1613 *
1614 * A Unified Symbol Resolution (USR) is a string that identifies a particular
1615 * entity (function, class, variable, etc.) within a program. USRs can be
1616 * compared across translation units to determine, e.g., when references in
1617 * one translation refer to an entity defined in another translation unit.
1618 */
1619CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor);
1620
1621/**
1622 * \brief Construct a USR for a specified Objective-C class.
1623 */
1624CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name);
1625
1626/**
1627 * \brief Construct a USR for a specified Objective-C category.
1628 */
1629CINDEX_LINKAGE CXString
1630  clang_constructUSR_ObjCCategory(const char *class_name,
1631                                 const char *category_name);
1632
1633/**
1634 * \brief Construct a USR for a specified Objective-C protocol.
1635 */
1636CINDEX_LINKAGE CXString
1637  clang_constructUSR_ObjCProtocol(const char *protocol_name);
1638
1639
1640/**
1641 * \brief Construct a USR for a specified Objective-C instance variable and
1642 *   the USR for its containing class.
1643 */
1644CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name,
1645                                                    CXString classUSR);
1646
1647/**
1648 * \brief Construct a USR for a specified Objective-C method and
1649 *   the USR for its containing class.
1650 */
1651CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name,
1652                                                      unsigned isInstanceMethod,
1653                                                      CXString classUSR);
1654
1655/**
1656 * \brief Construct a USR for a specified Objective-C property and the USR
1657 *  for its containing class.
1658 */
1659CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property,
1660                                                        CXString classUSR);
1661
1662/**
1663 * \brief Retrieve a name for the entity referenced by this cursor.
1664 */
1665CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
1666
1667/** \brief For a cursor that is a reference, retrieve a cursor representing the
1668 * entity that it references.
1669 *
1670 * Reference cursors refer to other entities in the AST. For example, an
1671 * Objective-C superclass reference cursor refers to an Objective-C class.
1672 * This function produces the cursor for the Objective-C class from the
1673 * cursor for the superclass reference. If the input cursor is a declaration or
1674 * definition, it returns that declaration or definition unchanged.
1675 * Otherwise, returns the NULL cursor.
1676 */
1677CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor);
1678
1679/**
1680 *  \brief For a cursor that is either a reference to or a declaration
1681 *  of some entity, retrieve a cursor that describes the definition of
1682 *  that entity.
1683 *
1684 *  Some entities can be declared multiple times within a translation
1685 *  unit, but only one of those declarations can also be a
1686 *  definition. For example, given:
1687 *
1688 *  \code
1689 *  int f(int, int);
1690 *  int g(int x, int y) { return f(x, y); }
1691 *  int f(int a, int b) { return a + b; }
1692 *  int f(int, int);
1693 *  \endcode
1694 *
1695 *  there are three declarations of the function "f", but only the
1696 *  second one is a definition. The clang_getCursorDefinition()
1697 *  function will take any cursor pointing to a declaration of "f"
1698 *  (the first or fourth lines of the example) or a cursor referenced
1699 *  that uses "f" (the call to "f' inside "g") and will return a
1700 *  declaration cursor pointing to the definition (the second "f"
1701 *  declaration).
1702 *
1703 *  If given a cursor for which there is no corresponding definition,
1704 *  e.g., because there is no definition of that entity within this
1705 *  translation unit, returns a NULL cursor.
1706 */
1707CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor);
1708
1709/**
1710 * \brief Determine whether the declaration pointed to by this cursor
1711 * is also a definition of that entity.
1712 */
1713CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor);
1714
1715/**
1716 * @}
1717 */
1718
1719/**
1720 * \defgroup CINDEX_CPP C++ AST introspection
1721 *
1722 * The routines in this group provide access information in the ASTs specific
1723 * to C++ language features.
1724 *
1725 * @{
1726 */
1727
1728/**
1729 * \brief Determine if a C++ member function or member function template is
1730 * declared 'static'.
1731 */
1732CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C);
1733
1734/**
1735 * \brief Given a cursor that represents a template, determine
1736 * the cursor kind of the specializations would be generated by instantiating
1737 * the template.
1738 *
1739 * This routine can be used to determine what flavor of function template,
1740 * class template, or class template partial specialization is stored in the
1741 * cursor. For example, it can describe whether a class template cursor is
1742 * declared with "struct", "class" or "union".
1743 *
1744 * \param C The cursor to query. This cursor should represent a template
1745 * declaration.
1746 *
1747 * \returns The cursor kind of the specializations that would be generated
1748 * by instantiating the template \p C. If \p C is not a template, returns
1749 * \c CXCursor_NoDeclFound.
1750 */
1751CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C);
1752
1753/**
1754 * \brief Given a cursor that may represent a specialization or instantiation
1755 * of a template, retrieve the cursor that represents the template that it
1756 * specializes or from which it was instantiated.
1757 *
1758 * This routine determines the template involved both for explicit
1759 * specializations of templates and for implicit instantiations of the template,
1760 * both of which are referred to as "specializations". For a class template
1761 * specialization (e.g., \c std::vector<bool>), this routine will return
1762 * either the primary template (\c std::vector) or, if the specialization was
1763 * instantiated from a class template partial specialization, the class template
1764 * partial specialization. For a class template partial specialization and a
1765 * function template specialization (including instantiations), this
1766 * this routine will return the specialized template.
1767 *
1768 * For members of a class template (e.g., member functions, member classes, or
1769 * static data members), returns the specialized or instantiated member.
1770 * Although not strictly "templates" in the C++ language, members of class
1771 * templates have the same notions of specializations and instantiations that
1772 * templates do, so this routine treats them similarly.
1773 *
1774 * \param C A cursor that may be a specialization of a template or a member
1775 * of a template.
1776 *
1777 * \returns If the given cursor is a specialization or instantiation of a
1778 * template or a member thereof, the template or member that it specializes or
1779 * from which it was instantiated. Otherwise, returns a NULL cursor.
1780 */
1781CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C);
1782
1783/**
1784 * @}
1785 */
1786
1787/**
1788 * \defgroup CINDEX_LEX Token extraction and manipulation
1789 *
1790 * The routines in this group provide access to the tokens within a
1791 * translation unit, along with a semantic mapping of those tokens to
1792 * their corresponding cursors.
1793 *
1794 * @{
1795 */
1796
1797/**
1798 * \brief Describes a kind of token.
1799 */
1800typedef enum CXTokenKind {
1801  /**
1802   * \brief A token that contains some kind of punctuation.
1803   */
1804  CXToken_Punctuation,
1805
1806  /**
1807   * \brief A language keyword.
1808   */
1809  CXToken_Keyword,
1810
1811  /**
1812   * \brief An identifier (that is not a keyword).
1813   */
1814  CXToken_Identifier,
1815
1816  /**
1817   * \brief A numeric, string, or character literal.
1818   */
1819  CXToken_Literal,
1820
1821  /**
1822   * \brief A comment.
1823   */
1824  CXToken_Comment
1825} CXTokenKind;
1826
1827/**
1828 * \brief Describes a single preprocessing token.
1829 */
1830typedef struct {
1831  unsigned int_data[4];
1832  void *ptr_data;
1833} CXToken;
1834
1835/**
1836 * \brief Determine the kind of the given token.
1837 */
1838CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken);
1839
1840/**
1841 * \brief Determine the spelling of the given token.
1842 *
1843 * The spelling of a token is the textual representation of that token, e.g.,
1844 * the text of an identifier or keyword.
1845 */
1846CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken);
1847
1848/**
1849 * \brief Retrieve the source location of the given token.
1850 */
1851CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit,
1852                                                       CXToken);
1853
1854/**
1855 * \brief Retrieve a source range that covers the given token.
1856 */
1857CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken);
1858
1859/**
1860 * \brief Tokenize the source code described by the given range into raw
1861 * lexical tokens.
1862 *
1863 * \param TU the translation unit whose text is being tokenized.
1864 *
1865 * \param Range the source range in which text should be tokenized. All of the
1866 * tokens produced by tokenization will fall within this source range,
1867 *
1868 * \param Tokens this pointer will be set to point to the array of tokens
1869 * that occur within the given source range. The returned pointer must be
1870 * freed with clang_disposeTokens() before the translation unit is destroyed.
1871 *
1872 * \param NumTokens will be set to the number of tokens in the \c *Tokens
1873 * array.
1874 *
1875 */
1876CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range,
1877                                   CXToken **Tokens, unsigned *NumTokens);
1878
1879/**
1880 * \brief Annotate the given set of tokens by providing cursors for each token
1881 * that can be mapped to a specific entity within the abstract syntax tree.
1882 *
1883 * This token-annotation routine is equivalent to invoking
1884 * clang_getCursor() for the source locations of each of the
1885 * tokens. The cursors provided are filtered, so that only those
1886 * cursors that have a direct correspondence to the token are
1887 * accepted. For example, given a function call \c f(x),
1888 * clang_getCursor() would provide the following cursors:
1889 *
1890 *   * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
1891 *   * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
1892 *   * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
1893 *
1894 * Only the first and last of these cursors will occur within the
1895 * annotate, since the tokens "f" and "x' directly refer to a function
1896 * and a variable, respectively, but the parentheses are just a small
1897 * part of the full syntax of the function call expression, which is
1898 * not provided as an annotation.
1899 *
1900 * \param TU the translation unit that owns the given tokens.
1901 *
1902 * \param Tokens the set of tokens to annotate.
1903 *
1904 * \param NumTokens the number of tokens in \p Tokens.
1905 *
1906 * \param Cursors an array of \p NumTokens cursors, whose contents will be
1907 * replaced with the cursors corresponding to each token.
1908 */
1909CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU,
1910                                         CXToken *Tokens, unsigned NumTokens,
1911                                         CXCursor *Cursors);
1912
1913/**
1914 * \brief Free the given set of tokens.
1915 */
1916CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU,
1917                                        CXToken *Tokens, unsigned NumTokens);
1918
1919/**
1920 * @}
1921 */
1922
1923/**
1924 * \defgroup CINDEX_DEBUG Debugging facilities
1925 *
1926 * These routines are used for testing and debugging, only, and should not
1927 * be relied upon.
1928 *
1929 * @{
1930 */
1931
1932/* for debug/testing */
1933CINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind);
1934CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor,
1935                                          const char **startBuf,
1936                                          const char **endBuf,
1937                                          unsigned *startLine,
1938                                          unsigned *startColumn,
1939                                          unsigned *endLine,
1940                                          unsigned *endColumn);
1941CINDEX_LINKAGE void clang_enableStackTraces(void);
1942/**
1943 * @}
1944 */
1945
1946/**
1947 * \defgroup CINDEX_CODE_COMPLET Code completion
1948 *
1949 * Code completion involves taking an (incomplete) source file, along with
1950 * knowledge of where the user is actively editing that file, and suggesting
1951 * syntactically- and semantically-valid constructs that the user might want to
1952 * use at that particular point in the source code. These data structures and
1953 * routines provide support for code completion.
1954 *
1955 * @{
1956 */
1957
1958/**
1959 * \brief A semantic string that describes a code-completion result.
1960 *
1961 * A semantic string that describes the formatting of a code-completion
1962 * result as a single "template" of text that should be inserted into the
1963 * source buffer when a particular code-completion result is selected.
1964 * Each semantic string is made up of some number of "chunks", each of which
1965 * contains some text along with a description of what that text means, e.g.,
1966 * the name of the entity being referenced, whether the text chunk is part of
1967 * the template, or whether it is a "placeholder" that the user should replace
1968 * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
1969 * description of the different kinds of chunks.
1970 */
1971typedef void *CXCompletionString;
1972
1973/**
1974 * \brief A single result of code completion.
1975 */
1976typedef struct {
1977  /**
1978   * \brief The kind of entity that this completion refers to.
1979   *
1980   * The cursor kind will be a macro, keyword, or a declaration (one of the
1981   * *Decl cursor kinds), describing the entity that the completion is
1982   * referring to.
1983   *
1984   * \todo In the future, we would like to provide a full cursor, to allow
1985   * the client to extract additional information from declaration.
1986   */
1987  enum CXCursorKind CursorKind;
1988
1989  /**
1990   * \brief The code-completion string that describes how to insert this
1991   * code-completion result into the editing buffer.
1992   */
1993  CXCompletionString CompletionString;
1994} CXCompletionResult;
1995
1996/**
1997 * \brief Describes a single piece of text within a code-completion string.
1998 *
1999 * Each "chunk" within a code-completion string (\c CXCompletionString) is
2000 * either a piece of text with a specific "kind" that describes how that text
2001 * should be interpreted by the client or is another completion string.
2002 */
2003enum CXCompletionChunkKind {
2004  /**
2005   * \brief A code-completion string that describes "optional" text that
2006   * could be a part of the template (but is not required).
2007   *
2008   * The Optional chunk is the only kind of chunk that has a code-completion
2009   * string for its representation, which is accessible via
2010   * \c clang_getCompletionChunkCompletionString(). The code-completion string
2011   * describes an additional part of the template that is completely optional.
2012   * For example, optional chunks can be used to describe the placeholders for
2013   * arguments that match up with defaulted function parameters, e.g. given:
2014   *
2015   * \code
2016   * void f(int x, float y = 3.14, double z = 2.71828);
2017   * \endcode
2018   *
2019   * The code-completion string for this function would contain:
2020   *   - a TypedText chunk for "f".
2021   *   - a LeftParen chunk for "(".
2022   *   - a Placeholder chunk for "int x"
2023   *   - an Optional chunk containing the remaining defaulted arguments, e.g.,
2024   *       - a Comma chunk for ","
2025   *       - a Placeholder chunk for "float y"
2026   *       - an Optional chunk containing the last defaulted argument:
2027   *           - a Comma chunk for ","
2028   *           - a Placeholder chunk for "double z"
2029   *   - a RightParen chunk for ")"
2030   *
2031   * There are many ways to handle Optional chunks. Two simple approaches are:
2032   *   - Completely ignore optional chunks, in which case the template for the
2033   *     function "f" would only include the first parameter ("int x").
2034   *   - Fully expand all optional chunks, in which case the template for the
2035   *     function "f" would have all of the parameters.
2036   */
2037  CXCompletionChunk_Optional,
2038  /**
2039   * \brief Text that a user would be expected to type to get this
2040   * code-completion result.
2041   *
2042   * There will be exactly one "typed text" chunk in a semantic string, which
2043   * will typically provide the spelling of a keyword or the name of a
2044   * declaration that could be used at the current code point. Clients are
2045   * expected to filter the code-completion results based on the text in this
2046   * chunk.
2047   */
2048  CXCompletionChunk_TypedText,
2049  /**
2050   * \brief Text that should be inserted as part of a code-completion result.
2051   *
2052   * A "text" chunk represents text that is part of the template to be
2053   * inserted into user code should this particular code-completion result
2054   * be selected.
2055   */
2056  CXCompletionChunk_Text,
2057  /**
2058   * \brief Placeholder text that should be replaced by the user.
2059   *
2060   * A "placeholder" chunk marks a place where the user should insert text
2061   * into the code-completion template. For example, placeholders might mark
2062   * the function parameters for a function declaration, to indicate that the
2063   * user should provide arguments for each of those parameters. The actual
2064   * text in a placeholder is a suggestion for the text to display before
2065   * the user replaces the placeholder with real code.
2066   */
2067  CXCompletionChunk_Placeholder,
2068  /**
2069   * \brief Informative text that should be displayed but never inserted as
2070   * part of the template.
2071   *
2072   * An "informative" chunk contains annotations that can be displayed to
2073   * help the user decide whether a particular code-completion result is the
2074   * right option, but which is not part of the actual template to be inserted
2075   * by code completion.
2076   */
2077  CXCompletionChunk_Informative,
2078  /**
2079   * \brief Text that describes the current parameter when code-completion is
2080   * referring to function call, message send, or template specialization.
2081   *
2082   * A "current parameter" chunk occurs when code-completion is providing
2083   * information about a parameter corresponding to the argument at the
2084   * code-completion point. For example, given a function
2085   *
2086   * \code
2087   * int add(int x, int y);
2088   * \endcode
2089   *
2090   * and the source code \c add(, where the code-completion point is after the
2091   * "(", the code-completion string will contain a "current parameter" chunk
2092   * for "int x", indicating that the current argument will initialize that
2093   * parameter. After typing further, to \c add(17, (where the code-completion
2094   * point is after the ","), the code-completion string will contain a
2095   * "current paremeter" chunk to "int y".
2096   */
2097  CXCompletionChunk_CurrentParameter,
2098  /**
2099   * \brief A left parenthesis ('('), used to initiate a function call or
2100   * signal the beginning of a function parameter list.
2101   */
2102  CXCompletionChunk_LeftParen,
2103  /**
2104   * \brief A right parenthesis (')'), used to finish a function call or
2105   * signal the end of a function parameter list.
2106   */
2107  CXCompletionChunk_RightParen,
2108  /**
2109   * \brief A left bracket ('[').
2110   */
2111  CXCompletionChunk_LeftBracket,
2112  /**
2113   * \brief A right bracket (']').
2114   */
2115  CXCompletionChunk_RightBracket,
2116  /**
2117   * \brief A left brace ('{').
2118   */
2119  CXCompletionChunk_LeftBrace,
2120  /**
2121   * \brief A right brace ('}').
2122   */
2123  CXCompletionChunk_RightBrace,
2124  /**
2125   * \brief A left angle bracket ('<').
2126   */
2127  CXCompletionChunk_LeftAngle,
2128  /**
2129   * \brief A right angle bracket ('>').
2130   */
2131  CXCompletionChunk_RightAngle,
2132  /**
2133   * \brief A comma separator (',').
2134   */
2135  CXCompletionChunk_Comma,
2136  /**
2137   * \brief Text that specifies the result type of a given result.
2138   *
2139   * This special kind of informative chunk is not meant to be inserted into
2140   * the text buffer. Rather, it is meant to illustrate the type that an
2141   * expression using the given completion string would have.
2142   */
2143  CXCompletionChunk_ResultType,
2144  /**
2145   * \brief A colon (':').
2146   */
2147  CXCompletionChunk_Colon,
2148  /**
2149   * \brief A semicolon (';').
2150   */
2151  CXCompletionChunk_SemiColon,
2152  /**
2153   * \brief An '=' sign.
2154   */
2155  CXCompletionChunk_Equal,
2156  /**
2157   * Horizontal space (' ').
2158   */
2159  CXCompletionChunk_HorizontalSpace,
2160  /**
2161   * Vertical space ('\n'), after which it is generally a good idea to
2162   * perform indentation.
2163   */
2164  CXCompletionChunk_VerticalSpace
2165};
2166
2167/**
2168 * \brief Determine the kind of a particular chunk within a completion string.
2169 *
2170 * \param completion_string the completion string to query.
2171 *
2172 * \param chunk_number the 0-based index of the chunk in the completion string.
2173 *
2174 * \returns the kind of the chunk at the index \c chunk_number.
2175 */
2176CINDEX_LINKAGE enum CXCompletionChunkKind
2177clang_getCompletionChunkKind(CXCompletionString completion_string,
2178                             unsigned chunk_number);
2179
2180/**
2181 * \brief Retrieve the text associated with a particular chunk within a
2182 * completion string.
2183 *
2184 * \param completion_string the completion string to query.
2185 *
2186 * \param chunk_number the 0-based index of the chunk in the completion string.
2187 *
2188 * \returns the text associated with the chunk at index \c chunk_number.
2189 */
2190CINDEX_LINKAGE CXString
2191clang_getCompletionChunkText(CXCompletionString completion_string,
2192                             unsigned chunk_number);
2193
2194/**
2195 * \brief Retrieve the completion string associated with a particular chunk
2196 * within a completion string.
2197 *
2198 * \param completion_string the completion string to query.
2199 *
2200 * \param chunk_number the 0-based index of the chunk in the completion string.
2201 *
2202 * \returns the completion string associated with the chunk at index
2203 * \c chunk_number, or NULL if that chunk is not represented by a completion
2204 * string.
2205 */
2206CINDEX_LINKAGE CXCompletionString
2207clang_getCompletionChunkCompletionString(CXCompletionString completion_string,
2208                                         unsigned chunk_number);
2209
2210/**
2211 * \brief Retrieve the number of chunks in the given code-completion string.
2212 */
2213CINDEX_LINKAGE unsigned
2214clang_getNumCompletionChunks(CXCompletionString completion_string);
2215
2216/**
2217 * \brief Determine the priority of this code completion.
2218 *
2219 * The priority of a code completion indicates how likely it is that this
2220 * particular completion is the completion that the user will select. The
2221 * priority is selected by various internal heuristics.
2222 *
2223 * \param completion_string The completion string to query.
2224 *
2225 * \returns The priority of this completion string. Smaller values indicate
2226 * higher-priority (more likely) completions.
2227 */
2228CINDEX_LINKAGE unsigned
2229clang_getCompletionPriority(CXCompletionString completion_string);
2230
2231/**
2232 * \brief Determine the availability of the entity that this code-completion
2233 * string refers to.
2234 *
2235 * \param completion_string The completion string to query.
2236 *
2237 * \returns The availability of the completion string.
2238 */
2239CINDEX_LINKAGE enum CXAvailabilityKind
2240clang_getCompletionAvailability(CXCompletionString completion_string);
2241
2242/**
2243 * \brief Contains the results of code-completion.
2244 *
2245 * This data structure contains the results of code completion, as
2246 * produced by \c clang_codeComplete. Its contents must be freed by
2247 * \c clang_disposeCodeCompleteResults.
2248 */
2249typedef struct {
2250  /**
2251   * \brief The code-completion results.
2252   */
2253  CXCompletionResult *Results;
2254
2255  /**
2256   * \brief The number of code-completion results stored in the
2257   * \c Results array.
2258   */
2259  unsigned NumResults;
2260} CXCodeCompleteResults;
2261
2262/**
2263 * \brief Perform code completion at a given location in a source file.
2264 *
2265 * This function performs code completion at a particular file, line, and
2266 * column within source code, providing results that suggest potential
2267 * code snippets based on the context of the completion. The basic model
2268 * for code completion is that Clang will parse a complete source file,
2269 * performing syntax checking up to the location where code-completion has
2270 * been requested. At that point, a special code-completion token is passed
2271 * to the parser, which recognizes this token and determines, based on the
2272 * current location in the C/Objective-C/C++ grammar and the state of
2273 * semantic analysis, what completions to provide. These completions are
2274 * returned via a new \c CXCodeCompleteResults structure.
2275 *
2276 * Code completion itself is meant to be triggered by the client when the
2277 * user types punctuation characters or whitespace, at which point the
2278 * code-completion location will coincide with the cursor. For example, if \c p
2279 * is a pointer, code-completion might be triggered after the "-" and then
2280 * after the ">" in \c p->. When the code-completion location is afer the ">",
2281 * the completion results will provide, e.g., the members of the struct that
2282 * "p" points to. The client is responsible for placing the cursor at the
2283 * beginning of the token currently being typed, then filtering the results
2284 * based on the contents of the token. For example, when code-completing for
2285 * the expression \c p->get, the client should provide the location just after
2286 * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
2287 * client can filter the results based on the current token text ("get"), only
2288 * showing those results that start with "get". The intent of this interface
2289 * is to separate the relatively high-latency acquisition of code-completion
2290 * results from the filtering of results on a per-character basis, which must
2291 * have a lower latency.
2292 *
2293 * \param CIdx the \c CXIndex instance that will be used to perform code
2294 * completion.
2295 *
2296 * \param source_filename the name of the source file that should be parsed to
2297 * perform code-completion. This source file must be the same as or include the
2298 * filename described by \p complete_filename, or no code-completion results
2299 * will be produced.  NOTE: One can also specify NULL for this argument if the
2300 * source file is included in command_line_args.
2301 *
2302 * \param num_command_line_args the number of command-line arguments stored in
2303 * \p command_line_args.
2304 *
2305 * \param command_line_args the command-line arguments to pass to the Clang
2306 * compiler to build the given source file. This should include all of the
2307 * necessary include paths, language-dialect switches, precompiled header
2308 * includes, etc., but should not include any information specific to
2309 * code completion.
2310 *
2311 * \param num_unsaved_files the number of unsaved file entries in \p
2312 * unsaved_files.
2313 *
2314 * \param unsaved_files the files that have not yet been saved to disk
2315 * but may be required for code completion, including the contents of
2316 * those files.  The contents and name of these files (as specified by
2317 * CXUnsavedFile) are copied when necessary, so the client only needs to
2318 * guarantee their validity until the call to this function returns.
2319 *
2320 * \param complete_filename the name of the source file where code completion
2321 * should be performed. In many cases, this name will be the same as the
2322 * source filename. However, the completion filename may also be a file
2323 * included by the source file, which is required when producing
2324 * code-completion results for a header.
2325 *
2326 * \param complete_line the line at which code-completion should occur.
2327 *
2328 * \param complete_column the column at which code-completion should occur.
2329 * Note that the column should point just after the syntactic construct that
2330 * initiated code completion, and not in the middle of a lexical token.
2331 *
2332 * \param diag_callback callback function that will receive any diagnostics
2333 * emitted while processing this source file. If NULL, diagnostics will be
2334 * suppressed.
2335 *
2336 * \param diag_client_data client data that will be passed to the diagnostic
2337 * callback function.
2338 *
2339 * \returns if successful, a new CXCodeCompleteResults structure
2340 * containing code-completion results, which should eventually be
2341 * freed with \c clang_disposeCodeCompleteResults(). If code
2342 * completion fails, returns NULL.
2343 */
2344CINDEX_LINKAGE
2345CXCodeCompleteResults *clang_codeComplete(CXIndex CIdx,
2346                                          const char *source_filename,
2347                                          int num_command_line_args,
2348                                          const char * const *command_line_args,
2349                                          unsigned num_unsaved_files,
2350                                          struct CXUnsavedFile *unsaved_files,
2351                                          const char *complete_filename,
2352                                          unsigned complete_line,
2353                                          unsigned complete_column);
2354
2355/**
2356 * \brief Flags that can be passed to \c clang_codeCompleteAt() to
2357 * modify its behavior.
2358 *
2359 * The enumerators in this enumeration can be bitwise-OR'd together to
2360 * provide multiple options to \c clang_codeCompleteAt().
2361 */
2362enum CXCodeComplete_Flags {
2363  /**
2364   * \brief Whether to include macros within the set of code
2365   * completions returned.
2366   */
2367  CXCodeComplete_IncludeMacros = 0x01,
2368
2369  /**
2370   * \brief Whether to include code patterns for language constructs
2371   * within the set of code completions, e.g., for loops.
2372   */
2373  CXCodeComplete_IncludeCodePatterns = 0x02
2374};
2375
2376/**
2377 * \brief Returns a default set of code-completion options that can be
2378 * passed to\c clang_codeCompleteAt().
2379 */
2380CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void);
2381
2382/**
2383 * \brief Perform code completion at a given location in a translation unit.
2384 *
2385 * This function performs code completion at a particular file, line, and
2386 * column within source code, providing results that suggest potential
2387 * code snippets based on the context of the completion. The basic model
2388 * for code completion is that Clang will parse a complete source file,
2389 * performing syntax checking up to the location where code-completion has
2390 * been requested. At that point, a special code-completion token is passed
2391 * to the parser, which recognizes this token and determines, based on the
2392 * current location in the C/Objective-C/C++ grammar and the state of
2393 * semantic analysis, what completions to provide. These completions are
2394 * returned via a new \c CXCodeCompleteResults structure.
2395 *
2396 * Code completion itself is meant to be triggered by the client when the
2397 * user types punctuation characters or whitespace, at which point the
2398 * code-completion location will coincide with the cursor. For example, if \c p
2399 * is a pointer, code-completion might be triggered after the "-" and then
2400 * after the ">" in \c p->. When the code-completion location is afer the ">",
2401 * the completion results will provide, e.g., the members of the struct that
2402 * "p" points to. The client is responsible for placing the cursor at the
2403 * beginning of the token currently being typed, then filtering the results
2404 * based on the contents of the token. For example, when code-completing for
2405 * the expression \c p->get, the client should provide the location just after
2406 * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
2407 * client can filter the results based on the current token text ("get"), only
2408 * showing those results that start with "get". The intent of this interface
2409 * is to separate the relatively high-latency acquisition of code-completion
2410 * results from the filtering of results on a per-character basis, which must
2411 * have a lower latency.
2412 *
2413 * \param TU The translation unit in which code-completion should
2414 * occur. The source files for this translation unit need not be
2415 * completely up-to-date (and the contents of those source files may
2416 * be overridden via \p unsaved_files). Cursors referring into the
2417 * translation unit may be invalidated by this invocation.
2418 *
2419 * \param complete_filename The name of the source file where code
2420 * completion should be performed. This filename may be any file
2421 * included in the translation unit.
2422 *
2423 * \param complete_line The line at which code-completion should occur.
2424 *
2425 * \param complete_column The column at which code-completion should occur.
2426 * Note that the column should point just after the syntactic construct that
2427 * initiated code completion, and not in the middle of a lexical token.
2428 *
2429 * \param unsaved_files the Tiles that have not yet been saved to disk
2430 * but may be required for parsing or code completion, including the
2431 * contents of those files.  The contents and name of these files (as
2432 * specified by CXUnsavedFile) are copied when necessary, so the
2433 * client only needs to guarantee their validity until the call to
2434 * this function returns.
2435 *
2436 * \param num_unsaved_files The number of unsaved file entries in \p
2437 * unsaved_files.
2438 *
2439 * \param options Extra options that control the behavior of code
2440 * completion, expressed as a bitwise OR of the enumerators of the
2441 * CXCodeComplete_Flags enumeration. The
2442 * \c clang_defaultCodeCompleteOptions() function returns a default set
2443 * of code-completion options.
2444 *
2445 * \returns If successful, a new \c CXCodeCompleteResults structure
2446 * containing code-completion results, which should eventually be
2447 * freed with \c clang_disposeCodeCompleteResults(). If code
2448 * completion fails, returns NULL.
2449 */
2450CINDEX_LINKAGE
2451CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU,
2452                                            const char *complete_filename,
2453                                            unsigned complete_line,
2454                                            unsigned complete_column,
2455                                            struct CXUnsavedFile *unsaved_files,
2456                                            unsigned num_unsaved_files,
2457                                            unsigned options);
2458
2459/**
2460 * \brief Sort the code-completion results in case-insensitive alphabetical
2461 * order.
2462 *
2463 * \param Results The set of results to sort.
2464 * \param NumResults The number of results in \p Results.
2465 */
2466CINDEX_LINKAGE
2467void clang_sortCodeCompletionResults(CXCompletionResult *Results,
2468                                     unsigned NumResults);
2469
2470/**
2471 * \brief Free the given set of code-completion results.
2472 */
2473CINDEX_LINKAGE
2474void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results);
2475
2476/**
2477 * \brief Determine the number of diagnostics produced prior to the
2478 * location where code completion was performed.
2479 */
2480CINDEX_LINKAGE
2481unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results);
2482
2483/**
2484 * \brief Retrieve a diagnostic associated with the given code completion.
2485 *
2486 * \param Result the code completion results to query.
2487 * \param Index the zero-based diagnostic number to retrieve.
2488 *
2489 * \returns the requested diagnostic. This diagnostic must be freed
2490 * via a call to \c clang_disposeDiagnostic().
2491 */
2492CINDEX_LINKAGE
2493CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results,
2494                                             unsigned Index);
2495
2496/**
2497 * @}
2498 */
2499
2500
2501/**
2502 * \defgroup CINDEX_MISC Miscellaneous utility functions
2503 *
2504 * @{
2505 */
2506
2507/**
2508 * \brief Return a version string, suitable for showing to a user, but not
2509 *        intended to be parsed (the format is not guaranteed to be stable).
2510 */
2511CINDEX_LINKAGE CXString clang_getClangVersion();
2512
2513/**
2514 * \brief Return a version string, suitable for showing to a user, but not
2515 *        intended to be parsed (the format is not guaranteed to be stable).
2516 */
2517
2518
2519 /**
2520  * \brief Visitor invoked for each file in a translation unit
2521  *        (used with clang_getInclusions()).
2522  *
2523  * This visitor function will be invoked by clang_getInclusions() for each
2524  * file included (either at the top-level or by #include directives) within
2525  * a translation unit.  The first argument is the file being included, and
2526  * the second and third arguments provide the inclusion stack.  The
2527  * array is sorted in order of immediate inclusion.  For example,
2528  * the first element refers to the location that included 'included_file'.
2529  */
2530typedef void (*CXInclusionVisitor)(CXFile included_file,
2531                                   CXSourceLocation* inclusion_stack,
2532                                   unsigned include_len,
2533                                   CXClientData client_data);
2534
2535/**
2536 * \brief Visit the set of preprocessor inclusions in a translation unit.
2537 *   The visitor function is called with the provided data for every included
2538 *   file.  This does not include headers included by the PCH file (unless one
2539 *   is inspecting the inclusions in the PCH file itself).
2540 */
2541CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu,
2542                                        CXInclusionVisitor visitor,
2543                                        CXClientData client_data);
2544
2545/**
2546 * @}
2547 */
2548
2549/**
2550 * @}
2551 */
2552
2553#ifdef __cplusplus
2554}
2555#endif
2556#endif
2557
2558