1 /*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
3 |* The LLVM Compiler Infrastructure *|
5 |* This file is distributed under the University of Illinois Open Source *|
6 |* License. See LICENSE.TXT for details. *|
8 |*===----------------------------------------------------------------------===*|
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 *|
14 \*===----------------------------------------------------------------------===*/
16 #ifndef CLANG_C_INDEX_H
17 #define CLANG_C_INDEX_H
27 /* MSVC DLL import/export. */
30 #define CINDEX_LINKAGE __declspec(dllexport)
32 #define CINDEX_LINKAGE __declspec(dllimport)
35 #define CINDEX_LINKAGE
38 /** \defgroup CINDEX libclang: C Interface to Clang
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.
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.
51 * To avoid namespace pollution, data types are prefixed with "CX" and
52 * functions are prefixed with "clang_".
58 * \brief An "index" that consists of a set of translation units that would
59 * typically be linked together into an executable or library.
61 typedef void *CXIndex;
64 * \brief A single translation unit, which resides in an index.
66 typedef struct CXTranslationUnitImpl *CXTranslationUnit;
69 * \brief Opaque pointer representing client data that will be passed through
70 * to various callbacks and visitors.
72 typedef void *CXClientData;
75 * \brief Provides the contents of a file that has not yet been saved to disk.
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.
81 struct CXUnsavedFile {
83 * \brief The file whose contents have not yet been saved.
85 * This file must already exist in the file system.
90 * \brief A buffer containing the unsaved contents of this file.
95 * \brief The length of the unsaved contents of this buffer.
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.
105 enum CXAvailabilityKind {
107 * \brief The entity is available.
109 CXAvailability_Available,
111 * \brief The entity is available, but has been deprecated (and its use is
114 CXAvailability_Deprecated,
116 * \brief The entity is not available; any use of it will be an error.
118 CXAvailability_NotAvailable
122 * \defgroup CINDEX_STRING String manipulation routines
128 * \brief A character string.
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.
137 unsigned private_flags;
141 * \brief Retrieve the character data associated with the given string.
143 CINDEX_LINKAGE const char *clang_getCString(CXString string);
146 * \brief Free the given string,
148 CINDEX_LINKAGE void clang_disposeString(CXString string);
155 * \brief clang_createIndex() provides a shared context for creating
156 * translation units. It provides two options:
158 * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
159 * declarations (when loading any new translation units). A "local" declaration
160 * is one that belongs in the translation unit itself and not in a precompiled
161 * header that was used by the translation unit. If zero, all declarations
162 * will be enumerated.
164 * Here is an example:
166 * // excludeDeclsFromPCH = 1, displayDiagnostics=1
167 * Idx = clang_createIndex(1, 1);
169 * // IndexTest.pch was produced with the following command:
170 * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
171 * TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
173 * // This will load all the symbols from 'IndexTest.pch'
174 * clang_visitChildren(clang_getTranslationUnitCursor(TU),
175 * TranslationUnitVisitor, 0);
176 * clang_disposeTranslationUnit(TU);
178 * // This will load all the symbols from 'IndexTest.c', excluding symbols
179 * // from 'IndexTest.pch'.
180 * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
181 * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
183 * clang_visitChildren(clang_getTranslationUnitCursor(TU),
184 * TranslationUnitVisitor, 0);
185 * clang_disposeTranslationUnit(TU);
187 * This process of creating the 'pch', loading it separately, and using it (via
188 * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
189 * (which gives the indexer the same performance benefit as the compiler).
191 CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
192 int displayDiagnostics);
195 * \brief Destroy the given index.
197 * The index must not be destroyed until all of the translation units created
198 * within that index have been destroyed.
200 CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
203 * \defgroup CINDEX_FILES File manipulation routines
209 * \brief A particular source file that is part of a translation unit.
211 typedef void *CXFile;
215 * \brief Retrieve the complete file and path name of the given file.
217 CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile);
220 * \brief Retrieve the last modification time of the given file.
222 CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
225 * \brief Retrieve a file handle within the given translation unit.
227 * \param tu the translation unit
229 * \param file_name the name of the file.
231 * \returns the file handle for the named file in the translation unit \p tu,
232 * or a NULL file handle if the file was not a part of this translation unit.
234 CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu,
235 const char *file_name);
242 * \defgroup CINDEX_LOCATIONS Physical source locations
244 * Clang represents physical source locations in its abstract syntax tree in
245 * great detail, with file, line, and column information for the majority of
246 * the tokens parsed in the source code. These data types and functions are
247 * used to represent source location information, either for a particular
248 * point in the program or for a range of points in the program, and extract
249 * specific location information from those data types.
255 * \brief Identifies a specific source location within a translation
258 * Use clang_getInstantiationLocation() or clang_getSpellingLocation()
259 * to map a source location to a particular file, line, and column.
267 * \brief Identifies a half-open character range in the source code.
269 * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
270 * starting and end locations from a source range, respectively.
274 unsigned begin_int_data;
275 unsigned end_int_data;
279 * \brief Retrieve a NULL (invalid) source location.
281 CINDEX_LINKAGE CXSourceLocation clang_getNullLocation();
284 * \determine Determine whether two source locations, which must refer into
285 * the same translation unit, refer to exactly the same point in the source
288 * \returns non-zero if the source locations refer to the same location, zero
289 * if they refer to different locations.
291 CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1,
292 CXSourceLocation loc2);
295 * \brief Retrieves the source location associated with a given file/line/column
296 * in a particular translation unit.
298 CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu,
303 * \brief Retrieves the source location associated with a given character offset
304 * in a particular translation unit.
306 CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu,
311 * \brief Retrieve a NULL (invalid) source range.
313 CINDEX_LINKAGE CXSourceRange clang_getNullRange();
316 * \brief Retrieve a source range given the beginning and ending source
319 CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin,
320 CXSourceLocation end);
323 * \brief Retrieve the file, line, column, and offset represented by
324 * the given source location.
326 * If the location refers into a macro instantiation, retrieves the
327 * location of the macro instantiation.
329 * \param location the location within a source file that will be decomposed
332 * \param file [out] if non-NULL, will be set to the file to which the given
333 * source location points.
335 * \param line [out] if non-NULL, will be set to the line to which the given
336 * source location points.
338 * \param column [out] if non-NULL, will be set to the column to which the given
339 * source location points.
341 * \param offset [out] if non-NULL, will be set to the offset into the
342 * buffer to which the given source location points.
344 CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location,
351 * \brief Retrieve the file, line, column, and offset represented by
352 * the given source location.
354 * If the location refers into a macro instantiation, return where the
355 * location was originally spelled in the source file.
357 * \param location the location within a source file that will be decomposed
360 * \param file [out] if non-NULL, will be set to the file to which the given
361 * source location points.
363 * \param line [out] if non-NULL, will be set to the line to which the given
364 * source location points.
366 * \param column [out] if non-NULL, will be set to the column to which the given
367 * source location points.
369 * \param offset [out] if non-NULL, will be set to the offset into the
370 * buffer to which the given source location points.
372 CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location,
379 * \brief Retrieve a source location representing the first character within a
382 CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
385 * \brief Retrieve a source location representing the last character within a
388 CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
395 * \defgroup CINDEX_DIAG Diagnostic reporting
401 * \brief Describes the severity of a particular diagnostic.
403 enum CXDiagnosticSeverity {
405 * \brief A diagnostic that has been suppressed, e.g., by a command-line
408 CXDiagnostic_Ignored = 0,
411 * \brief This diagnostic is a note that should be attached to the
412 * previous (non-note) diagnostic.
414 CXDiagnostic_Note = 1,
417 * \brief This diagnostic indicates suspicious code that may not be
420 CXDiagnostic_Warning = 2,
423 * \brief This diagnostic indicates that the code is ill-formed.
425 CXDiagnostic_Error = 3,
428 * \brief This diagnostic indicates that the code is ill-formed such
429 * that future parser recovery is unlikely to produce useful
432 CXDiagnostic_Fatal = 4
436 * \brief A single diagnostic, containing the diagnostic's severity,
437 * location, text, source ranges, and fix-it hints.
439 typedef void *CXDiagnostic;
442 * \brief Determine the number of diagnostics produced for the given
445 CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit);
448 * \brief Retrieve a diagnostic associated with the given translation unit.
450 * \param Unit the translation unit to query.
451 * \param Index the zero-based diagnostic number to retrieve.
453 * \returns the requested diagnostic. This diagnostic must be freed
454 * via a call to \c clang_disposeDiagnostic().
456 CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit,
460 * \brief Destroy a diagnostic.
462 CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);
465 * \brief Options to control the display of diagnostics.
467 * The values in this enum are meant to be combined to customize the
468 * behavior of \c clang_displayDiagnostic().
470 enum CXDiagnosticDisplayOptions {
472 * \brief Display the source-location information where the
473 * diagnostic was located.
475 * When set, diagnostics will be prefixed by the file, line, and
476 * (optionally) column to which the diagnostic refers. For example,
479 * test.c:28: warning: extra tokens at end of #endif directive
482 * This option corresponds to the clang flag \c -fshow-source-location.
484 CXDiagnostic_DisplaySourceLocation = 0x01,
487 * \brief If displaying the source-location information of the
488 * diagnostic, also include the column number.
490 * This option corresponds to the clang flag \c -fshow-column.
492 CXDiagnostic_DisplayColumn = 0x02,
495 * \brief If displaying the source-location information of the
496 * diagnostic, also include information about source ranges in a
497 * machine-parsable format.
499 * This option corresponds to the clang flag
500 * \c -fdiagnostics-print-source-range-info.
502 CXDiagnostic_DisplaySourceRanges = 0x04,
505 * \brief Display the option name associated with this diagnostic, if any.
507 * The option name displayed (e.g., -Wconversion) will be placed in brackets
508 * after the diagnostic text. This option corresponds to the clang flag
509 * \c -fdiagnostics-show-option.
511 CXDiagnostic_DisplayOption = 0x08,
514 * \brief Display the category number associated with this diagnostic, if any.
516 * The category number is displayed within brackets after the diagnostic text.
517 * This option corresponds to the clang flag
518 * \c -fdiagnostics-show-category=id.
520 CXDiagnostic_DisplayCategoryId = 0x10,
523 * \brief Display the category name associated with this diagnostic, if any.
525 * The category name is displayed within brackets after the diagnostic text.
526 * This option corresponds to the clang flag
527 * \c -fdiagnostics-show-category=name.
529 CXDiagnostic_DisplayCategoryName = 0x20
533 * \brief Format the given diagnostic in a manner that is suitable for display.
535 * This routine will format the given diagnostic to a string, rendering
536 * the diagnostic according to the various options given. The
537 * \c clang_defaultDiagnosticDisplayOptions() function returns the set of
538 * options that most closely mimics the behavior of the clang compiler.
540 * \param Diagnostic The diagnostic to print.
542 * \param Options A set of options that control the diagnostic display,
543 * created by combining \c CXDiagnosticDisplayOptions values.
545 * \returns A new string containing for formatted diagnostic.
547 CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,
551 * \brief Retrieve the set of display options most similar to the
552 * default behavior of the clang compiler.
554 * \returns A set of display options suitable for use with \c
555 * clang_displayDiagnostic().
557 CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void);
560 * \brief Determine the severity of the given diagnostic.
562 CINDEX_LINKAGE enum CXDiagnosticSeverity
563 clang_getDiagnosticSeverity(CXDiagnostic);
566 * \brief Retrieve the source location of the given diagnostic.
568 * This location is where Clang would print the caret ('^') when
569 * displaying the diagnostic on the command line.
571 CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);
574 * \brief Retrieve the text of the given diagnostic.
576 CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);
579 * \brief Retrieve the name of the command-line option that enabled this
582 * \param Diag The diagnostic to be queried.
584 * \param Disable If non-NULL, will be set to the option that disables this
585 * diagnostic (if any).
587 * \returns A string that contains the command-line option used to enable this
588 * warning, such as "-Wconversion" or "-pedantic".
590 CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag,
594 * \brief Retrieve the category number for this diagnostic.
596 * Diagnostics can be categorized into groups along with other, related
597 * diagnostics (e.g., diagnostics under the same warning flag). This routine
598 * retrieves the category number for the given diagnostic.
600 * \returns The number of the category that contains this diagnostic, or zero
601 * if this diagnostic is uncategorized.
603 CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);
606 * \brief Retrieve the name of a particular diagnostic category.
608 * \param Category A diagnostic category number, as returned by
609 * \c clang_getDiagnosticCategory().
611 * \returns The name of the given diagnostic category.
613 CINDEX_LINKAGE CXString clang_getDiagnosticCategoryName(unsigned Category);
616 * \brief Determine the number of source ranges associated with the given
619 CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
622 * \brief Retrieve a source range associated with the diagnostic.
624 * A diagnostic's source ranges highlight important elements in the source
625 * code. On the command line, Clang displays source ranges by
626 * underlining them with '~' characters.
628 * \param Diagnostic the diagnostic whose range is being extracted.
630 * \param Range the zero-based index specifying which range to
632 * \returns the requested source range.
634 CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,
638 * \brief Determine the number of fix-it hints associated with the
641 CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
644 * \brief Retrieve the replacement information for a given fix-it.
646 * Fix-its are described in terms of a source range whose contents
647 * should be replaced by a string. This approach generalizes over
648 * three kinds of operations: removal of source code (the range covers
649 * the code to be removed and the replacement string is empty),
650 * replacement of source code (the range covers the code to be
651 * replaced and the replacement string provides the new code), and
652 * insertion (both the start and end of the range point at the
653 * insertion location, and the replacement string provides the text to
656 * \param Diagnostic The diagnostic whose fix-its are being queried.
658 * \param FixIt The zero-based index of the fix-it.
660 * \param ReplacementRange The source range whose contents will be
661 * replaced with the returned replacement string. Note that source
662 * ranges are half-open ranges [a, b), so the source code should be
663 * replaced from a and up to (but not including) b.
665 * \returns A string containing text that should be replace the source
666 * code indicated by the \c ReplacementRange.
668 CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic,
670 CXSourceRange *ReplacementRange);
677 * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
679 * The routines in this group provide the ability to create and destroy
680 * translation units from files, either by parsing the contents of the files or
681 * by reading in a serialized representation of a translation unit.
687 * \brief Get the original translation unit source file name.
689 CINDEX_LINKAGE CXString
690 clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
693 * \brief Return the CXTranslationUnit for a given source file and the provided
694 * command line arguments one would pass to the compiler.
696 * Note: The 'source_filename' argument is optional. If the caller provides a
697 * NULL pointer, the name of the source file is expected to reside in the
698 * specified command line arguments.
700 * Note: When encountered in 'clang_command_line_args', the following options
706 * '-o <output file>' (both '-o' and '<output file>' are ignored)
708 * \param CIdx The index object with which the translation unit will be
711 * \param source_filename - The name of the source file to load, or NULL if the
712 * source file is included in \p clang_command_line_args.
714 * \param num_clang_command_line_args The number of command-line arguments in
715 * \p clang_command_line_args.
717 * \param clang_command_line_args The command-line arguments that would be
718 * passed to the \c clang executable if it were being invoked out-of-process.
719 * These command-line options will be parsed and will affect how the translation
720 * unit is parsed. Note that the following options are ignored: '-c',
721 * '-emit-ast', '-fsyntex-only' (which is the default), and '-o <output file>'.
723 * \param num_unsaved_files the number of unsaved file entries in \p
726 * \param unsaved_files the files that have not yet been saved to disk
727 * but may be required for code completion, including the contents of
728 * those files. The contents and name of these files (as specified by
729 * CXUnsavedFile) are copied when necessary, so the client only needs to
730 * guarantee their validity until the call to this function returns.
732 CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
734 const char *source_filename,
735 int num_clang_command_line_args,
736 const char * const *clang_command_line_args,
737 unsigned num_unsaved_files,
738 struct CXUnsavedFile *unsaved_files);
741 * \brief Create a translation unit from an AST file (-emit-ast).
743 CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex,
744 const char *ast_filename);
747 * \brief Flags that control the creation of translation units.
749 * The enumerators in this enumeration type are meant to be bitwise
750 * ORed together to specify which options should be used when
751 * constructing the translation unit.
753 enum CXTranslationUnit_Flags {
755 * \brief Used to indicate that no special translation-unit options are
758 CXTranslationUnit_None = 0x0,
761 * \brief Used to indicate that the parser should construct a "detailed"
762 * preprocessing record, including all macro definitions and instantiations.
764 * Constructing a detailed preprocessing record requires more memory
765 * and time to parse, since the information contained in the record
766 * is usually not retained. However, it can be useful for
767 * applications that require more detailed information about the
768 * behavior of the preprocessor.
770 CXTranslationUnit_DetailedPreprocessingRecord = 0x01,
773 * \brief Used to indicate that the translation unit is incomplete.
775 * When a translation unit is considered "incomplete", semantic
776 * analysis that is typically performed at the end of the
777 * translation unit will be suppressed. For example, this suppresses
778 * the completion of tentative declarations in C and of
779 * instantiation of implicitly-instantiation function templates in
780 * C++. This option is typically used when parsing a header with the
781 * intent of producing a precompiled header.
783 CXTranslationUnit_Incomplete = 0x02,
786 * \brief Used to indicate that the translation unit should be built with an
787 * implicit precompiled header for the preamble.
789 * An implicit precompiled header is used as an optimization when a
790 * particular translation unit is likely to be reparsed many times
791 * when the sources aren't changing that often. In this case, an
792 * implicit precompiled header will be built containing all of the
793 * initial includes at the top of the main file (what we refer to as
794 * the "preamble" of the file). In subsequent parses, if the
795 * preamble or the files in it have not changed, \c
796 * clang_reparseTranslationUnit() will re-use the implicit
797 * precompiled header to improve parsing performance.
799 CXTranslationUnit_PrecompiledPreamble = 0x04,
802 * \brief Used to indicate that the translation unit should cache some
803 * code-completion results with each reparse of the source file.
805 * Caching of code-completion results is a performance optimization that
806 * introduces some overhead to reparsing but improves the performance of
807 * code-completion operations.
809 CXTranslationUnit_CacheCompletionResults = 0x08,
811 * \brief Enable precompiled preambles in C++.
813 * Note: this is a *temporary* option that is available only while
814 * we are testing C++ precompiled preamble support.
816 CXTranslationUnit_CXXPrecompiledPreamble = 0x10,
819 * \brief Enabled chained precompiled preambles in C++.
821 * Note: this is a *temporary* option that is available only while
822 * we are testing C++ precompiled preamble support.
824 CXTranslationUnit_CXXChainedPCH = 0x20
828 * \brief Returns the set of flags that is suitable for parsing a translation
829 * unit that is being edited.
831 * The set of flags returned provide options for \c clang_parseTranslationUnit()
832 * to indicate that the translation unit is likely to be reparsed many times,
833 * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly
834 * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag
835 * set contains an unspecified set of optimizations (e.g., the precompiled
836 * preamble) geared toward improving the performance of these routines. The
837 * set of optimizations enabled may change from one version to the next.
839 CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
842 * \brief Parse the given source file and the translation unit corresponding
845 * This routine is the main entry point for the Clang C API, providing the
846 * ability to parse a source file into a translation unit that can then be
847 * queried by other functions in the API. This routine accepts a set of
848 * command-line arguments so that the compilation can be configured in the same
849 * way that the compiler is configured on the command line.
851 * \param CIdx The index object with which the translation unit will be
854 * \param source_filename The name of the source file to load, or NULL if the
855 * source file is included in \p command_line_args.
857 * \param command_line_args The command-line arguments that would be
858 * passed to the \c clang executable if it were being invoked out-of-process.
859 * These command-line options will be parsed and will affect how the translation
860 * unit is parsed. Note that the following options are ignored: '-c',
861 * '-emit-ast', '-fsyntex-only' (which is the default), and '-o <output file>'.
863 * \param num_command_line_args The number of command-line arguments in
864 * \p command_line_args.
866 * \param unsaved_files the files that have not yet been saved to disk
867 * but may be required for parsing, including the contents of
868 * those files. The contents and name of these files (as specified by
869 * CXUnsavedFile) are copied when necessary, so the client only needs to
870 * guarantee their validity until the call to this function returns.
872 * \param num_unsaved_files the number of unsaved file entries in \p
875 * \param options A bitmask of options that affects how the translation unit
876 * is managed but not its compilation. This should be a bitwise OR of the
877 * CXTranslationUnit_XXX flags.
879 * \returns A new translation unit describing the parsed code and containing
880 * any diagnostics produced by the compiler. If there is a failure from which
881 * the compiler cannot recover, returns NULL.
883 CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx,
884 const char *source_filename,
885 const char * const *command_line_args,
886 int num_command_line_args,
887 struct CXUnsavedFile *unsaved_files,
888 unsigned num_unsaved_files,
892 * \brief Flags that control how translation units are saved.
894 * The enumerators in this enumeration type are meant to be bitwise
895 * ORed together to specify which options should be used when
896 * saving the translation unit.
898 enum CXSaveTranslationUnit_Flags {
900 * \brief Used to indicate that no special saving options are needed.
902 CXSaveTranslationUnit_None = 0x0
906 * \brief Returns the set of flags that is suitable for saving a translation
909 * The set of flags returned provide options for
910 * \c clang_saveTranslationUnit() by default. The returned flag
911 * set contains an unspecified set of options that save translation units with
912 * the most commonly-requested data.
914 CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU);
917 * \brief Saves a translation unit into a serialized representation of
918 * that translation unit on disk.
920 * Any translation unit that was parsed without error can be saved
921 * into a file. The translation unit can then be deserialized into a
922 * new \c CXTranslationUnit with \c clang_createTranslationUnit() or,
923 * if it is an incomplete translation unit that corresponds to a
924 * header, used as a precompiled header when parsing other translation
927 * \param TU The translation unit to save.
929 * \param FileName The file to which the translation unit will be saved.
931 * \param options A bitmask of options that affects how the translation unit
932 * is saved. This should be a bitwise OR of the
933 * CXSaveTranslationUnit_XXX flags.
935 * \returns Zero if the translation unit was saved successfully, a
936 * non-zero value otherwise.
938 CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU,
939 const char *FileName,
943 * \brief Destroy the specified CXTranslationUnit object.
945 CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
948 * \brief Flags that control the reparsing of translation units.
950 * The enumerators in this enumeration type are meant to be bitwise
951 * ORed together to specify which options should be used when
952 * reparsing the translation unit.
954 enum CXReparse_Flags {
956 * \brief Used to indicate that no special reparsing options are needed.
962 * \brief Returns the set of flags that is suitable for reparsing a translation
965 * The set of flags returned provide options for
966 * \c clang_reparseTranslationUnit() by default. The returned flag
967 * set contains an unspecified set of optimizations geared toward common uses
968 * of reparsing. The set of optimizations enabled may change from one version
971 CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU);
974 * \brief Reparse the source files that produced this translation unit.
976 * This routine can be used to re-parse the source files that originally
977 * created the given translation unit, for example because those source files
978 * have changed (either on disk or as passed via \p unsaved_files). The
979 * source code will be reparsed with the same command-line options as it
980 * was originally parsed.
982 * Reparsing a translation unit invalidates all cursors and source locations
983 * that refer into that translation unit. This makes reparsing a translation
984 * unit semantically equivalent to destroying the translation unit and then
985 * creating a new translation unit with the same command-line arguments.
986 * However, it may be more efficient to reparse a translation
987 * unit using this routine.
989 * \param TU The translation unit whose contents will be re-parsed. The
990 * translation unit must originally have been built with
991 * \c clang_createTranslationUnitFromSourceFile().
993 * \param num_unsaved_files The number of unsaved file entries in \p
996 * \param unsaved_files The files that have not yet been saved to disk
997 * but may be required for parsing, including the contents of
998 * those files. The contents and name of these files (as specified by
999 * CXUnsavedFile) are copied when necessary, so the client only needs to
1000 * guarantee their validity until the call to this function returns.
1002 * \param options A bitset of options composed of the flags in CXReparse_Flags.
1003 * The function \c clang_defaultReparseOptions() produces a default set of
1004 * options recommended for most uses, based on the translation unit.
1006 * \returns 0 if the sources could be reparsed. A non-zero value will be
1007 * returned if reparsing was impossible, such that the translation unit is
1008 * invalid. In such cases, the only valid call for \p TU is
1009 * \c clang_disposeTranslationUnit(TU).
1011 CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU,
1012 unsigned num_unsaved_files,
1013 struct CXUnsavedFile *unsaved_files,
1021 * \brief Describes the kind of entity that a cursor refers to.
1026 * \brief A declaration whose specific kind is not exposed via this
1029 * Unexposed declarations have the same operations as any other kind
1030 * of declaration; one can extract their location information,
1031 * spelling, find their definitions, etc. However, the specific kind
1032 * of the declaration is not reported.
1034 CXCursor_UnexposedDecl = 1,
1035 /** \brief A C or C++ struct. */
1036 CXCursor_StructDecl = 2,
1037 /** \brief A C or C++ union. */
1038 CXCursor_UnionDecl = 3,
1039 /** \brief A C++ class. */
1040 CXCursor_ClassDecl = 4,
1041 /** \brief An enumeration. */
1042 CXCursor_EnumDecl = 5,
1044 * \brief A field (in C) or non-static data member (in C++) in a
1045 * struct, union, or C++ class.
1047 CXCursor_FieldDecl = 6,
1048 /** \brief An enumerator constant. */
1049 CXCursor_EnumConstantDecl = 7,
1050 /** \brief A function. */
1051 CXCursor_FunctionDecl = 8,
1052 /** \brief A variable. */
1053 CXCursor_VarDecl = 9,
1054 /** \brief A function or method parameter. */
1055 CXCursor_ParmDecl = 10,
1056 /** \brief An Objective-C @interface. */
1057 CXCursor_ObjCInterfaceDecl = 11,
1058 /** \brief An Objective-C @interface for a category. */
1059 CXCursor_ObjCCategoryDecl = 12,
1060 /** \brief An Objective-C @protocol declaration. */
1061 CXCursor_ObjCProtocolDecl = 13,
1062 /** \brief An Objective-C @property declaration. */
1063 CXCursor_ObjCPropertyDecl = 14,
1064 /** \brief An Objective-C instance variable. */
1065 CXCursor_ObjCIvarDecl = 15,
1066 /** \brief An Objective-C instance method. */
1067 CXCursor_ObjCInstanceMethodDecl = 16,
1068 /** \brief An Objective-C class method. */
1069 CXCursor_ObjCClassMethodDecl = 17,
1070 /** \brief An Objective-C @implementation. */
1071 CXCursor_ObjCImplementationDecl = 18,
1072 /** \brief An Objective-C @implementation for a category. */
1073 CXCursor_ObjCCategoryImplDecl = 19,
1074 /** \brief A typedef */
1075 CXCursor_TypedefDecl = 20,
1076 /** \brief A C++ class method. */
1077 CXCursor_CXXMethod = 21,
1078 /** \brief A C++ namespace. */
1079 CXCursor_Namespace = 22,
1080 /** \brief A linkage specification, e.g. 'extern "C"'. */
1081 CXCursor_LinkageSpec = 23,
1082 /** \brief A C++ constructor. */
1083 CXCursor_Constructor = 24,
1084 /** \brief A C++ destructor. */
1085 CXCursor_Destructor = 25,
1086 /** \brief A C++ conversion function. */
1087 CXCursor_ConversionFunction = 26,
1088 /** \brief A C++ template type parameter. */
1089 CXCursor_TemplateTypeParameter = 27,
1090 /** \brief A C++ non-type template parameter. */
1091 CXCursor_NonTypeTemplateParameter = 28,
1092 /** \brief A C++ template template parameter. */
1093 CXCursor_TemplateTemplateParameter = 29,
1094 /** \brief A C++ function template. */
1095 CXCursor_FunctionTemplate = 30,
1096 /** \brief A C++ class template. */
1097 CXCursor_ClassTemplate = 31,
1098 /** \brief A C++ class template partial specialization. */
1099 CXCursor_ClassTemplatePartialSpecialization = 32,
1100 /** \brief A C++ namespace alias declaration. */
1101 CXCursor_NamespaceAlias = 33,
1102 /** \brief A C++ using directive. */
1103 CXCursor_UsingDirective = 34,
1104 /** \brief A using declaration. */
1105 CXCursor_UsingDeclaration = 35,
1106 CXCursor_FirstDecl = CXCursor_UnexposedDecl,
1107 CXCursor_LastDecl = CXCursor_UsingDeclaration,
1110 CXCursor_FirstRef = 40, /* Decl references */
1111 CXCursor_ObjCSuperClassRef = 40,
1112 CXCursor_ObjCProtocolRef = 41,
1113 CXCursor_ObjCClassRef = 42,
1115 * \brief A reference to a type declaration.
1117 * A type reference occurs anywhere where a type is named but not
1118 * declared. For example, given:
1121 * typedef unsigned size_type;
1125 * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
1126 * while the type of the variable "size" is referenced. The cursor
1127 * referenced by the type of size is the typedef for size_type.
1129 CXCursor_TypeRef = 43,
1130 CXCursor_CXXBaseSpecifier = 44,
1132 * \brief A reference to a class template, function template, template
1133 * template parameter, or class template partial specialization.
1135 CXCursor_TemplateRef = 45,
1137 * \brief A reference to a namespace or namespace alias.
1139 CXCursor_NamespaceRef = 46,
1141 * \brief A reference to a member of a struct, union, or class that occurs in
1142 * some non-expression context, e.g., a designated initializer.
1144 CXCursor_MemberRef = 47,
1146 * \brief A reference to a labeled statement.
1148 * This cursor kind is used to describe the jump to "start_over" in the
1149 * goto statement in the following example:
1158 * A label reference cursor refers to a label statement.
1160 CXCursor_LabelRef = 48,
1163 * \brief A reference to a set of overloaded functions or function templates
1164 * that has not yet been resolved to a specific function or function template.
1166 * An overloaded declaration reference cursor occurs in C++ templates where
1167 * a dependent name refers to a function. For example:
1170 * template<typename T> void swap(T&, T&);
1173 * void swap(X&, X&);
1175 * template<typename T>
1176 * void reverse(T* first, T* last) {
1177 * while (first < last - 1) {
1178 * swap(*first, *--last);
1184 * void swap(Y&, Y&);
1187 * Here, the identifier "swap" is associated with an overloaded declaration
1188 * reference. In the template definition, "swap" refers to either of the two
1189 * "swap" functions declared above, so both results will be available. At
1190 * instantiation time, "swap" may also refer to other functions found via
1191 * argument-dependent lookup (e.g., the "swap" function at the end of the
1194 * The functions \c clang_getNumOverloadedDecls() and
1195 * \c clang_getOverloadedDecl() can be used to retrieve the definitions
1196 * referenced by this cursor.
1198 CXCursor_OverloadedDeclRef = 49,
1200 CXCursor_LastRef = CXCursor_OverloadedDeclRef,
1202 /* Error conditions */
1203 CXCursor_FirstInvalid = 70,
1204 CXCursor_InvalidFile = 70,
1205 CXCursor_NoDeclFound = 71,
1206 CXCursor_NotImplemented = 72,
1207 CXCursor_InvalidCode = 73,
1208 CXCursor_LastInvalid = CXCursor_InvalidCode,
1211 CXCursor_FirstExpr = 100,
1214 * \brief An expression whose specific kind is not exposed via this
1217 * Unexposed expressions have the same operations as any other kind
1218 * of expression; one can extract their location information,
1219 * spelling, children, etc. However, the specific kind of the
1220 * expression is not reported.
1222 CXCursor_UnexposedExpr = 100,
1225 * \brief An expression that refers to some value declaration, such
1226 * as a function, varible, or enumerator.
1228 CXCursor_DeclRefExpr = 101,
1231 * \brief An expression that refers to a member of a struct, union,
1232 * class, Objective-C class, etc.
1234 CXCursor_MemberRefExpr = 102,
1236 /** \brief An expression that calls a function. */
1237 CXCursor_CallExpr = 103,
1239 /** \brief An expression that sends a message to an Objective-C
1241 CXCursor_ObjCMessageExpr = 104,
1243 /** \brief An expression that represents a block literal. */
1244 CXCursor_BlockExpr = 105,
1246 CXCursor_LastExpr = 105,
1249 CXCursor_FirstStmt = 200,
1251 * \brief A statement whose specific kind is not exposed via this
1254 * Unexposed statements have the same operations as any other kind of
1255 * statement; one can extract their location information, spelling,
1256 * children, etc. However, the specific kind of the statement is not
1259 CXCursor_UnexposedStmt = 200,
1261 /** \brief A labelled statement in a function.
1263 * This cursor kind is used to describe the "start_over:" label statement in
1264 * the following example:
1272 CXCursor_LabelStmt = 201,
1274 CXCursor_LastStmt = CXCursor_LabelStmt,
1277 * \brief Cursor that represents the translation unit itself.
1279 * The translation unit cursor exists primarily to act as the root
1280 * cursor for traversing the contents of a translation unit.
1282 CXCursor_TranslationUnit = 300,
1285 CXCursor_FirstAttr = 400,
1287 * \brief An attribute whose specific kind is not exposed via this
1290 CXCursor_UnexposedAttr = 400,
1292 CXCursor_IBActionAttr = 401,
1293 CXCursor_IBOutletAttr = 402,
1294 CXCursor_IBOutletCollectionAttr = 403,
1295 CXCursor_LastAttr = CXCursor_IBOutletCollectionAttr,
1298 CXCursor_PreprocessingDirective = 500,
1299 CXCursor_MacroDefinition = 501,
1300 CXCursor_MacroInstantiation = 502,
1301 CXCursor_InclusionDirective = 503,
1302 CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective,
1303 CXCursor_LastPreprocessing = CXCursor_InclusionDirective
1307 * \brief A cursor representing some element in the abstract syntax tree for
1308 * a translation unit.
1310 * The cursor abstraction unifies the different kinds of entities in a
1311 * program--declaration, statements, expressions, references to declarations,
1312 * etc.--under a single "cursor" abstraction with a common set of operations.
1313 * Common operation for a cursor include: getting the physical location in
1314 * a source file where the cursor points, getting the name associated with a
1315 * cursor, and retrieving cursors for any child nodes of a particular cursor.
1317 * Cursors can be produced in two specific ways.
1318 * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
1319 * from which one can use clang_visitChildren() to explore the rest of the
1320 * translation unit. clang_getCursor() maps from a physical source location
1321 * to the entity that resides at that location, allowing one to map from the
1322 * source code into the AST.
1325 enum CXCursorKind kind;
1330 * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
1336 * \brief Retrieve the NULL cursor, which represents no entity.
1338 CINDEX_LINKAGE CXCursor clang_getNullCursor(void);
1341 * \brief Retrieve the cursor that represents the given translation unit.
1343 * The translation unit cursor can be used to start traversing the
1344 * various declarations within the given translation unit.
1346 CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit);
1349 * \brief Determine whether two cursors are equivalent.
1351 CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor);
1354 * \brief Compute a hash value for the given cursor.
1356 CINDEX_LINKAGE unsigned clang_hashCursor(CXCursor);
1359 * \brief Retrieve the kind of the given cursor.
1361 CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
1364 * \brief Determine whether the given cursor kind represents a declaration.
1366 CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
1369 * \brief Determine whether the given cursor kind represents a simple
1372 * Note that other kinds of cursors (such as expressions) can also refer to
1373 * other cursors. Use clang_getCursorReferenced() to determine whether a
1374 * particular cursor refers to another entity.
1376 CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
1379 * \brief Determine whether the given cursor kind represents an expression.
1381 CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind);
1384 * \brief Determine whether the given cursor kind represents a statement.
1386 CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind);
1389 * \brief Determine whether the given cursor kind represents an invalid
1392 CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
1395 * \brief Determine whether the given cursor kind represents a translation
1398 CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind);
1401 * \brief Determine whether the given cursor represents a preprocessing
1402 * element, such as a preprocessor directive or macro instantiation.
1404 CINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind);
1407 * \brief Determine whether the given cursor represents a currently
1408 * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).
1410 CINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind);
1413 * \brief Describe the linkage of the entity referred to by a cursor.
1415 enum CXLinkageKind {
1416 /** \brief This value indicates that no linkage information is available
1417 * for a provided CXCursor. */
1420 * \brief This is the linkage for variables, parameters, and so on that
1421 * have automatic storage. This covers normal (non-extern) local variables.
1423 CXLinkage_NoLinkage,
1424 /** \brief This is the linkage for static variables and static functions. */
1426 /** \brief This is the linkage for entities with external linkage that live
1427 * in C++ anonymous namespaces.*/
1428 CXLinkage_UniqueExternal,
1429 /** \brief This is the linkage for entities with true, external linkage. */
1434 * \brief Determine the linkage of the entity referred to by a given cursor.
1436 CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor);
1439 * \brief Determine the availability of the entity that this cursor refers to.
1441 * \param cursor The cursor to query.
1443 * \returns The availability of the cursor.
1445 CINDEX_LINKAGE enum CXAvailabilityKind
1446 clang_getCursorAvailability(CXCursor cursor);
1449 * \brief Describe the "language" of the entity referred to by a cursor.
1451 CINDEX_LINKAGE enum CXLanguageKind {
1452 CXLanguage_Invalid = 0,
1455 CXLanguage_CPlusPlus
1459 * \brief Determine the "language" of the entity referred to by a given cursor.
1461 CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor);
1465 * \brief A fast container representing a set of CXCursors.
1467 typedef struct CXCursorSetImpl *CXCursorSet;
1470 * \brief Creates an empty CXCursorSet.
1472 CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet();
1475 * \brief Disposes a CXCursorSet and releases its associated memory.
1477 CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset);
1480 * \brief Queries a CXCursorSet to see if it contains a specific CXCursor.
1482 * \returns non-zero if the set contains the specified cursor.
1484 CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset,
1488 * \brief Inserts a CXCursor into a CXCursorSet.
1490 * \returns zero if the CXCursor was already in the set, and non-zero otherwise.
1492 CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset,
1496 * \brief Determine the semantic parent of the given cursor.
1498 * The semantic parent of a cursor is the cursor that semantically contains
1499 * the given \p cursor. For many declarations, the lexical and semantic parents
1500 * are equivalent (the lexical parent is returned by
1501 * \c clang_getCursorLexicalParent()). They diverge when declarations or
1502 * definitions are provided out-of-line. For example:
1512 * In the out-of-line definition of \c C::f, the semantic parent is the
1513 * the class \c C, of which this function is a member. The lexical parent is
1514 * the place where the declaration actually occurs in the source code; in this
1515 * case, the definition occurs in the translation unit. In general, the
1516 * lexical parent for a given entity can change without affecting the semantics
1517 * of the program, and the lexical parent of different declarations of the
1518 * same entity may be different. Changing the semantic parent of a declaration,
1519 * on the other hand, can have a major impact on semantics, and redeclarations
1520 * of a particular entity should all have the same semantic context.
1522 * In the example above, both declarations of \c C::f have \c C as their
1523 * semantic context, while the lexical context of the first \c C::f is \c C
1524 * and the lexical context of the second \c C::f is the translation unit.
1526 * For global declarations, the semantic parent is the translation unit.
1528 CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor);
1531 * \brief Determine the lexical parent of the given cursor.
1533 * The lexical parent of a cursor is the cursor in which the given \p cursor
1534 * was actually written. For many declarations, the lexical and semantic parents
1535 * are equivalent (the semantic parent is returned by
1536 * \c clang_getCursorSemanticParent()). They diverge when declarations or
1537 * definitions are provided out-of-line. For example:
1547 * In the out-of-line definition of \c C::f, the semantic parent is the
1548 * the class \c C, of which this function is a member. The lexical parent is
1549 * the place where the declaration actually occurs in the source code; in this
1550 * case, the definition occurs in the translation unit. In general, the
1551 * lexical parent for a given entity can change without affecting the semantics
1552 * of the program, and the lexical parent of different declarations of the
1553 * same entity may be different. Changing the semantic parent of a declaration,
1554 * on the other hand, can have a major impact on semantics, and redeclarations
1555 * of a particular entity should all have the same semantic context.
1557 * In the example above, both declarations of \c C::f have \c C as their
1558 * semantic context, while the lexical context of the first \c C::f is \c C
1559 * and the lexical context of the second \c C::f is the translation unit.
1561 * For declarations written in the global scope, the lexical parent is
1562 * the translation unit.
1564 CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor);
1567 * \brief Determine the set of methods that are overridden by the given
1570 * In both Objective-C and C++, a method (aka virtual member function,
1571 * in C++) can override a virtual method in a base class. For
1572 * Objective-C, a method is said to override any method in the class's
1573 * interface (if we're coming from an implementation), its protocols,
1574 * or its categories, that has the same selector and is of the same
1575 * kind (class or instance). If no such method exists, the search
1576 * continues to the class's superclass, its protocols, and its
1577 * categories, and so on.
1579 * For C++, a virtual member function overrides any virtual member
1580 * function with the same signature that occurs in its base
1581 * classes. With multiple inheritance, a virtual member function can
1582 * override several virtual member functions coming from different
1585 * In all cases, this function determines the immediate overridden
1586 * method, rather than all of the overridden methods. For example, if
1587 * a method is originally declared in a class A, then overridden in B
1588 * (which in inherits from A) and also in C (which inherited from B),
1589 * then the only overridden method returned from this function when
1590 * invoked on C's method will be B's method. The client may then
1591 * invoke this function again, given the previously-found overridden
1592 * methods, to map out the complete method-override set.
1594 * \param cursor A cursor representing an Objective-C or C++
1595 * method. This routine will compute the set of methods that this
1598 * \param overridden A pointer whose pointee will be replaced with a
1599 * pointer to an array of cursors, representing the set of overridden
1600 * methods. If there are no overridden methods, the pointee will be
1601 * set to NULL. The pointee must be freed via a call to
1602 * \c clang_disposeOverriddenCursors().
1604 * \param num_overridden A pointer to the number of overridden
1605 * functions, will be set to the number of overridden functions in the
1606 * array pointed to by \p overridden.
1608 CINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor,
1609 CXCursor **overridden,
1610 unsigned *num_overridden);
1613 * \brief Free the set of overridden cursors returned by \c
1614 * clang_getOverriddenCursors().
1616 CINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden);
1619 * \brief Retrieve the file that is included by the given inclusion directive
1622 CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor);
1629 * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
1631 * Cursors represent a location within the Abstract Syntax Tree (AST). These
1632 * routines help map between cursors and the physical locations where the
1633 * described entities occur in the source code. The mapping is provided in
1634 * both directions, so one can map from source code to the AST and back.
1640 * \brief Map a source location to the cursor that describes the entity at that
1641 * location in the source code.
1643 * clang_getCursor() maps an arbitrary source location within a translation
1644 * unit down to the most specific cursor that describes the entity at that
1645 * location. For example, given an expression \c x + y, invoking
1646 * clang_getCursor() with a source location pointing to "x" will return the
1647 * cursor for "x"; similarly for "y". If the cursor points anywhere between
1648 * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
1649 * will return a cursor referring to the "+" expression.
1651 * \returns a cursor representing the entity at the given source location, or
1652 * a NULL cursor if no such entity can be found.
1654 CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation);
1657 * \brief Retrieve the physical location of the source constructor referenced
1658 * by the given cursor.
1660 * The location of a declaration is typically the location of the name of that
1661 * declaration, where the name of that declaration would occur if it is
1662 * unnamed, or some keyword that introduces that particular declaration.
1663 * The location of a reference is where that reference occurs within the
1666 CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor);
1669 * \brief Retrieve the physical extent of the source construct referenced by
1672 * The extent of a cursor starts with the file/line/column pointing at the
1673 * first character within the source construct that the cursor refers to and
1674 * ends with the last character withinin that source construct. For a
1675 * declaration, the extent covers the declaration itself. For a reference,
1676 * the extent covers the location of the reference (e.g., where the referenced
1677 * entity was actually used).
1679 CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor);
1686 * \defgroup CINDEX_TYPES Type information for CXCursors
1692 * \brief Describes the kind of type
1696 * \brief Reprents an invalid type (e.g., where no type is available).
1701 * \brief A type whose specific kind is not exposed via this
1704 CXType_Unexposed = 1,
1716 CXType_ULongLong = 11,
1717 CXType_UInt128 = 12,
1724 CXType_LongLong = 19,
1728 CXType_LongDouble = 23,
1729 CXType_NullPtr = 24,
1730 CXType_Overload = 25,
1731 CXType_Dependent = 26,
1733 CXType_ObjCClass = 28,
1734 CXType_ObjCSel = 29,
1735 CXType_FirstBuiltin = CXType_Void,
1736 CXType_LastBuiltin = CXType_ObjCSel,
1738 CXType_Complex = 100,
1739 CXType_Pointer = 101,
1740 CXType_BlockPointer = 102,
1741 CXType_LValueReference = 103,
1742 CXType_RValueReference = 104,
1743 CXType_Record = 105,
1745 CXType_Typedef = 107,
1746 CXType_ObjCInterface = 108,
1747 CXType_ObjCObjectPointer = 109,
1748 CXType_FunctionNoProto = 110,
1749 CXType_FunctionProto = 111
1753 * \brief The type of an element in the abstract syntax tree.
1757 enum CXTypeKind kind;
1762 * \brief Retrieve the type of a CXCursor (if any).
1764 CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C);
1767 * \determine Determine whether two CXTypes represent the same type.
1769 * \returns non-zero if the CXTypes represent the same type and
1772 CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B);
1775 * \brief Return the canonical type for a CXType.
1777 * Clang's type system explicitly models typedefs and all the ways
1778 * a specific type can be represented. The canonical type is the underlying
1779 * type with all the "sugar" removed. For example, if 'T' is a typedef
1780 * for 'int', the canonical type for 'T' would be 'int'.
1782 CINDEX_LINKAGE CXType clang_getCanonicalType(CXType T);
1785 * \determine Determine whether a CXType has the "const" qualifier set,
1786 * without looking through typedefs that may have added "const" at a different level.
1788 CINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T);
1791 * \determine Determine whether a CXType has the "volatile" qualifier set,
1792 * without looking through typedefs that may have added "volatile" at a different level.
1794 CINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T);
1797 * \determine Determine whether a CXType has the "restrict" qualifier set,
1798 * without looking through typedefs that may have added "restrict" at a different level.
1800 CINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T);
1803 * \brief For pointer types, returns the type of the pointee.
1806 CINDEX_LINKAGE CXType clang_getPointeeType(CXType T);
1809 * \brief Return the cursor for the declaration of the given type.
1811 CINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T);
1814 * Returns the Objective-C type encoding for the specified declaration.
1816 CINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C);
1819 * \brief Retrieve the spelling of a given CXTypeKind.
1821 CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K);
1824 * \brief Retrieve the result type associated with a function type.
1826 CINDEX_LINKAGE CXType clang_getResultType(CXType T);
1829 * \brief Retrieve the result type associated with a given cursor. This only
1830 * returns a valid type of the cursor refers to a function or method.
1832 CINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C);
1835 * \brief Return 1 if the CXType is a POD (plain old data) type, and 0
1838 CINDEX_LINKAGE unsigned clang_isPODType(CXType T);
1841 * \brief Returns 1 if the base class specified by the cursor with kind
1842 * CX_CXXBaseSpecifier is virtual.
1844 CINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor);
1847 * \brief Represents the C++ access control level to a base class for a
1848 * cursor with kind CX_CXXBaseSpecifier.
1850 enum CX_CXXAccessSpecifier {
1851 CX_CXXInvalidAccessSpecifier,
1858 * \brief Returns the access control level for the C++ base specifier
1859 * represented by a cursor with kind CX_CXXBaseSpecifier.
1861 CINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor);
1864 * \brief Determine the number of overloaded declarations referenced by a
1865 * \c CXCursor_OverloadedDeclRef cursor.
1867 * \param cursor The cursor whose overloaded declarations are being queried.
1869 * \returns The number of overloaded declarations referenced by \c cursor. If it
1870 * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0.
1872 CINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor);
1875 * \brief Retrieve a cursor for one of the overloaded declarations referenced
1876 * by a \c CXCursor_OverloadedDeclRef cursor.
1878 * \param cursor The cursor whose overloaded declarations are being queried.
1880 * \param index The zero-based index into the set of overloaded declarations in
1883 * \returns A cursor representing the declaration referenced by the given
1884 * \c cursor at the specified \c index. If the cursor does not have an
1885 * associated set of overloaded declarations, or if the index is out of bounds,
1886 * returns \c clang_getNullCursor();
1888 CINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor,
1896 * \defgroup CINDEX_ATTRIBUTES Information for attributes
1903 * \brief For cursors representing an iboutletcollection attribute,
1904 * this function returns the collection element type.
1907 CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor);
1914 * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
1916 * These routines provide the ability to traverse the abstract syntax tree
1923 * \brief Describes how the traversal of the children of a particular
1924 * cursor should proceed after visiting a particular child cursor.
1926 * A value of this enumeration type should be returned by each
1927 * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
1929 enum CXChildVisitResult {
1931 * \brief Terminates the cursor traversal.
1935 * \brief Continues the cursor traversal with the next sibling of
1936 * the cursor just visited, without visiting its children.
1938 CXChildVisit_Continue,
1940 * \brief Recursively traverse the children of this cursor, using
1941 * the same visitor and client data.
1943 CXChildVisit_Recurse
1947 * \brief Visitor invoked for each cursor found by a traversal.
1949 * This visitor function will be invoked for each cursor found by
1950 * clang_visitCursorChildren(). Its first argument is the cursor being
1951 * visited, its second argument is the parent visitor for that cursor,
1952 * and its third argument is the client data provided to
1953 * clang_visitCursorChildren().
1955 * The visitor should return one of the \c CXChildVisitResult values
1956 * to direct clang_visitCursorChildren().
1958 typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor,
1960 CXClientData client_data);
1963 * \brief Visit the children of a particular cursor.
1965 * This function visits all the direct children of the given cursor,
1966 * invoking the given \p visitor function with the cursors of each
1967 * visited child. The traversal may be recursive, if the visitor returns
1968 * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
1969 * the visitor returns \c CXChildVisit_Break.
1971 * \param parent the cursor whose child may be visited. All kinds of
1972 * cursors can be visited, including invalid cursors (which, by
1973 * definition, have no children).
1975 * \param visitor the visitor function that will be invoked for each
1976 * child of \p parent.
1978 * \param client_data pointer data supplied by the client, which will
1979 * be passed to the visitor each time it is invoked.
1981 * \returns a non-zero value if the traversal was terminated
1982 * prematurely by the visitor returning \c CXChildVisit_Break.
1984 CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent,
1985 CXCursorVisitor visitor,
1986 CXClientData client_data);
1987 #ifdef __has_feature
1988 # if __has_feature(blocks)
1990 * \brief Visitor invoked for each cursor found by a traversal.
1992 * This visitor block will be invoked for each cursor found by
1993 * clang_visitChildrenWithBlock(). Its first argument is the cursor being
1994 * visited, its second argument is the parent visitor for that cursor.
1996 * The visitor should return one of the \c CXChildVisitResult values
1997 * to direct clang_visitChildrenWithBlock().
1999 typedef enum CXChildVisitResult
2000 (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent);
2003 * Visits the children of a cursor using the specified block. Behaves
2004 * identically to clang_visitChildren() in all other respects.
2006 unsigned clang_visitChildrenWithBlock(CXCursor parent,
2007 CXCursorVisitorBlock block);
2016 * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
2018 * These routines provide the ability to determine references within and
2019 * across translation units, by providing the names of the entities referenced
2020 * by cursors, follow reference cursors to the declarations they reference,
2021 * and associate declarations with their definitions.
2027 * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced
2028 * by the given cursor.
2030 * A Unified Symbol Resolution (USR) is a string that identifies a particular
2031 * entity (function, class, variable, etc.) within a program. USRs can be
2032 * compared across translation units to determine, e.g., when references in
2033 * one translation refer to an entity defined in another translation unit.
2035 CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor);
2038 * \brief Construct a USR for a specified Objective-C class.
2040 CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name);
2043 * \brief Construct a USR for a specified Objective-C category.
2045 CINDEX_LINKAGE CXString
2046 clang_constructUSR_ObjCCategory(const char *class_name,
2047 const char *category_name);
2050 * \brief Construct a USR for a specified Objective-C protocol.
2052 CINDEX_LINKAGE CXString
2053 clang_constructUSR_ObjCProtocol(const char *protocol_name);
2057 * \brief Construct a USR for a specified Objective-C instance variable and
2058 * the USR for its containing class.
2060 CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name,
2064 * \brief Construct a USR for a specified Objective-C method and
2065 * the USR for its containing class.
2067 CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name,
2068 unsigned isInstanceMethod,
2072 * \brief Construct a USR for a specified Objective-C property and the USR
2073 * for its containing class.
2075 CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property,
2079 * \brief Retrieve a name for the entity referenced by this cursor.
2081 CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
2084 * \brief Retrieve the display name for the entity referenced by this cursor.
2086 * The display name contains extra information that helps identify the cursor,
2087 * such as the parameters of a function or template or the arguments of a
2088 * class template specialization.
2090 CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor);
2092 /** \brief For a cursor that is a reference, retrieve a cursor representing the
2093 * entity that it references.
2095 * Reference cursors refer to other entities in the AST. For example, an
2096 * Objective-C superclass reference cursor refers to an Objective-C class.
2097 * This function produces the cursor for the Objective-C class from the
2098 * cursor for the superclass reference. If the input cursor is a declaration or
2099 * definition, it returns that declaration or definition unchanged.
2100 * Otherwise, returns the NULL cursor.
2102 CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor);
2105 * \brief For a cursor that is either a reference to or a declaration
2106 * of some entity, retrieve a cursor that describes the definition of
2109 * Some entities can be declared multiple times within a translation
2110 * unit, but only one of those declarations can also be a
2111 * definition. For example, given:
2115 * int g(int x, int y) { return f(x, y); }
2116 * int f(int a, int b) { return a + b; }
2120 * there are three declarations of the function "f", but only the
2121 * second one is a definition. The clang_getCursorDefinition()
2122 * function will take any cursor pointing to a declaration of "f"
2123 * (the first or fourth lines of the example) or a cursor referenced
2124 * that uses "f" (the call to "f' inside "g") and will return a
2125 * declaration cursor pointing to the definition (the second "f"
2128 * If given a cursor for which there is no corresponding definition,
2129 * e.g., because there is no definition of that entity within this
2130 * translation unit, returns a NULL cursor.
2132 CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor);
2135 * \brief Determine whether the declaration pointed to by this cursor
2136 * is also a definition of that entity.
2138 CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor);
2141 * \brief Retrieve the canonical cursor corresponding to the given cursor.
2143 * In the C family of languages, many kinds of entities can be declared several
2144 * times within a single translation unit. For example, a structure type can
2145 * be forward-declared (possibly multiple times) and later defined:
2155 * The declarations and the definition of \c X are represented by three
2156 * different cursors, all of which are declarations of the same underlying
2157 * entity. One of these cursor is considered the "canonical" cursor, which
2158 * is effectively the representative for the underlying entity. One can
2159 * determine if two cursors are declarations of the same underlying entity by
2160 * comparing their canonical cursors.
2162 * \returns The canonical cursor for the entity referred to by the given cursor.
2164 CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor);
2171 * \defgroup CINDEX_CPP C++ AST introspection
2173 * The routines in this group provide access information in the ASTs specific
2174 * to C++ language features.
2180 * \brief Determine if a C++ member function or member function template is
2181 * declared 'static'.
2183 CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C);
2186 * \brief Given a cursor that represents a template, determine
2187 * the cursor kind of the specializations would be generated by instantiating
2190 * This routine can be used to determine what flavor of function template,
2191 * class template, or class template partial specialization is stored in the
2192 * cursor. For example, it can describe whether a class template cursor is
2193 * declared with "struct", "class" or "union".
2195 * \param C The cursor to query. This cursor should represent a template
2198 * \returns The cursor kind of the specializations that would be generated
2199 * by instantiating the template \p C. If \p C is not a template, returns
2200 * \c CXCursor_NoDeclFound.
2202 CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C);
2205 * \brief Given a cursor that may represent a specialization or instantiation
2206 * of a template, retrieve the cursor that represents the template that it
2207 * specializes or from which it was instantiated.
2209 * This routine determines the template involved both for explicit
2210 * specializations of templates and for implicit instantiations of the template,
2211 * both of which are referred to as "specializations". For a class template
2212 * specialization (e.g., \c std::vector<bool>), this routine will return
2213 * either the primary template (\c std::vector) or, if the specialization was
2214 * instantiated from a class template partial specialization, the class template
2215 * partial specialization. For a class template partial specialization and a
2216 * function template specialization (including instantiations), this
2217 * this routine will return the specialized template.
2219 * For members of a class template (e.g., member functions, member classes, or
2220 * static data members), returns the specialized or instantiated member.
2221 * Although not strictly "templates" in the C++ language, members of class
2222 * templates have the same notions of specializations and instantiations that
2223 * templates do, so this routine treats them similarly.
2225 * \param C A cursor that may be a specialization of a template or a member
2228 * \returns If the given cursor is a specialization or instantiation of a
2229 * template or a member thereof, the template or member that it specializes or
2230 * from which it was instantiated. Otherwise, returns a NULL cursor.
2232 CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C);
2239 * \defgroup CINDEX_LEX Token extraction and manipulation
2241 * The routines in this group provide access to the tokens within a
2242 * translation unit, along with a semantic mapping of those tokens to
2243 * their corresponding cursors.
2249 * \brief Describes a kind of token.
2251 typedef enum CXTokenKind {
2253 * \brief A token that contains some kind of punctuation.
2255 CXToken_Punctuation,
2258 * \brief A language keyword.
2263 * \brief An identifier (that is not a keyword).
2268 * \brief A numeric, string, or character literal.
2279 * \brief Describes a single preprocessing token.
2282 unsigned int_data[4];
2287 * \brief Determine the kind of the given token.
2289 CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken);
2292 * \brief Determine the spelling of the given token.
2294 * The spelling of a token is the textual representation of that token, e.g.,
2295 * the text of an identifier or keyword.
2297 CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken);
2300 * \brief Retrieve the source location of the given token.
2302 CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit,
2306 * \brief Retrieve a source range that covers the given token.
2308 CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken);
2311 * \brief Tokenize the source code described by the given range into raw
2314 * \param TU the translation unit whose text is being tokenized.
2316 * \param Range the source range in which text should be tokenized. All of the
2317 * tokens produced by tokenization will fall within this source range,
2319 * \param Tokens this pointer will be set to point to the array of tokens
2320 * that occur within the given source range. The returned pointer must be
2321 * freed with clang_disposeTokens() before the translation unit is destroyed.
2323 * \param NumTokens will be set to the number of tokens in the \c *Tokens
2327 CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range,
2328 CXToken **Tokens, unsigned *NumTokens);
2331 * \brief Annotate the given set of tokens by providing cursors for each token
2332 * that can be mapped to a specific entity within the abstract syntax tree.
2334 * This token-annotation routine is equivalent to invoking
2335 * clang_getCursor() for the source locations of each of the
2336 * tokens. The cursors provided are filtered, so that only those
2337 * cursors that have a direct correspondence to the token are
2338 * accepted. For example, given a function call \c f(x),
2339 * clang_getCursor() would provide the following cursors:
2341 * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
2342 * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
2343 * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
2345 * Only the first and last of these cursors will occur within the
2346 * annotate, since the tokens "f" and "x' directly refer to a function
2347 * and a variable, respectively, but the parentheses are just a small
2348 * part of the full syntax of the function call expression, which is
2349 * not provided as an annotation.
2351 * \param TU the translation unit that owns the given tokens.
2353 * \param Tokens the set of tokens to annotate.
2355 * \param NumTokens the number of tokens in \p Tokens.
2357 * \param Cursors an array of \p NumTokens cursors, whose contents will be
2358 * replaced with the cursors corresponding to each token.
2360 CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU,
2361 CXToken *Tokens, unsigned NumTokens,
2365 * \brief Free the given set of tokens.
2367 CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU,
2368 CXToken *Tokens, unsigned NumTokens);
2375 * \defgroup CINDEX_DEBUG Debugging facilities
2377 * These routines are used for testing and debugging, only, and should not
2383 /* for debug/testing */
2384 CINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind);
2385 CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor,
2386 const char **startBuf,
2387 const char **endBuf,
2388 unsigned *startLine,
2389 unsigned *startColumn,
2391 unsigned *endColumn);
2392 CINDEX_LINKAGE void clang_enableStackTraces(void);
2393 CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data,
2394 unsigned stack_size);
2401 * \defgroup CINDEX_CODE_COMPLET Code completion
2403 * Code completion involves taking an (incomplete) source file, along with
2404 * knowledge of where the user is actively editing that file, and suggesting
2405 * syntactically- and semantically-valid constructs that the user might want to
2406 * use at that particular point in the source code. These data structures and
2407 * routines provide support for code completion.
2413 * \brief A semantic string that describes a code-completion result.
2415 * A semantic string that describes the formatting of a code-completion
2416 * result as a single "template" of text that should be inserted into the
2417 * source buffer when a particular code-completion result is selected.
2418 * Each semantic string is made up of some number of "chunks", each of which
2419 * contains some text along with a description of what that text means, e.g.,
2420 * the name of the entity being referenced, whether the text chunk is part of
2421 * the template, or whether it is a "placeholder" that the user should replace
2422 * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
2423 * description of the different kinds of chunks.
2425 typedef void *CXCompletionString;
2428 * \brief A single result of code completion.
2432 * \brief The kind of entity that this completion refers to.
2434 * The cursor kind will be a macro, keyword, or a declaration (one of the
2435 * *Decl cursor kinds), describing the entity that the completion is
2438 * \todo In the future, we would like to provide a full cursor, to allow
2439 * the client to extract additional information from declaration.
2441 enum CXCursorKind CursorKind;
2444 * \brief The code-completion string that describes how to insert this
2445 * code-completion result into the editing buffer.
2447 CXCompletionString CompletionString;
2448 } CXCompletionResult;
2451 * \brief Describes a single piece of text within a code-completion string.
2453 * Each "chunk" within a code-completion string (\c CXCompletionString) is
2454 * either a piece of text with a specific "kind" that describes how that text
2455 * should be interpreted by the client or is another completion string.
2457 enum CXCompletionChunkKind {
2459 * \brief A code-completion string that describes "optional" text that
2460 * could be a part of the template (but is not required).
2462 * The Optional chunk is the only kind of chunk that has a code-completion
2463 * string for its representation, which is accessible via
2464 * \c clang_getCompletionChunkCompletionString(). The code-completion string
2465 * describes an additional part of the template that is completely optional.
2466 * For example, optional chunks can be used to describe the placeholders for
2467 * arguments that match up with defaulted function parameters, e.g. given:
2470 * void f(int x, float y = 3.14, double z = 2.71828);
2473 * The code-completion string for this function would contain:
2474 * - a TypedText chunk for "f".
2475 * - a LeftParen chunk for "(".
2476 * - a Placeholder chunk for "int x"
2477 * - an Optional chunk containing the remaining defaulted arguments, e.g.,
2478 * - a Comma chunk for ","
2479 * - a Placeholder chunk for "float y"
2480 * - an Optional chunk containing the last defaulted argument:
2481 * - a Comma chunk for ","
2482 * - a Placeholder chunk for "double z"
2483 * - a RightParen chunk for ")"
2485 * There are many ways to handle Optional chunks. Two simple approaches are:
2486 * - Completely ignore optional chunks, in which case the template for the
2487 * function "f" would only include the first parameter ("int x").
2488 * - Fully expand all optional chunks, in which case the template for the
2489 * function "f" would have all of the parameters.
2491 CXCompletionChunk_Optional,
2493 * \brief Text that a user would be expected to type to get this
2494 * code-completion result.
2496 * There will be exactly one "typed text" chunk in a semantic string, which
2497 * will typically provide the spelling of a keyword or the name of a
2498 * declaration that could be used at the current code point. Clients are
2499 * expected to filter the code-completion results based on the text in this
2502 CXCompletionChunk_TypedText,
2504 * \brief Text that should be inserted as part of a code-completion result.
2506 * A "text" chunk represents text that is part of the template to be
2507 * inserted into user code should this particular code-completion result
2510 CXCompletionChunk_Text,
2512 * \brief Placeholder text that should be replaced by the user.
2514 * A "placeholder" chunk marks a place where the user should insert text
2515 * into the code-completion template. For example, placeholders might mark
2516 * the function parameters for a function declaration, to indicate that the
2517 * user should provide arguments for each of those parameters. The actual
2518 * text in a placeholder is a suggestion for the text to display before
2519 * the user replaces the placeholder with real code.
2521 CXCompletionChunk_Placeholder,
2523 * \brief Informative text that should be displayed but never inserted as
2524 * part of the template.
2526 * An "informative" chunk contains annotations that can be displayed to
2527 * help the user decide whether a particular code-completion result is the
2528 * right option, but which is not part of the actual template to be inserted
2529 * by code completion.
2531 CXCompletionChunk_Informative,
2533 * \brief Text that describes the current parameter when code-completion is
2534 * referring to function call, message send, or template specialization.
2536 * A "current parameter" chunk occurs when code-completion is providing
2537 * information about a parameter corresponding to the argument at the
2538 * code-completion point. For example, given a function
2541 * int add(int x, int y);
2544 * and the source code \c add(, where the code-completion point is after the
2545 * "(", the code-completion string will contain a "current parameter" chunk
2546 * for "int x", indicating that the current argument will initialize that
2547 * parameter. After typing further, to \c add(17, (where the code-completion
2548 * point is after the ","), the code-completion string will contain a
2549 * "current paremeter" chunk to "int y".
2551 CXCompletionChunk_CurrentParameter,
2553 * \brief A left parenthesis ('('), used to initiate a function call or
2554 * signal the beginning of a function parameter list.
2556 CXCompletionChunk_LeftParen,
2558 * \brief A right parenthesis (')'), used to finish a function call or
2559 * signal the end of a function parameter list.
2561 CXCompletionChunk_RightParen,
2563 * \brief A left bracket ('[').
2565 CXCompletionChunk_LeftBracket,
2567 * \brief A right bracket (']').
2569 CXCompletionChunk_RightBracket,
2571 * \brief A left brace ('{').
2573 CXCompletionChunk_LeftBrace,
2575 * \brief A right brace ('}').
2577 CXCompletionChunk_RightBrace,
2579 * \brief A left angle bracket ('<').
2581 CXCompletionChunk_LeftAngle,
2583 * \brief A right angle bracket ('>').
2585 CXCompletionChunk_RightAngle,
2587 * \brief A comma separator (',').
2589 CXCompletionChunk_Comma,
2591 * \brief Text that specifies the result type of a given result.
2593 * This special kind of informative chunk is not meant to be inserted into
2594 * the text buffer. Rather, it is meant to illustrate the type that an
2595 * expression using the given completion string would have.
2597 CXCompletionChunk_ResultType,
2599 * \brief A colon (':').
2601 CXCompletionChunk_Colon,
2603 * \brief A semicolon (';').
2605 CXCompletionChunk_SemiColon,
2607 * \brief An '=' sign.
2609 CXCompletionChunk_Equal,
2611 * Horizontal space (' ').
2613 CXCompletionChunk_HorizontalSpace,
2615 * Vertical space ('\n'), after which it is generally a good idea to
2616 * perform indentation.
2618 CXCompletionChunk_VerticalSpace
2622 * \brief Determine the kind of a particular chunk within a completion string.
2624 * \param completion_string the completion string to query.
2626 * \param chunk_number the 0-based index of the chunk in the completion string.
2628 * \returns the kind of the chunk at the index \c chunk_number.
2630 CINDEX_LINKAGE enum CXCompletionChunkKind
2631 clang_getCompletionChunkKind(CXCompletionString completion_string,
2632 unsigned chunk_number);
2635 * \brief Retrieve the text associated with a particular chunk within a
2636 * completion string.
2638 * \param completion_string the completion string to query.
2640 * \param chunk_number the 0-based index of the chunk in the completion string.
2642 * \returns the text associated with the chunk at index \c chunk_number.
2644 CINDEX_LINKAGE CXString
2645 clang_getCompletionChunkText(CXCompletionString completion_string,
2646 unsigned chunk_number);
2649 * \brief Retrieve the completion string associated with a particular chunk
2650 * within a completion string.
2652 * \param completion_string the completion string to query.
2654 * \param chunk_number the 0-based index of the chunk in the completion string.
2656 * \returns the completion string associated with the chunk at index
2657 * \c chunk_number, or NULL if that chunk is not represented by a completion
2660 CINDEX_LINKAGE CXCompletionString
2661 clang_getCompletionChunkCompletionString(CXCompletionString completion_string,
2662 unsigned chunk_number);
2665 * \brief Retrieve the number of chunks in the given code-completion string.
2667 CINDEX_LINKAGE unsigned
2668 clang_getNumCompletionChunks(CXCompletionString completion_string);
2671 * \brief Determine the priority of this code completion.
2673 * The priority of a code completion indicates how likely it is that this
2674 * particular completion is the completion that the user will select. The
2675 * priority is selected by various internal heuristics.
2677 * \param completion_string The completion string to query.
2679 * \returns The priority of this completion string. Smaller values indicate
2680 * higher-priority (more likely) completions.
2682 CINDEX_LINKAGE unsigned
2683 clang_getCompletionPriority(CXCompletionString completion_string);
2686 * \brief Determine the availability of the entity that this code-completion
2689 * \param completion_string The completion string to query.
2691 * \returns The availability of the completion string.
2693 CINDEX_LINKAGE enum CXAvailabilityKind
2694 clang_getCompletionAvailability(CXCompletionString completion_string);
2697 * \brief Contains the results of code-completion.
2699 * This data structure contains the results of code completion, as
2700 * produced by \c clang_codeCompleteAt(). Its contents must be freed by
2701 * \c clang_disposeCodeCompleteResults.
2705 * \brief The code-completion results.
2707 CXCompletionResult *Results;
2710 * \brief The number of code-completion results stored in the
2713 unsigned NumResults;
2714 } CXCodeCompleteResults;
2717 * \brief Flags that can be passed to \c clang_codeCompleteAt() to
2718 * modify its behavior.
2720 * The enumerators in this enumeration can be bitwise-OR'd together to
2721 * provide multiple options to \c clang_codeCompleteAt().
2723 enum CXCodeComplete_Flags {
2725 * \brief Whether to include macros within the set of code
2726 * completions returned.
2728 CXCodeComplete_IncludeMacros = 0x01,
2731 * \brief Whether to include code patterns for language constructs
2732 * within the set of code completions, e.g., for loops.
2734 CXCodeComplete_IncludeCodePatterns = 0x02
2738 * \brief Returns a default set of code-completion options that can be
2739 * passed to\c clang_codeCompleteAt().
2741 CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void);
2744 * \brief Perform code completion at a given location in a translation unit.
2746 * This function performs code completion at a particular file, line, and
2747 * column within source code, providing results that suggest potential
2748 * code snippets based on the context of the completion. The basic model
2749 * for code completion is that Clang will parse a complete source file,
2750 * performing syntax checking up to the location where code-completion has
2751 * been requested. At that point, a special code-completion token is passed
2752 * to the parser, which recognizes this token and determines, based on the
2753 * current location in the C/Objective-C/C++ grammar and the state of
2754 * semantic analysis, what completions to provide. These completions are
2755 * returned via a new \c CXCodeCompleteResults structure.
2757 * Code completion itself is meant to be triggered by the client when the
2758 * user types punctuation characters or whitespace, at which point the
2759 * code-completion location will coincide with the cursor. For example, if \c p
2760 * is a pointer, code-completion might be triggered after the "-" and then
2761 * after the ">" in \c p->. When the code-completion location is afer the ">",
2762 * the completion results will provide, e.g., the members of the struct that
2763 * "p" points to. The client is responsible for placing the cursor at the
2764 * beginning of the token currently being typed, then filtering the results
2765 * based on the contents of the token. For example, when code-completing for
2766 * the expression \c p->get, the client should provide the location just after
2767 * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
2768 * client can filter the results based on the current token text ("get"), only
2769 * showing those results that start with "get". The intent of this interface
2770 * is to separate the relatively high-latency acquisition of code-completion
2771 * results from the filtering of results on a per-character basis, which must
2772 * have a lower latency.
2774 * \param TU The translation unit in which code-completion should
2775 * occur. The source files for this translation unit need not be
2776 * completely up-to-date (and the contents of those source files may
2777 * be overridden via \p unsaved_files). Cursors referring into the
2778 * translation unit may be invalidated by this invocation.
2780 * \param complete_filename The name of the source file where code
2781 * completion should be performed. This filename may be any file
2782 * included in the translation unit.
2784 * \param complete_line The line at which code-completion should occur.
2786 * \param complete_column The column at which code-completion should occur.
2787 * Note that the column should point just after the syntactic construct that
2788 * initiated code completion, and not in the middle of a lexical token.
2790 * \param unsaved_files the Tiles that have not yet been saved to disk
2791 * but may be required for parsing or code completion, including the
2792 * contents of those files. The contents and name of these files (as
2793 * specified by CXUnsavedFile) are copied when necessary, so the
2794 * client only needs to guarantee their validity until the call to
2795 * this function returns.
2797 * \param num_unsaved_files The number of unsaved file entries in \p
2800 * \param options Extra options that control the behavior of code
2801 * completion, expressed as a bitwise OR of the enumerators of the
2802 * CXCodeComplete_Flags enumeration. The
2803 * \c clang_defaultCodeCompleteOptions() function returns a default set
2804 * of code-completion options.
2806 * \returns If successful, a new \c CXCodeCompleteResults structure
2807 * containing code-completion results, which should eventually be
2808 * freed with \c clang_disposeCodeCompleteResults(). If code
2809 * completion fails, returns NULL.
2812 CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU,
2813 const char *complete_filename,
2814 unsigned complete_line,
2815 unsigned complete_column,
2816 struct CXUnsavedFile *unsaved_files,
2817 unsigned num_unsaved_files,
2821 * \brief Sort the code-completion results in case-insensitive alphabetical
2824 * \param Results The set of results to sort.
2825 * \param NumResults The number of results in \p Results.
2828 void clang_sortCodeCompletionResults(CXCompletionResult *Results,
2829 unsigned NumResults);
2832 * \brief Free the given set of code-completion results.
2835 void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results);
2838 * \brief Determine the number of diagnostics produced prior to the
2839 * location where code completion was performed.
2842 unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results);
2845 * \brief Retrieve a diagnostic associated with the given code completion.
2847 * \param Result the code completion results to query.
2848 * \param Index the zero-based diagnostic number to retrieve.
2850 * \returns the requested diagnostic. This diagnostic must be freed
2851 * via a call to \c clang_disposeDiagnostic().
2854 CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results,
2863 * \defgroup CINDEX_MISC Miscellaneous utility functions
2869 * \brief Return a version string, suitable for showing to a user, but not
2870 * intended to be parsed (the format is not guaranteed to be stable).
2872 CINDEX_LINKAGE CXString clang_getClangVersion();
2875 * \brief Visitor invoked for each file in a translation unit
2876 * (used with clang_getInclusions()).
2878 * This visitor function will be invoked by clang_getInclusions() for each
2879 * file included (either at the top-level or by #include directives) within
2880 * a translation unit. The first argument is the file being included, and
2881 * the second and third arguments provide the inclusion stack. The
2882 * array is sorted in order of immediate inclusion. For example,
2883 * the first element refers to the location that included 'included_file'.
2885 typedef void (*CXInclusionVisitor)(CXFile included_file,
2886 CXSourceLocation* inclusion_stack,
2887 unsigned include_len,
2888 CXClientData client_data);
2891 * \brief Visit the set of preprocessor inclusions in a translation unit.
2892 * The visitor function is called with the provided data for every included
2893 * file. This does not include headers included by the PCH file (unless one
2894 * is inspecting the inclusions in the PCH file itself).
2896 CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu,
2897 CXInclusionVisitor visitor,
2898 CXClientData client_data);