Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

Rev

Blame | Last modification | View Log | Download | RSS feed

  1. /*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
  2. |*                                                                            *|
  3. |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
  4. |* Exceptions.                                                                *|
  5. |* See https://llvm.org/LICENSE.txt for license information.                  *|
  6. |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
  7. |*                                                                            *|
  8. |*===----------------------------------------------------------------------===*|
  9. |*                                                                            *|
  10. |* This header provides a public interface to a Clang library for extracting  *|
  11. |* high-level symbol information from source files without exposing the full  *|
  12. |* Clang C++ API.                                                             *|
  13. |*                                                                            *|
  14. \*===----------------------------------------------------------------------===*/
  15.  
  16. #ifndef LLVM_CLANG_C_INDEX_H
  17. #define LLVM_CLANG_C_INDEX_H
  18.  
  19. #include "clang-c/BuildSystem.h"
  20. #include "clang-c/CXDiagnostic.h"
  21. #include "clang-c/CXErrorCode.h"
  22. #include "clang-c/CXFile.h"
  23. #include "clang-c/CXSourceLocation.h"
  24. #include "clang-c/CXString.h"
  25. #include "clang-c/ExternC.h"
  26. #include "clang-c/Platform.h"
  27.  
  28. /**
  29.  * The version constants for the libclang API.
  30.  * CINDEX_VERSION_MINOR should increase when there are API additions.
  31.  * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes.
  32.  *
  33.  * The policy about the libclang API was always to keep it source and ABI
  34.  * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable.
  35.  */
  36. #define CINDEX_VERSION_MAJOR 0
  37. #define CINDEX_VERSION_MINOR 63
  38.  
  39. #define CINDEX_VERSION_ENCODE(major, minor) (((major)*10000) + ((minor)*1))
  40.  
  41. #define CINDEX_VERSION                                                         \
  42.   CINDEX_VERSION_ENCODE(CINDEX_VERSION_MAJOR, CINDEX_VERSION_MINOR)
  43.  
  44. #define CINDEX_VERSION_STRINGIZE_(major, minor) #major "." #minor
  45. #define CINDEX_VERSION_STRINGIZE(major, minor)                                 \
  46.   CINDEX_VERSION_STRINGIZE_(major, minor)
  47.  
  48. #define CINDEX_VERSION_STRING                                                  \
  49.   CINDEX_VERSION_STRINGIZE(CINDEX_VERSION_MAJOR, CINDEX_VERSION_MINOR)
  50.  
  51. LLVM_CLANG_C_EXTERN_C_BEGIN
  52.  
  53. /** \defgroup CINDEX libclang: C Interface to Clang
  54.  *
  55.  * The C Interface to Clang provides a relatively small API that exposes
  56.  * facilities for parsing source code into an abstract syntax tree (AST),
  57.  * loading already-parsed ASTs, traversing the AST, associating
  58.  * physical source locations with elements within the AST, and other
  59.  * facilities that support Clang-based development tools.
  60.  *
  61.  * This C interface to Clang will never provide all of the information
  62.  * representation stored in Clang's C++ AST, nor should it: the intent is to
  63.  * maintain an API that is relatively stable from one release to the next,
  64.  * providing only the basic functionality needed to support development tools.
  65.  *
  66.  * To avoid namespace pollution, data types are prefixed with "CX" and
  67.  * functions are prefixed with "clang_".
  68.  *
  69.  * @{
  70.  */
  71.  
  72. /**
  73.  * An "index" that consists of a set of translation units that would
  74.  * typically be linked together into an executable or library.
  75.  */
  76. typedef void *CXIndex;
  77.  
  78. /**
  79.  * An opaque type representing target information for a given translation
  80.  * unit.
  81.  */
  82. typedef struct CXTargetInfoImpl *CXTargetInfo;
  83.  
  84. /**
  85.  * A single translation unit, which resides in an index.
  86.  */
  87. typedef struct CXTranslationUnitImpl *CXTranslationUnit;
  88.  
  89. /**
  90.  * Opaque pointer representing client data that will be passed through
  91.  * to various callbacks and visitors.
  92.  */
  93. typedef void *CXClientData;
  94.  
  95. /**
  96.  * Provides the contents of a file that has not yet been saved to disk.
  97.  *
  98.  * Each CXUnsavedFile instance provides the name of a file on the
  99.  * system along with the current contents of that file that have not
  100.  * yet been saved to disk.
  101.  */
  102. struct CXUnsavedFile {
  103.   /**
  104.    * The file whose contents have not yet been saved.
  105.    *
  106.    * This file must already exist in the file system.
  107.    */
  108.   const char *Filename;
  109.  
  110.   /**
  111.    * A buffer containing the unsaved contents of this file.
  112.    */
  113.   const char *Contents;
  114.  
  115.   /**
  116.    * The length of the unsaved contents of this buffer.
  117.    */
  118.   unsigned long Length;
  119. };
  120.  
  121. /**
  122.  * Describes the availability of a particular entity, which indicates
  123.  * whether the use of this entity will result in a warning or error due to
  124.  * it being deprecated or unavailable.
  125.  */
  126. enum CXAvailabilityKind {
  127.   /**
  128.    * The entity is available.
  129.    */
  130.   CXAvailability_Available,
  131.   /**
  132.    * The entity is available, but has been deprecated (and its use is
  133.    * not recommended).
  134.    */
  135.   CXAvailability_Deprecated,
  136.   /**
  137.    * The entity is not available; any use of it will be an error.
  138.    */
  139.   CXAvailability_NotAvailable,
  140.   /**
  141.    * The entity is available, but not accessible; any use of it will be
  142.    * an error.
  143.    */
  144.   CXAvailability_NotAccessible
  145. };
  146.  
  147. /**
  148.  * Describes a version number of the form major.minor.subminor.
  149.  */
  150. typedef struct CXVersion {
  151.   /**
  152.    * The major version number, e.g., the '10' in '10.7.3'. A negative
  153.    * value indicates that there is no version number at all.
  154.    */
  155.   int Major;
  156.   /**
  157.    * The minor version number, e.g., the '7' in '10.7.3'. This value
  158.    * will be negative if no minor version number was provided, e.g., for
  159.    * version '10'.
  160.    */
  161.   int Minor;
  162.   /**
  163.    * The subminor version number, e.g., the '3' in '10.7.3'. This value
  164.    * will be negative if no minor or subminor version number was provided,
  165.    * e.g., in version '10' or '10.7'.
  166.    */
  167.   int Subminor;
  168. } CXVersion;
  169.  
  170. /**
  171.  * Describes the exception specification of a cursor.
  172.  *
  173.  * A negative value indicates that the cursor is not a function declaration.
  174.  */
  175. enum CXCursor_ExceptionSpecificationKind {
  176.   /**
  177.    * The cursor has no exception specification.
  178.    */
  179.   CXCursor_ExceptionSpecificationKind_None,
  180.  
  181.   /**
  182.    * The cursor has exception specification throw()
  183.    */
  184.   CXCursor_ExceptionSpecificationKind_DynamicNone,
  185.  
  186.   /**
  187.    * The cursor has exception specification throw(T1, T2)
  188.    */
  189.   CXCursor_ExceptionSpecificationKind_Dynamic,
  190.  
  191.   /**
  192.    * The cursor has exception specification throw(...).
  193.    */
  194.   CXCursor_ExceptionSpecificationKind_MSAny,
  195.  
  196.   /**
  197.    * The cursor has exception specification basic noexcept.
  198.    */
  199.   CXCursor_ExceptionSpecificationKind_BasicNoexcept,
  200.  
  201.   /**
  202.    * The cursor has exception specification computed noexcept.
  203.    */
  204.   CXCursor_ExceptionSpecificationKind_ComputedNoexcept,
  205.  
  206.   /**
  207.    * The exception specification has not yet been evaluated.
  208.    */
  209.   CXCursor_ExceptionSpecificationKind_Unevaluated,
  210.  
  211.   /**
  212.    * The exception specification has not yet been instantiated.
  213.    */
  214.   CXCursor_ExceptionSpecificationKind_Uninstantiated,
  215.  
  216.   /**
  217.    * The exception specification has not been parsed yet.
  218.    */
  219.   CXCursor_ExceptionSpecificationKind_Unparsed,
  220.  
  221.   /**
  222.    * The cursor has a __declspec(nothrow) exception specification.
  223.    */
  224.   CXCursor_ExceptionSpecificationKind_NoThrow
  225. };
  226.  
  227. /**
  228.  * Provides a shared context for creating translation units.
  229.  *
  230.  * It provides two options:
  231.  *
  232.  * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
  233.  * declarations (when loading any new translation units). A "local" declaration
  234.  * is one that belongs in the translation unit itself and not in a precompiled
  235.  * header that was used by the translation unit. If zero, all declarations
  236.  * will be enumerated.
  237.  *
  238.  * Here is an example:
  239.  *
  240.  * \code
  241.  *   // excludeDeclsFromPCH = 1, displayDiagnostics=1
  242.  *   Idx = clang_createIndex(1, 1);
  243.  *
  244.  *   // IndexTest.pch was produced with the following command:
  245.  *   // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
  246.  *   TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
  247.  *
  248.  *   // This will load all the symbols from 'IndexTest.pch'
  249.  *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
  250.  *                       TranslationUnitVisitor, 0);
  251.  *   clang_disposeTranslationUnit(TU);
  252.  *
  253.  *   // This will load all the symbols from 'IndexTest.c', excluding symbols
  254.  *   // from 'IndexTest.pch'.
  255.  *   char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
  256.  *   TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
  257.  *                                                  0, 0);
  258.  *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
  259.  *                       TranslationUnitVisitor, 0);
  260.  *   clang_disposeTranslationUnit(TU);
  261.  * \endcode
  262.  *
  263.  * This process of creating the 'pch', loading it separately, and using it (via
  264.  * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
  265.  * (which gives the indexer the same performance benefit as the compiler).
  266.  */
  267. CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
  268.                                          int displayDiagnostics);
  269.  
  270. /**
  271.  * Destroy the given index.
  272.  *
  273.  * The index must not be destroyed until all of the translation units created
  274.  * within that index have been destroyed.
  275.  */
  276. CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
  277.  
  278. typedef enum {
  279.   /**
  280.    * Used to indicate that no special CXIndex options are needed.
  281.    */
  282.   CXGlobalOpt_None = 0x0,
  283.  
  284.   /**
  285.    * Used to indicate that threads that libclang creates for indexing
  286.    * purposes should use background priority.
  287.    *
  288.    * Affects #clang_indexSourceFile, #clang_indexTranslationUnit,
  289.    * #clang_parseTranslationUnit, #clang_saveTranslationUnit.
  290.    */
  291.   CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1,
  292.  
  293.   /**
  294.    * Used to indicate that threads that libclang creates for editing
  295.    * purposes should use background priority.
  296.    *
  297.    * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt,
  298.    * #clang_annotateTokens
  299.    */
  300.   CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2,
  301.  
  302.   /**
  303.    * Used to indicate that all threads that libclang creates should use
  304.    * background priority.
  305.    */
  306.   CXGlobalOpt_ThreadBackgroundPriorityForAll =
  307.       CXGlobalOpt_ThreadBackgroundPriorityForIndexing |
  308.       CXGlobalOpt_ThreadBackgroundPriorityForEditing
  309.  
  310. } CXGlobalOptFlags;
  311.  
  312. /**
  313.  * Sets general options associated with a CXIndex.
  314.  *
  315.  * For example:
  316.  * \code
  317.  * CXIndex idx = ...;
  318.  * clang_CXIndex_setGlobalOptions(idx,
  319.  *     clang_CXIndex_getGlobalOptions(idx) |
  320.  *     CXGlobalOpt_ThreadBackgroundPriorityForIndexing);
  321.  * \endcode
  322.  *
  323.  * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags.
  324.  */
  325. CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options);
  326.  
  327. /**
  328.  * Gets the general options associated with a CXIndex.
  329.  *
  330.  * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that
  331.  * are associated with the given CXIndex object.
  332.  */
  333. CINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex);
  334.  
  335. /**
  336.  * Sets the invocation emission path option in a CXIndex.
  337.  *
  338.  * The invocation emission path specifies a path which will contain log
  339.  * files for certain libclang invocations. A null value (default) implies that
  340.  * libclang invocations are not logged..
  341.  */
  342. CINDEX_LINKAGE void
  343. clang_CXIndex_setInvocationEmissionPathOption(CXIndex, const char *Path);
  344.  
  345. /**
  346.  * Determine whether the given header is guarded against
  347.  * multiple inclusions, either with the conventional
  348.  * \#ifndef/\#define/\#endif macro guards or with \#pragma once.
  349.  */
  350. CINDEX_LINKAGE unsigned clang_isFileMultipleIncludeGuarded(CXTranslationUnit tu,
  351.                                                            CXFile file);
  352.  
  353. /**
  354.  * Retrieve a file handle within the given translation unit.
  355.  *
  356.  * \param tu the translation unit
  357.  *
  358.  * \param file_name the name of the file.
  359.  *
  360.  * \returns the file handle for the named file in the translation unit \p tu,
  361.  * or a NULL file handle if the file was not a part of this translation unit.
  362.  */
  363. CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu,
  364.                                     const char *file_name);
  365.  
  366. /**
  367.  * Retrieve the buffer associated with the given file.
  368.  *
  369.  * \param tu the translation unit
  370.  *
  371.  * \param file the file for which to retrieve the buffer.
  372.  *
  373.  * \param size [out] if non-NULL, will be set to the size of the buffer.
  374.  *
  375.  * \returns a pointer to the buffer in memory that holds the contents of
  376.  * \p file, or a NULL pointer when the file is not loaded.
  377.  */
  378. CINDEX_LINKAGE const char *clang_getFileContents(CXTranslationUnit tu,
  379.                                                  CXFile file, size_t *size);
  380.  
  381. /**
  382.  * Retrieves the source location associated with a given file/line/column
  383.  * in a particular translation unit.
  384.  */
  385. CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu,
  386.                                                   CXFile file, unsigned line,
  387.                                                   unsigned column);
  388. /**
  389.  * Retrieves the source location associated with a given character offset
  390.  * in a particular translation unit.
  391.  */
  392. CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu,
  393.                                                            CXFile file,
  394.                                                            unsigned offset);
  395.  
  396. /**
  397.  * Retrieve all ranges that were skipped by the preprocessor.
  398.  *
  399.  * The preprocessor will skip lines when they are surrounded by an
  400.  * if/ifdef/ifndef directive whose condition does not evaluate to true.
  401.  */
  402. CINDEX_LINKAGE CXSourceRangeList *clang_getSkippedRanges(CXTranslationUnit tu,
  403.                                                          CXFile file);
  404.  
  405. /**
  406.  * Retrieve all ranges from all files that were skipped by the
  407.  * preprocessor.
  408.  *
  409.  * The preprocessor will skip lines when they are surrounded by an
  410.  * if/ifdef/ifndef directive whose condition does not evaluate to true.
  411.  */
  412. CINDEX_LINKAGE CXSourceRangeList *
  413. clang_getAllSkippedRanges(CXTranslationUnit tu);
  414.  
  415. /**
  416.  * Determine the number of diagnostics produced for the given
  417.  * translation unit.
  418.  */
  419. CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit);
  420.  
  421. /**
  422.  * Retrieve a diagnostic associated with the given translation unit.
  423.  *
  424.  * \param Unit the translation unit to query.
  425.  * \param Index the zero-based diagnostic number to retrieve.
  426.  *
  427.  * \returns the requested diagnostic. This diagnostic must be freed
  428.  * via a call to \c clang_disposeDiagnostic().
  429.  */
  430. CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit,
  431.                                                 unsigned Index);
  432.  
  433. /**
  434.  * Retrieve the complete set of diagnostics associated with a
  435.  *        translation unit.
  436.  *
  437.  * \param Unit the translation unit to query.
  438.  */
  439. CINDEX_LINKAGE CXDiagnosticSet
  440. clang_getDiagnosticSetFromTU(CXTranslationUnit Unit);
  441.  
  442. /**
  443.  * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
  444.  *
  445.  * The routines in this group provide the ability to create and destroy
  446.  * translation units from files, either by parsing the contents of the files or
  447.  * by reading in a serialized representation of a translation unit.
  448.  *
  449.  * @{
  450.  */
  451.  
  452. /**
  453.  * Get the original translation unit source file name.
  454.  */
  455. CINDEX_LINKAGE CXString
  456. clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
  457.  
  458. /**
  459.  * Return the CXTranslationUnit for a given source file and the provided
  460.  * command line arguments one would pass to the compiler.
  461.  *
  462.  * Note: The 'source_filename' argument is optional.  If the caller provides a
  463.  * NULL pointer, the name of the source file is expected to reside in the
  464.  * specified command line arguments.
  465.  *
  466.  * Note: When encountered in 'clang_command_line_args', the following options
  467.  * are ignored:
  468.  *
  469.  *   '-c'
  470.  *   '-emit-ast'
  471.  *   '-fsyntax-only'
  472.  *   '-o \<output file>'  (both '-o' and '\<output file>' are ignored)
  473.  *
  474.  * \param CIdx The index object with which the translation unit will be
  475.  * associated.
  476.  *
  477.  * \param source_filename The name of the source file to load, or NULL if the
  478.  * source file is included in \p clang_command_line_args.
  479.  *
  480.  * \param num_clang_command_line_args The number of command-line arguments in
  481.  * \p clang_command_line_args.
  482.  *
  483.  * \param clang_command_line_args The command-line arguments that would be
  484.  * passed to the \c clang executable if it were being invoked out-of-process.
  485.  * These command-line options will be parsed and will affect how the translation
  486.  * unit is parsed. Note that the following options are ignored: '-c',
  487.  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'.
  488.  *
  489.  * \param num_unsaved_files the number of unsaved file entries in \p
  490.  * unsaved_files.
  491.  *
  492.  * \param unsaved_files the files that have not yet been saved to disk
  493.  * but may be required for code completion, including the contents of
  494.  * those files.  The contents and name of these files (as specified by
  495.  * CXUnsavedFile) are copied when necessary, so the client only needs to
  496.  * guarantee their validity until the call to this function returns.
  497.  */
  498. CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
  499.     CXIndex CIdx, const char *source_filename, int num_clang_command_line_args,
  500.     const char *const *clang_command_line_args, unsigned num_unsaved_files,
  501.     struct CXUnsavedFile *unsaved_files);
  502.  
  503. /**
  504.  * Same as \c clang_createTranslationUnit2, but returns
  505.  * the \c CXTranslationUnit instead of an error code.  In case of an error this
  506.  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
  507.  * error codes.
  508.  */
  509. CINDEX_LINKAGE CXTranslationUnit
  510. clang_createTranslationUnit(CXIndex CIdx, const char *ast_filename);
  511.  
  512. /**
  513.  * Create a translation unit from an AST file (\c -emit-ast).
  514.  *
  515.  * \param[out] out_TU A non-NULL pointer to store the created
  516.  * \c CXTranslationUnit.
  517.  *
  518.  * \returns Zero on success, otherwise returns an error code.
  519.  */
  520. CINDEX_LINKAGE enum CXErrorCode
  521. clang_createTranslationUnit2(CXIndex CIdx, const char *ast_filename,
  522.                              CXTranslationUnit *out_TU);
  523.  
  524. /**
  525.  * Flags that control the creation of translation units.
  526.  *
  527.  * The enumerators in this enumeration type are meant to be bitwise
  528.  * ORed together to specify which options should be used when
  529.  * constructing the translation unit.
  530.  */
  531. enum CXTranslationUnit_Flags {
  532.   /**
  533.    * Used to indicate that no special translation-unit options are
  534.    * needed.
  535.    */
  536.   CXTranslationUnit_None = 0x0,
  537.  
  538.   /**
  539.    * Used to indicate that the parser should construct a "detailed"
  540.    * preprocessing record, including all macro definitions and instantiations.
  541.    *
  542.    * Constructing a detailed preprocessing record requires more memory
  543.    * and time to parse, since the information contained in the record
  544.    * is usually not retained. However, it can be useful for
  545.    * applications that require more detailed information about the
  546.    * behavior of the preprocessor.
  547.    */
  548.   CXTranslationUnit_DetailedPreprocessingRecord = 0x01,
  549.  
  550.   /**
  551.    * Used to indicate that the translation unit is incomplete.
  552.    *
  553.    * When a translation unit is considered "incomplete", semantic
  554.    * analysis that is typically performed at the end of the
  555.    * translation unit will be suppressed. For example, this suppresses
  556.    * the completion of tentative declarations in C and of
  557.    * instantiation of implicitly-instantiation function templates in
  558.    * C++. This option is typically used when parsing a header with the
  559.    * intent of producing a precompiled header.
  560.    */
  561.   CXTranslationUnit_Incomplete = 0x02,
  562.  
  563.   /**
  564.    * Used to indicate that the translation unit should be built with an
  565.    * implicit precompiled header for the preamble.
  566.    *
  567.    * An implicit precompiled header is used as an optimization when a
  568.    * particular translation unit is likely to be reparsed many times
  569.    * when the sources aren't changing that often. In this case, an
  570.    * implicit precompiled header will be built containing all of the
  571.    * initial includes at the top of the main file (what we refer to as
  572.    * the "preamble" of the file). In subsequent parses, if the
  573.    * preamble or the files in it have not changed, \c
  574.    * clang_reparseTranslationUnit() will re-use the implicit
  575.    * precompiled header to improve parsing performance.
  576.    */
  577.   CXTranslationUnit_PrecompiledPreamble = 0x04,
  578.  
  579.   /**
  580.    * Used to indicate that the translation unit should cache some
  581.    * code-completion results with each reparse of the source file.
  582.    *
  583.    * Caching of code-completion results is a performance optimization that
  584.    * introduces some overhead to reparsing but improves the performance of
  585.    * code-completion operations.
  586.    */
  587.   CXTranslationUnit_CacheCompletionResults = 0x08,
  588.  
  589.   /**
  590.    * Used to indicate that the translation unit will be serialized with
  591.    * \c clang_saveTranslationUnit.
  592.    *
  593.    * This option is typically used when parsing a header with the intent of
  594.    * producing a precompiled header.
  595.    */
  596.   CXTranslationUnit_ForSerialization = 0x10,
  597.  
  598.   /**
  599.    * DEPRECATED: Enabled chained precompiled preambles in C++.
  600.    *
  601.    * Note: this is a *temporary* option that is available only while
  602.    * we are testing C++ precompiled preamble support. It is deprecated.
  603.    */
  604.   CXTranslationUnit_CXXChainedPCH = 0x20,
  605.  
  606.   /**
  607.    * Used to indicate that function/method bodies should be skipped while
  608.    * parsing.
  609.    *
  610.    * This option can be used to search for declarations/definitions while
  611.    * ignoring the usages.
  612.    */
  613.   CXTranslationUnit_SkipFunctionBodies = 0x40,
  614.  
  615.   /**
  616.    * Used to indicate that brief documentation comments should be
  617.    * included into the set of code completions returned from this translation
  618.    * unit.
  619.    */
  620.   CXTranslationUnit_IncludeBriefCommentsInCodeCompletion = 0x80,
  621.  
  622.   /**
  623.    * Used to indicate that the precompiled preamble should be created on
  624.    * the first parse. Otherwise it will be created on the first reparse. This
  625.    * trades runtime on the first parse (serializing the preamble takes time) for
  626.    * reduced runtime on the second parse (can now reuse the preamble).
  627.    */
  628.   CXTranslationUnit_CreatePreambleOnFirstParse = 0x100,
  629.  
  630.   /**
  631.    * Do not stop processing when fatal errors are encountered.
  632.    *
  633.    * When fatal errors are encountered while parsing a translation unit,
  634.    * semantic analysis is typically stopped early when compiling code. A common
  635.    * source for fatal errors are unresolvable include files. For the
  636.    * purposes of an IDE, this is undesirable behavior and as much information
  637.    * as possible should be reported. Use this flag to enable this behavior.
  638.    */
  639.   CXTranslationUnit_KeepGoing = 0x200,
  640.  
  641.   /**
  642.    * Sets the preprocessor in a mode for parsing a single file only.
  643.    */
  644.   CXTranslationUnit_SingleFileParse = 0x400,
  645.  
  646.   /**
  647.    * Used in combination with CXTranslationUnit_SkipFunctionBodies to
  648.    * constrain the skipping of function bodies to the preamble.
  649.    *
  650.    * The function bodies of the main file are not skipped.
  651.    */
  652.   CXTranslationUnit_LimitSkipFunctionBodiesToPreamble = 0x800,
  653.  
  654.   /**
  655.    * Used to indicate that attributed types should be included in CXType.
  656.    */
  657.   CXTranslationUnit_IncludeAttributedTypes = 0x1000,
  658.  
  659.   /**
  660.    * Used to indicate that implicit attributes should be visited.
  661.    */
  662.   CXTranslationUnit_VisitImplicitAttributes = 0x2000,
  663.  
  664.   /**
  665.    * Used to indicate that non-errors from included files should be ignored.
  666.    *
  667.    * If set, clang_getDiagnosticSetFromTU() will not report e.g. warnings from
  668.    * included files anymore. This speeds up clang_getDiagnosticSetFromTU() for
  669.    * the case where these warnings are not of interest, as for an IDE for
  670.    * example, which typically shows only the diagnostics in the main file.
  671.    */
  672.   CXTranslationUnit_IgnoreNonErrorsFromIncludedFiles = 0x4000,
  673.  
  674.   /**
  675.    * Tells the preprocessor not to skip excluded conditional blocks.
  676.    */
  677.   CXTranslationUnit_RetainExcludedConditionalBlocks = 0x8000
  678. };
  679.  
  680. /**
  681.  * Returns the set of flags that is suitable for parsing a translation
  682.  * unit that is being edited.
  683.  *
  684.  * The set of flags returned provide options for \c clang_parseTranslationUnit()
  685.  * to indicate that the translation unit is likely to be reparsed many times,
  686.  * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly
  687.  * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag
  688.  * set contains an unspecified set of optimizations (e.g., the precompiled
  689.  * preamble) geared toward improving the performance of these routines. The
  690.  * set of optimizations enabled may change from one version to the next.
  691.  */
  692. CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
  693.  
  694. /**
  695.  * Same as \c clang_parseTranslationUnit2, but returns
  696.  * the \c CXTranslationUnit instead of an error code.  In case of an error this
  697.  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
  698.  * error codes.
  699.  */
  700. CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(
  701.     CXIndex CIdx, const char *source_filename,
  702.     const char *const *command_line_args, int num_command_line_args,
  703.     struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
  704.     unsigned options);
  705.  
  706. /**
  707.  * Parse the given source file and the translation unit corresponding
  708.  * to that file.
  709.  *
  710.  * This routine is the main entry point for the Clang C API, providing the
  711.  * ability to parse a source file into a translation unit that can then be
  712.  * queried by other functions in the API. This routine accepts a set of
  713.  * command-line arguments so that the compilation can be configured in the same
  714.  * way that the compiler is configured on the command line.
  715.  *
  716.  * \param CIdx The index object with which the translation unit will be
  717.  * associated.
  718.  *
  719.  * \param source_filename The name of the source file to load, or NULL if the
  720.  * source file is included in \c command_line_args.
  721.  *
  722.  * \param command_line_args The command-line arguments that would be
  723.  * passed to the \c clang executable if it were being invoked out-of-process.
  724.  * These command-line options will be parsed and will affect how the translation
  725.  * unit is parsed. Note that the following options are ignored: '-c',
  726.  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'.
  727.  *
  728.  * \param num_command_line_args The number of command-line arguments in
  729.  * \c command_line_args.
  730.  *
  731.  * \param unsaved_files the files that have not yet been saved to disk
  732.  * but may be required for parsing, including the contents of
  733.  * those files.  The contents and name of these files (as specified by
  734.  * CXUnsavedFile) are copied when necessary, so the client only needs to
  735.  * guarantee their validity until the call to this function returns.
  736.  *
  737.  * \param num_unsaved_files the number of unsaved file entries in \p
  738.  * unsaved_files.
  739.  *
  740.  * \param options A bitmask of options that affects how the translation unit
  741.  * is managed but not its compilation. This should be a bitwise OR of the
  742.  * CXTranslationUnit_XXX flags.
  743.  *
  744.  * \param[out] out_TU A non-NULL pointer to store the created
  745.  * \c CXTranslationUnit, describing the parsed code and containing any
  746.  * diagnostics produced by the compiler.
  747.  *
  748.  * \returns Zero on success, otherwise returns an error code.
  749.  */
  750. CINDEX_LINKAGE enum CXErrorCode clang_parseTranslationUnit2(
  751.     CXIndex CIdx, const char *source_filename,
  752.     const char *const *command_line_args, int num_command_line_args,
  753.     struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
  754.     unsigned options, CXTranslationUnit *out_TU);
  755.  
  756. /**
  757.  * Same as clang_parseTranslationUnit2 but requires a full command line
  758.  * for \c command_line_args including argv[0]. This is useful if the standard
  759.  * library paths are relative to the binary.
  760.  */
  761. CINDEX_LINKAGE enum CXErrorCode clang_parseTranslationUnit2FullArgv(
  762.     CXIndex CIdx, const char *source_filename,
  763.     const char *const *command_line_args, int num_command_line_args,
  764.     struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
  765.     unsigned options, CXTranslationUnit *out_TU);
  766.  
  767. /**
  768.  * Flags that control how translation units are saved.
  769.  *
  770.  * The enumerators in this enumeration type are meant to be bitwise
  771.  * ORed together to specify which options should be used when
  772.  * saving the translation unit.
  773.  */
  774. enum CXSaveTranslationUnit_Flags {
  775.   /**
  776.    * Used to indicate that no special saving options are needed.
  777.    */
  778.   CXSaveTranslationUnit_None = 0x0
  779. };
  780.  
  781. /**
  782.  * Returns the set of flags that is suitable for saving a translation
  783.  * unit.
  784.  *
  785.  * The set of flags returned provide options for
  786.  * \c clang_saveTranslationUnit() by default. The returned flag
  787.  * set contains an unspecified set of options that save translation units with
  788.  * the most commonly-requested data.
  789.  */
  790. CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU);
  791.  
  792. /**
  793.  * Describes the kind of error that occurred (if any) in a call to
  794.  * \c clang_saveTranslationUnit().
  795.  */
  796. enum CXSaveError {
  797.   /**
  798.    * Indicates that no error occurred while saving a translation unit.
  799.    */
  800.   CXSaveError_None = 0,
  801.  
  802.   /**
  803.    * Indicates that an unknown error occurred while attempting to save
  804.    * the file.
  805.    *
  806.    * This error typically indicates that file I/O failed when attempting to
  807.    * write the file.
  808.    */
  809.   CXSaveError_Unknown = 1,
  810.  
  811.   /**
  812.    * Indicates that errors during translation prevented this attempt
  813.    * to save the translation unit.
  814.    *
  815.    * Errors that prevent the translation unit from being saved can be
  816.    * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic().
  817.    */
  818.   CXSaveError_TranslationErrors = 2,
  819.  
  820.   /**
  821.    * Indicates that the translation unit to be saved was somehow
  822.    * invalid (e.g., NULL).
  823.    */
  824.   CXSaveError_InvalidTU = 3
  825. };
  826.  
  827. /**
  828.  * Saves a translation unit into a serialized representation of
  829.  * that translation unit on disk.
  830.  *
  831.  * Any translation unit that was parsed without error can be saved
  832.  * into a file. The translation unit can then be deserialized into a
  833.  * new \c CXTranslationUnit with \c clang_createTranslationUnit() or,
  834.  * if it is an incomplete translation unit that corresponds to a
  835.  * header, used as a precompiled header when parsing other translation
  836.  * units.
  837.  *
  838.  * \param TU The translation unit to save.
  839.  *
  840.  * \param FileName The file to which the translation unit will be saved.
  841.  *
  842.  * \param options A bitmask of options that affects how the translation unit
  843.  * is saved. This should be a bitwise OR of the
  844.  * CXSaveTranslationUnit_XXX flags.
  845.  *
  846.  * \returns A value that will match one of the enumerators of the CXSaveError
  847.  * enumeration. Zero (CXSaveError_None) indicates that the translation unit was
  848.  * saved successfully, while a non-zero value indicates that a problem occurred.
  849.  */
  850. CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU,
  851.                                              const char *FileName,
  852.                                              unsigned options);
  853.  
  854. /**
  855.  * Suspend a translation unit in order to free memory associated with it.
  856.  *
  857.  * A suspended translation unit uses significantly less memory but on the other
  858.  * side does not support any other calls than \c clang_reparseTranslationUnit
  859.  * to resume it or \c clang_disposeTranslationUnit to dispose it completely.
  860.  */
  861. CINDEX_LINKAGE unsigned clang_suspendTranslationUnit(CXTranslationUnit);
  862.  
  863. /**
  864.  * Destroy the specified CXTranslationUnit object.
  865.  */
  866. CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
  867.  
  868. /**
  869.  * Flags that control the reparsing of translation units.
  870.  *
  871.  * The enumerators in this enumeration type are meant to be bitwise
  872.  * ORed together to specify which options should be used when
  873.  * reparsing the translation unit.
  874.  */
  875. enum CXReparse_Flags {
  876.   /**
  877.    * Used to indicate that no special reparsing options are needed.
  878.    */
  879.   CXReparse_None = 0x0
  880. };
  881.  
  882. /**
  883.  * Returns the set of flags that is suitable for reparsing a translation
  884.  * unit.
  885.  *
  886.  * The set of flags returned provide options for
  887.  * \c clang_reparseTranslationUnit() by default. The returned flag
  888.  * set contains an unspecified set of optimizations geared toward common uses
  889.  * of reparsing. The set of optimizations enabled may change from one version
  890.  * to the next.
  891.  */
  892. CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU);
  893.  
  894. /**
  895.  * Reparse the source files that produced this translation unit.
  896.  *
  897.  * This routine can be used to re-parse the source files that originally
  898.  * created the given translation unit, for example because those source files
  899.  * have changed (either on disk or as passed via \p unsaved_files). The
  900.  * source code will be reparsed with the same command-line options as it
  901.  * was originally parsed.
  902.  *
  903.  * Reparsing a translation unit invalidates all cursors and source locations
  904.  * that refer into that translation unit. This makes reparsing a translation
  905.  * unit semantically equivalent to destroying the translation unit and then
  906.  * creating a new translation unit with the same command-line arguments.
  907.  * However, it may be more efficient to reparse a translation
  908.  * unit using this routine.
  909.  *
  910.  * \param TU The translation unit whose contents will be re-parsed. The
  911.  * translation unit must originally have been built with
  912.  * \c clang_createTranslationUnitFromSourceFile().
  913.  *
  914.  * \param num_unsaved_files The number of unsaved file entries in \p
  915.  * unsaved_files.
  916.  *
  917.  * \param unsaved_files The files that have not yet been saved to disk
  918.  * but may be required for parsing, including the contents of
  919.  * those files.  The contents and name of these files (as specified by
  920.  * CXUnsavedFile) are copied when necessary, so the client only needs to
  921.  * guarantee their validity until the call to this function returns.
  922.  *
  923.  * \param options A bitset of options composed of the flags in CXReparse_Flags.
  924.  * The function \c clang_defaultReparseOptions() produces a default set of
  925.  * options recommended for most uses, based on the translation unit.
  926.  *
  927.  * \returns 0 if the sources could be reparsed.  A non-zero error code will be
  928.  * returned if reparsing was impossible, such that the translation unit is
  929.  * invalid. In such cases, the only valid call for \c TU is
  930.  * \c clang_disposeTranslationUnit(TU).  The error codes returned by this
  931.  * routine are described by the \c CXErrorCode enum.
  932.  */
  933. CINDEX_LINKAGE int
  934. clang_reparseTranslationUnit(CXTranslationUnit TU, unsigned num_unsaved_files,
  935.                              struct CXUnsavedFile *unsaved_files,
  936.                              unsigned options);
  937.  
  938. /**
  939.  * Categorizes how memory is being used by a translation unit.
  940.  */
  941. enum CXTUResourceUsageKind {
  942.   CXTUResourceUsage_AST = 1,
  943.   CXTUResourceUsage_Identifiers = 2,
  944.   CXTUResourceUsage_Selectors = 3,
  945.   CXTUResourceUsage_GlobalCompletionResults = 4,
  946.   CXTUResourceUsage_SourceManagerContentCache = 5,
  947.   CXTUResourceUsage_AST_SideTables = 6,
  948.   CXTUResourceUsage_SourceManager_Membuffer_Malloc = 7,
  949.   CXTUResourceUsage_SourceManager_Membuffer_MMap = 8,
  950.   CXTUResourceUsage_ExternalASTSource_Membuffer_Malloc = 9,
  951.   CXTUResourceUsage_ExternalASTSource_Membuffer_MMap = 10,
  952.   CXTUResourceUsage_Preprocessor = 11,
  953.   CXTUResourceUsage_PreprocessingRecord = 12,
  954.   CXTUResourceUsage_SourceManager_DataStructures = 13,
  955.   CXTUResourceUsage_Preprocessor_HeaderSearch = 14,
  956.   CXTUResourceUsage_MEMORY_IN_BYTES_BEGIN = CXTUResourceUsage_AST,
  957.   CXTUResourceUsage_MEMORY_IN_BYTES_END =
  958.       CXTUResourceUsage_Preprocessor_HeaderSearch,
  959.  
  960.   CXTUResourceUsage_First = CXTUResourceUsage_AST,
  961.   CXTUResourceUsage_Last = CXTUResourceUsage_Preprocessor_HeaderSearch
  962. };
  963.  
  964. /**
  965.  * Returns the human-readable null-terminated C string that represents
  966.  *  the name of the memory category.  This string should never be freed.
  967.  */
  968. CINDEX_LINKAGE
  969. const char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind);
  970.  
  971. typedef struct CXTUResourceUsageEntry {
  972.   /* The memory usage category. */
  973.   enum CXTUResourceUsageKind kind;
  974.   /* Amount of resources used.
  975.       The units will depend on the resource kind. */
  976.   unsigned long amount;
  977. } CXTUResourceUsageEntry;
  978.  
  979. /**
  980.  * The memory usage of a CXTranslationUnit, broken into categories.
  981.  */
  982. typedef struct CXTUResourceUsage {
  983.   /* Private data member, used for queries. */
  984.   void *data;
  985.  
  986.   /* The number of entries in the 'entries' array. */
  987.   unsigned numEntries;
  988.  
  989.   /* An array of key-value pairs, representing the breakdown of memory
  990.             usage. */
  991.   CXTUResourceUsageEntry *entries;
  992.  
  993. } CXTUResourceUsage;
  994.  
  995. /**
  996.  * Return the memory usage of a translation unit.  This object
  997.  *  should be released with clang_disposeCXTUResourceUsage().
  998.  */
  999. CINDEX_LINKAGE CXTUResourceUsage
  1000. clang_getCXTUResourceUsage(CXTranslationUnit TU);
  1001.  
  1002. CINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage);
  1003.  
  1004. /**
  1005.  * Get target information for this translation unit.
  1006.  *
  1007.  * The CXTargetInfo object cannot outlive the CXTranslationUnit object.
  1008.  */
  1009. CINDEX_LINKAGE CXTargetInfo
  1010. clang_getTranslationUnitTargetInfo(CXTranslationUnit CTUnit);
  1011.  
  1012. /**
  1013.  * Destroy the CXTargetInfo object.
  1014.  */
  1015. CINDEX_LINKAGE void clang_TargetInfo_dispose(CXTargetInfo Info);
  1016.  
  1017. /**
  1018.  * Get the normalized target triple as a string.
  1019.  *
  1020.  * Returns the empty string in case of any error.
  1021.  */
  1022. CINDEX_LINKAGE CXString clang_TargetInfo_getTriple(CXTargetInfo Info);
  1023.  
  1024. /**
  1025.  * Get the pointer width of the target in bits.
  1026.  *
  1027.  * Returns -1 in case of error.
  1028.  */
  1029. CINDEX_LINKAGE int clang_TargetInfo_getPointerWidth(CXTargetInfo Info);
  1030.  
  1031. /**
  1032.  * @}
  1033.  */
  1034.  
  1035. /**
  1036.  * Describes the kind of entity that a cursor refers to.
  1037.  */
  1038. enum CXCursorKind {
  1039.   /* Declarations */
  1040.   /**
  1041.    * A declaration whose specific kind is not exposed via this
  1042.    * interface.
  1043.    *
  1044.    * Unexposed declarations have the same operations as any other kind
  1045.    * of declaration; one can extract their location information,
  1046.    * spelling, find their definitions, etc. However, the specific kind
  1047.    * of the declaration is not reported.
  1048.    */
  1049.   CXCursor_UnexposedDecl = 1,
  1050.   /** A C or C++ struct. */
  1051.   CXCursor_StructDecl = 2,
  1052.   /** A C or C++ union. */
  1053.   CXCursor_UnionDecl = 3,
  1054.   /** A C++ class. */
  1055.   CXCursor_ClassDecl = 4,
  1056.   /** An enumeration. */
  1057.   CXCursor_EnumDecl = 5,
  1058.   /**
  1059.    * A field (in C) or non-static data member (in C++) in a
  1060.    * struct, union, or C++ class.
  1061.    */
  1062.   CXCursor_FieldDecl = 6,
  1063.   /** An enumerator constant. */
  1064.   CXCursor_EnumConstantDecl = 7,
  1065.   /** A function. */
  1066.   CXCursor_FunctionDecl = 8,
  1067.   /** A variable. */
  1068.   CXCursor_VarDecl = 9,
  1069.   /** A function or method parameter. */
  1070.   CXCursor_ParmDecl = 10,
  1071.   /** An Objective-C \@interface. */
  1072.   CXCursor_ObjCInterfaceDecl = 11,
  1073.   /** An Objective-C \@interface for a category. */
  1074.   CXCursor_ObjCCategoryDecl = 12,
  1075.   /** An Objective-C \@protocol declaration. */
  1076.   CXCursor_ObjCProtocolDecl = 13,
  1077.   /** An Objective-C \@property declaration. */
  1078.   CXCursor_ObjCPropertyDecl = 14,
  1079.   /** An Objective-C instance variable. */
  1080.   CXCursor_ObjCIvarDecl = 15,
  1081.   /** An Objective-C instance method. */
  1082.   CXCursor_ObjCInstanceMethodDecl = 16,
  1083.   /** An Objective-C class method. */
  1084.   CXCursor_ObjCClassMethodDecl = 17,
  1085.   /** An Objective-C \@implementation. */
  1086.   CXCursor_ObjCImplementationDecl = 18,
  1087.   /** An Objective-C \@implementation for a category. */
  1088.   CXCursor_ObjCCategoryImplDecl = 19,
  1089.   /** A typedef. */
  1090.   CXCursor_TypedefDecl = 20,
  1091.   /** A C++ class method. */
  1092.   CXCursor_CXXMethod = 21,
  1093.   /** A C++ namespace. */
  1094.   CXCursor_Namespace = 22,
  1095.   /** A linkage specification, e.g. 'extern "C"'. */
  1096.   CXCursor_LinkageSpec = 23,
  1097.   /** A C++ constructor. */
  1098.   CXCursor_Constructor = 24,
  1099.   /** A C++ destructor. */
  1100.   CXCursor_Destructor = 25,
  1101.   /** A C++ conversion function. */
  1102.   CXCursor_ConversionFunction = 26,
  1103.   /** A C++ template type parameter. */
  1104.   CXCursor_TemplateTypeParameter = 27,
  1105.   /** A C++ non-type template parameter. */
  1106.   CXCursor_NonTypeTemplateParameter = 28,
  1107.   /** A C++ template template parameter. */
  1108.   CXCursor_TemplateTemplateParameter = 29,
  1109.   /** A C++ function template. */
  1110.   CXCursor_FunctionTemplate = 30,
  1111.   /** A C++ class template. */
  1112.   CXCursor_ClassTemplate = 31,
  1113.   /** A C++ class template partial specialization. */
  1114.   CXCursor_ClassTemplatePartialSpecialization = 32,
  1115.   /** A C++ namespace alias declaration. */
  1116.   CXCursor_NamespaceAlias = 33,
  1117.   /** A C++ using directive. */
  1118.   CXCursor_UsingDirective = 34,
  1119.   /** A C++ using declaration. */
  1120.   CXCursor_UsingDeclaration = 35,
  1121.   /** A C++ alias declaration */
  1122.   CXCursor_TypeAliasDecl = 36,
  1123.   /** An Objective-C \@synthesize definition. */
  1124.   CXCursor_ObjCSynthesizeDecl = 37,
  1125.   /** An Objective-C \@dynamic definition. */
  1126.   CXCursor_ObjCDynamicDecl = 38,
  1127.   /** An access specifier. */
  1128.   CXCursor_CXXAccessSpecifier = 39,
  1129.  
  1130.   CXCursor_FirstDecl = CXCursor_UnexposedDecl,
  1131.   CXCursor_LastDecl = CXCursor_CXXAccessSpecifier,
  1132.  
  1133.   /* References */
  1134.   CXCursor_FirstRef = 40, /* Decl references */
  1135.   CXCursor_ObjCSuperClassRef = 40,
  1136.   CXCursor_ObjCProtocolRef = 41,
  1137.   CXCursor_ObjCClassRef = 42,
  1138.   /**
  1139.    * A reference to a type declaration.
  1140.    *
  1141.    * A type reference occurs anywhere where a type is named but not
  1142.    * declared. For example, given:
  1143.    *
  1144.    * \code
  1145.    * typedef unsigned size_type;
  1146.    * size_type size;
  1147.    * \endcode
  1148.    *
  1149.    * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
  1150.    * while the type of the variable "size" is referenced. The cursor
  1151.    * referenced by the type of size is the typedef for size_type.
  1152.    */
  1153.   CXCursor_TypeRef = 43,
  1154.   CXCursor_CXXBaseSpecifier = 44,
  1155.   /**
  1156.    * A reference to a class template, function template, template
  1157.    * template parameter, or class template partial specialization.
  1158.    */
  1159.   CXCursor_TemplateRef = 45,
  1160.   /**
  1161.    * A reference to a namespace or namespace alias.
  1162.    */
  1163.   CXCursor_NamespaceRef = 46,
  1164.   /**
  1165.    * A reference to a member of a struct, union, or class that occurs in
  1166.    * some non-expression context, e.g., a designated initializer.
  1167.    */
  1168.   CXCursor_MemberRef = 47,
  1169.   /**
  1170.    * A reference to a labeled statement.
  1171.    *
  1172.    * This cursor kind is used to describe the jump to "start_over" in the
  1173.    * goto statement in the following example:
  1174.    *
  1175.    * \code
  1176.    *   start_over:
  1177.    *     ++counter;
  1178.    *
  1179.    *     goto start_over;
  1180.    * \endcode
  1181.    *
  1182.    * A label reference cursor refers to a label statement.
  1183.    */
  1184.   CXCursor_LabelRef = 48,
  1185.  
  1186.   /**
  1187.    * A reference to a set of overloaded functions or function templates
  1188.    * that has not yet been resolved to a specific function or function template.
  1189.    *
  1190.    * An overloaded declaration reference cursor occurs in C++ templates where
  1191.    * a dependent name refers to a function. For example:
  1192.    *
  1193.    * \code
  1194.    * template<typename T> void swap(T&, T&);
  1195.    *
  1196.    * struct X { ... };
  1197.    * void swap(X&, X&);
  1198.    *
  1199.    * template<typename T>
  1200.    * void reverse(T* first, T* last) {
  1201.    *   while (first < last - 1) {
  1202.    *     swap(*first, *--last);
  1203.    *     ++first;
  1204.    *   }
  1205.    * }
  1206.    *
  1207.    * struct Y { };
  1208.    * void swap(Y&, Y&);
  1209.    * \endcode
  1210.    *
  1211.    * Here, the identifier "swap" is associated with an overloaded declaration
  1212.    * reference. In the template definition, "swap" refers to either of the two
  1213.    * "swap" functions declared above, so both results will be available. At
  1214.    * instantiation time, "swap" may also refer to other functions found via
  1215.    * argument-dependent lookup (e.g., the "swap" function at the end of the
  1216.    * example).
  1217.    *
  1218.    * The functions \c clang_getNumOverloadedDecls() and
  1219.    * \c clang_getOverloadedDecl() can be used to retrieve the definitions
  1220.    * referenced by this cursor.
  1221.    */
  1222.   CXCursor_OverloadedDeclRef = 49,
  1223.  
  1224.   /**
  1225.    * A reference to a variable that occurs in some non-expression
  1226.    * context, e.g., a C++ lambda capture list.
  1227.    */
  1228.   CXCursor_VariableRef = 50,
  1229.  
  1230.   CXCursor_LastRef = CXCursor_VariableRef,
  1231.  
  1232.   /* Error conditions */
  1233.   CXCursor_FirstInvalid = 70,
  1234.   CXCursor_InvalidFile = 70,
  1235.   CXCursor_NoDeclFound = 71,
  1236.   CXCursor_NotImplemented = 72,
  1237.   CXCursor_InvalidCode = 73,
  1238.   CXCursor_LastInvalid = CXCursor_InvalidCode,
  1239.  
  1240.   /* Expressions */
  1241.   CXCursor_FirstExpr = 100,
  1242.  
  1243.   /**
  1244.    * An expression whose specific kind is not exposed via this
  1245.    * interface.
  1246.    *
  1247.    * Unexposed expressions have the same operations as any other kind
  1248.    * of expression; one can extract their location information,
  1249.    * spelling, children, etc. However, the specific kind of the
  1250.    * expression is not reported.
  1251.    */
  1252.   CXCursor_UnexposedExpr = 100,
  1253.  
  1254.   /**
  1255.    * An expression that refers to some value declaration, such
  1256.    * as a function, variable, or enumerator.
  1257.    */
  1258.   CXCursor_DeclRefExpr = 101,
  1259.  
  1260.   /**
  1261.    * An expression that refers to a member of a struct, union,
  1262.    * class, Objective-C class, etc.
  1263.    */
  1264.   CXCursor_MemberRefExpr = 102,
  1265.  
  1266.   /** An expression that calls a function. */
  1267.   CXCursor_CallExpr = 103,
  1268.  
  1269.   /** An expression that sends a message to an Objective-C
  1270.    object or class. */
  1271.   CXCursor_ObjCMessageExpr = 104,
  1272.  
  1273.   /** An expression that represents a block literal. */
  1274.   CXCursor_BlockExpr = 105,
  1275.  
  1276.   /** An integer literal.
  1277.    */
  1278.   CXCursor_IntegerLiteral = 106,
  1279.  
  1280.   /** A floating point number literal.
  1281.    */
  1282.   CXCursor_FloatingLiteral = 107,
  1283.  
  1284.   /** An imaginary number literal.
  1285.    */
  1286.   CXCursor_ImaginaryLiteral = 108,
  1287.  
  1288.   /** A string literal.
  1289.    */
  1290.   CXCursor_StringLiteral = 109,
  1291.  
  1292.   /** A character literal.
  1293.    */
  1294.   CXCursor_CharacterLiteral = 110,
  1295.  
  1296.   /** A parenthesized expression, e.g. "(1)".
  1297.    *
  1298.    * This AST node is only formed if full location information is requested.
  1299.    */
  1300.   CXCursor_ParenExpr = 111,
  1301.  
  1302.   /** This represents the unary-expression's (except sizeof and
  1303.    * alignof).
  1304.    */
  1305.   CXCursor_UnaryOperator = 112,
  1306.  
  1307.   /** [C99 6.5.2.1] Array Subscripting.
  1308.    */
  1309.   CXCursor_ArraySubscriptExpr = 113,
  1310.  
  1311.   /** A builtin binary operation expression such as "x + y" or
  1312.    * "x <= y".
  1313.    */
  1314.   CXCursor_BinaryOperator = 114,
  1315.  
  1316.   /** Compound assignment such as "+=".
  1317.    */
  1318.   CXCursor_CompoundAssignOperator = 115,
  1319.  
  1320.   /** The ?: ternary operator.
  1321.    */
  1322.   CXCursor_ConditionalOperator = 116,
  1323.  
  1324.   /** An explicit cast in C (C99 6.5.4) or a C-style cast in C++
  1325.    * (C++ [expr.cast]), which uses the syntax (Type)expr.
  1326.    *
  1327.    * For example: (int)f.
  1328.    */
  1329.   CXCursor_CStyleCastExpr = 117,
  1330.  
  1331.   /** [C99 6.5.2.5]
  1332.    */
  1333.   CXCursor_CompoundLiteralExpr = 118,
  1334.  
  1335.   /** Describes an C or C++ initializer list.
  1336.    */
  1337.   CXCursor_InitListExpr = 119,
  1338.  
  1339.   /** The GNU address of label extension, representing &&label.
  1340.    */
  1341.   CXCursor_AddrLabelExpr = 120,
  1342.  
  1343.   /** This is the GNU Statement Expression extension: ({int X=4; X;})
  1344.    */
  1345.   CXCursor_StmtExpr = 121,
  1346.  
  1347.   /** Represents a C11 generic selection.
  1348.    */
  1349.   CXCursor_GenericSelectionExpr = 122,
  1350.  
  1351.   /** Implements the GNU __null extension, which is a name for a null
  1352.    * pointer constant that has integral type (e.g., int or long) and is the same
  1353.    * size and alignment as a pointer.
  1354.    *
  1355.    * The __null extension is typically only used by system headers, which define
  1356.    * NULL as __null in C++ rather than using 0 (which is an integer that may not
  1357.    * match the size of a pointer).
  1358.    */
  1359.   CXCursor_GNUNullExpr = 123,
  1360.  
  1361.   /** C++'s static_cast<> expression.
  1362.    */
  1363.   CXCursor_CXXStaticCastExpr = 124,
  1364.  
  1365.   /** C++'s dynamic_cast<> expression.
  1366.    */
  1367.   CXCursor_CXXDynamicCastExpr = 125,
  1368.  
  1369.   /** C++'s reinterpret_cast<> expression.
  1370.    */
  1371.   CXCursor_CXXReinterpretCastExpr = 126,
  1372.  
  1373.   /** C++'s const_cast<> expression.
  1374.    */
  1375.   CXCursor_CXXConstCastExpr = 127,
  1376.  
  1377.   /** Represents an explicit C++ type conversion that uses "functional"
  1378.    * notion (C++ [expr.type.conv]).
  1379.    *
  1380.    * Example:
  1381.    * \code
  1382.    *   x = int(0.5);
  1383.    * \endcode
  1384.    */
  1385.   CXCursor_CXXFunctionalCastExpr = 128,
  1386.  
  1387.   /** A C++ typeid expression (C++ [expr.typeid]).
  1388.    */
  1389.   CXCursor_CXXTypeidExpr = 129,
  1390.  
  1391.   /** [C++ 2.13.5] C++ Boolean Literal.
  1392.    */
  1393.   CXCursor_CXXBoolLiteralExpr = 130,
  1394.  
  1395.   /** [C++0x 2.14.7] C++ Pointer Literal.
  1396.    */
  1397.   CXCursor_CXXNullPtrLiteralExpr = 131,
  1398.  
  1399.   /** Represents the "this" expression in C++
  1400.    */
  1401.   CXCursor_CXXThisExpr = 132,
  1402.  
  1403.   /** [C++ 15] C++ Throw Expression.
  1404.    *
  1405.    * This handles 'throw' and 'throw' assignment-expression. When
  1406.    * assignment-expression isn't present, Op will be null.
  1407.    */
  1408.   CXCursor_CXXThrowExpr = 133,
  1409.  
  1410.   /** A new expression for memory allocation and constructor calls, e.g:
  1411.    * "new CXXNewExpr(foo)".
  1412.    */
  1413.   CXCursor_CXXNewExpr = 134,
  1414.  
  1415.   /** A delete expression for memory deallocation and destructor calls,
  1416.    * e.g. "delete[] pArray".
  1417.    */
  1418.   CXCursor_CXXDeleteExpr = 135,
  1419.  
  1420.   /** A unary expression. (noexcept, sizeof, or other traits)
  1421.    */
  1422.   CXCursor_UnaryExpr = 136,
  1423.  
  1424.   /** An Objective-C string literal i.e. @"foo".
  1425.    */
  1426.   CXCursor_ObjCStringLiteral = 137,
  1427.  
  1428.   /** An Objective-C \@encode expression.
  1429.    */
  1430.   CXCursor_ObjCEncodeExpr = 138,
  1431.  
  1432.   /** An Objective-C \@selector expression.
  1433.    */
  1434.   CXCursor_ObjCSelectorExpr = 139,
  1435.  
  1436.   /** An Objective-C \@protocol expression.
  1437.    */
  1438.   CXCursor_ObjCProtocolExpr = 140,
  1439.  
  1440.   /** An Objective-C "bridged" cast expression, which casts between
  1441.    * Objective-C pointers and C pointers, transferring ownership in the process.
  1442.    *
  1443.    * \code
  1444.    *   NSString *str = (__bridge_transfer NSString *)CFCreateString();
  1445.    * \endcode
  1446.    */
  1447.   CXCursor_ObjCBridgedCastExpr = 141,
  1448.  
  1449.   /** Represents a C++0x pack expansion that produces a sequence of
  1450.    * expressions.
  1451.    *
  1452.    * A pack expansion expression contains a pattern (which itself is an
  1453.    * expression) followed by an ellipsis. For example:
  1454.    *
  1455.    * \code
  1456.    * template<typename F, typename ...Types>
  1457.    * void forward(F f, Types &&...args) {
  1458.    *  f(static_cast<Types&&>(args)...);
  1459.    * }
  1460.    * \endcode
  1461.    */
  1462.   CXCursor_PackExpansionExpr = 142,
  1463.  
  1464.   /** Represents an expression that computes the length of a parameter
  1465.    * pack.
  1466.    *
  1467.    * \code
  1468.    * template<typename ...Types>
  1469.    * struct count {
  1470.    *   static const unsigned value = sizeof...(Types);
  1471.    * };
  1472.    * \endcode
  1473.    */
  1474.   CXCursor_SizeOfPackExpr = 143,
  1475.  
  1476.   /* Represents a C++ lambda expression that produces a local function
  1477.    * object.
  1478.    *
  1479.    * \code
  1480.    * void abssort(float *x, unsigned N) {
  1481.    *   std::sort(x, x + N,
  1482.    *             [](float a, float b) {
  1483.    *               return std::abs(a) < std::abs(b);
  1484.    *             });
  1485.    * }
  1486.    * \endcode
  1487.    */
  1488.   CXCursor_LambdaExpr = 144,
  1489.  
  1490.   /** Objective-c Boolean Literal.
  1491.    */
  1492.   CXCursor_ObjCBoolLiteralExpr = 145,
  1493.  
  1494.   /** Represents the "self" expression in an Objective-C method.
  1495.    */
  1496.   CXCursor_ObjCSelfExpr = 146,
  1497.  
  1498.   /** OpenMP 5.0 [2.1.5, Array Section].
  1499.    */
  1500.   CXCursor_OMPArraySectionExpr = 147,
  1501.  
  1502.   /** Represents an @available(...) check.
  1503.    */
  1504.   CXCursor_ObjCAvailabilityCheckExpr = 148,
  1505.  
  1506.   /**
  1507.    * Fixed point literal
  1508.    */
  1509.   CXCursor_FixedPointLiteral = 149,
  1510.  
  1511.   /** OpenMP 5.0 [2.1.4, Array Shaping].
  1512.    */
  1513.   CXCursor_OMPArrayShapingExpr = 150,
  1514.  
  1515.   /**
  1516.    * OpenMP 5.0 [2.1.6 Iterators]
  1517.    */
  1518.   CXCursor_OMPIteratorExpr = 151,
  1519.  
  1520.   /** OpenCL's addrspace_cast<> expression.
  1521.    */
  1522.   CXCursor_CXXAddrspaceCastExpr = 152,
  1523.  
  1524.   /**
  1525.    * Expression that references a C++20 concept.
  1526.    */
  1527.   CXCursor_ConceptSpecializationExpr = 153,
  1528.  
  1529.   /**
  1530.    * Expression that references a C++20 concept.
  1531.    */
  1532.   CXCursor_RequiresExpr = 154,
  1533.  
  1534.   /**
  1535.    * Expression that references a C++20 parenthesized list aggregate
  1536.    * initializer.
  1537.    */
  1538.   CXCursor_CXXParenListInitExpr = 155,
  1539.  
  1540.   CXCursor_LastExpr = CXCursor_CXXParenListInitExpr,
  1541.  
  1542.   /* Statements */
  1543.   CXCursor_FirstStmt = 200,
  1544.   /**
  1545.    * A statement whose specific kind is not exposed via this
  1546.    * interface.
  1547.    *
  1548.    * Unexposed statements have the same operations as any other kind of
  1549.    * statement; one can extract their location information, spelling,
  1550.    * children, etc. However, the specific kind of the statement is not
  1551.    * reported.
  1552.    */
  1553.   CXCursor_UnexposedStmt = 200,
  1554.  
  1555.   /** A labelled statement in a function.
  1556.    *
  1557.    * This cursor kind is used to describe the "start_over:" label statement in
  1558.    * the following example:
  1559.    *
  1560.    * \code
  1561.    *   start_over:
  1562.    *     ++counter;
  1563.    * \endcode
  1564.    *
  1565.    */
  1566.   CXCursor_LabelStmt = 201,
  1567.  
  1568.   /** A group of statements like { stmt stmt }.
  1569.    *
  1570.    * This cursor kind is used to describe compound statements, e.g. function
  1571.    * bodies.
  1572.    */
  1573.   CXCursor_CompoundStmt = 202,
  1574.  
  1575.   /** A case statement.
  1576.    */
  1577.   CXCursor_CaseStmt = 203,
  1578.  
  1579.   /** A default statement.
  1580.    */
  1581.   CXCursor_DefaultStmt = 204,
  1582.  
  1583.   /** An if statement
  1584.    */
  1585.   CXCursor_IfStmt = 205,
  1586.  
  1587.   /** A switch statement.
  1588.    */
  1589.   CXCursor_SwitchStmt = 206,
  1590.  
  1591.   /** A while statement.
  1592.    */
  1593.   CXCursor_WhileStmt = 207,
  1594.  
  1595.   /** A do statement.
  1596.    */
  1597.   CXCursor_DoStmt = 208,
  1598.  
  1599.   /** A for statement.
  1600.    */
  1601.   CXCursor_ForStmt = 209,
  1602.  
  1603.   /** A goto statement.
  1604.    */
  1605.   CXCursor_GotoStmt = 210,
  1606.  
  1607.   /** An indirect goto statement.
  1608.    */
  1609.   CXCursor_IndirectGotoStmt = 211,
  1610.  
  1611.   /** A continue statement.
  1612.    */
  1613.   CXCursor_ContinueStmt = 212,
  1614.  
  1615.   /** A break statement.
  1616.    */
  1617.   CXCursor_BreakStmt = 213,
  1618.  
  1619.   /** A return statement.
  1620.    */
  1621.   CXCursor_ReturnStmt = 214,
  1622.  
  1623.   /** A GCC inline assembly statement extension.
  1624.    */
  1625.   CXCursor_GCCAsmStmt = 215,
  1626.   CXCursor_AsmStmt = CXCursor_GCCAsmStmt,
  1627.  
  1628.   /** Objective-C's overall \@try-\@catch-\@finally statement.
  1629.    */
  1630.   CXCursor_ObjCAtTryStmt = 216,
  1631.  
  1632.   /** Objective-C's \@catch statement.
  1633.    */
  1634.   CXCursor_ObjCAtCatchStmt = 217,
  1635.  
  1636.   /** Objective-C's \@finally statement.
  1637.    */
  1638.   CXCursor_ObjCAtFinallyStmt = 218,
  1639.  
  1640.   /** Objective-C's \@throw statement.
  1641.    */
  1642.   CXCursor_ObjCAtThrowStmt = 219,
  1643.  
  1644.   /** Objective-C's \@synchronized statement.
  1645.    */
  1646.   CXCursor_ObjCAtSynchronizedStmt = 220,
  1647.  
  1648.   /** Objective-C's autorelease pool statement.
  1649.    */
  1650.   CXCursor_ObjCAutoreleasePoolStmt = 221,
  1651.  
  1652.   /** Objective-C's collection statement.
  1653.    */
  1654.   CXCursor_ObjCForCollectionStmt = 222,
  1655.  
  1656.   /** C++'s catch statement.
  1657.    */
  1658.   CXCursor_CXXCatchStmt = 223,
  1659.  
  1660.   /** C++'s try statement.
  1661.    */
  1662.   CXCursor_CXXTryStmt = 224,
  1663.  
  1664.   /** C++'s for (* : *) statement.
  1665.    */
  1666.   CXCursor_CXXForRangeStmt = 225,
  1667.  
  1668.   /** Windows Structured Exception Handling's try statement.
  1669.    */
  1670.   CXCursor_SEHTryStmt = 226,
  1671.  
  1672.   /** Windows Structured Exception Handling's except statement.
  1673.    */
  1674.   CXCursor_SEHExceptStmt = 227,
  1675.  
  1676.   /** Windows Structured Exception Handling's finally statement.
  1677.    */
  1678.   CXCursor_SEHFinallyStmt = 228,
  1679.  
  1680.   /** A MS inline assembly statement extension.
  1681.    */
  1682.   CXCursor_MSAsmStmt = 229,
  1683.  
  1684.   /** The null statement ";": C99 6.8.3p3.
  1685.    *
  1686.    * This cursor kind is used to describe the null statement.
  1687.    */
  1688.   CXCursor_NullStmt = 230,
  1689.  
  1690.   /** Adaptor class for mixing declarations with statements and
  1691.    * expressions.
  1692.    */
  1693.   CXCursor_DeclStmt = 231,
  1694.  
  1695.   /** OpenMP parallel directive.
  1696.    */
  1697.   CXCursor_OMPParallelDirective = 232,
  1698.  
  1699.   /** OpenMP SIMD directive.
  1700.    */
  1701.   CXCursor_OMPSimdDirective = 233,
  1702.  
  1703.   /** OpenMP for directive.
  1704.    */
  1705.   CXCursor_OMPForDirective = 234,
  1706.  
  1707.   /** OpenMP sections directive.
  1708.    */
  1709.   CXCursor_OMPSectionsDirective = 235,
  1710.  
  1711.   /** OpenMP section directive.
  1712.    */
  1713.   CXCursor_OMPSectionDirective = 236,
  1714.  
  1715.   /** OpenMP single directive.
  1716.    */
  1717.   CXCursor_OMPSingleDirective = 237,
  1718.  
  1719.   /** OpenMP parallel for directive.
  1720.    */
  1721.   CXCursor_OMPParallelForDirective = 238,
  1722.  
  1723.   /** OpenMP parallel sections directive.
  1724.    */
  1725.   CXCursor_OMPParallelSectionsDirective = 239,
  1726.  
  1727.   /** OpenMP task directive.
  1728.    */
  1729.   CXCursor_OMPTaskDirective = 240,
  1730.  
  1731.   /** OpenMP master directive.
  1732.    */
  1733.   CXCursor_OMPMasterDirective = 241,
  1734.  
  1735.   /** OpenMP critical directive.
  1736.    */
  1737.   CXCursor_OMPCriticalDirective = 242,
  1738.  
  1739.   /** OpenMP taskyield directive.
  1740.    */
  1741.   CXCursor_OMPTaskyieldDirective = 243,
  1742.  
  1743.   /** OpenMP barrier directive.
  1744.    */
  1745.   CXCursor_OMPBarrierDirective = 244,
  1746.  
  1747.   /** OpenMP taskwait directive.
  1748.    */
  1749.   CXCursor_OMPTaskwaitDirective = 245,
  1750.  
  1751.   /** OpenMP flush directive.
  1752.    */
  1753.   CXCursor_OMPFlushDirective = 246,
  1754.  
  1755.   /** Windows Structured Exception Handling's leave statement.
  1756.    */
  1757.   CXCursor_SEHLeaveStmt = 247,
  1758.  
  1759.   /** OpenMP ordered directive.
  1760.    */
  1761.   CXCursor_OMPOrderedDirective = 248,
  1762.  
  1763.   /** OpenMP atomic directive.
  1764.    */
  1765.   CXCursor_OMPAtomicDirective = 249,
  1766.  
  1767.   /** OpenMP for SIMD directive.
  1768.    */
  1769.   CXCursor_OMPForSimdDirective = 250,
  1770.  
  1771.   /** OpenMP parallel for SIMD directive.
  1772.    */
  1773.   CXCursor_OMPParallelForSimdDirective = 251,
  1774.  
  1775.   /** OpenMP target directive.
  1776.    */
  1777.   CXCursor_OMPTargetDirective = 252,
  1778.  
  1779.   /** OpenMP teams directive.
  1780.    */
  1781.   CXCursor_OMPTeamsDirective = 253,
  1782.  
  1783.   /** OpenMP taskgroup directive.
  1784.    */
  1785.   CXCursor_OMPTaskgroupDirective = 254,
  1786.  
  1787.   /** OpenMP cancellation point directive.
  1788.    */
  1789.   CXCursor_OMPCancellationPointDirective = 255,
  1790.  
  1791.   /** OpenMP cancel directive.
  1792.    */
  1793.   CXCursor_OMPCancelDirective = 256,
  1794.  
  1795.   /** OpenMP target data directive.
  1796.    */
  1797.   CXCursor_OMPTargetDataDirective = 257,
  1798.  
  1799.   /** OpenMP taskloop directive.
  1800.    */
  1801.   CXCursor_OMPTaskLoopDirective = 258,
  1802.  
  1803.   /** OpenMP taskloop simd directive.
  1804.    */
  1805.   CXCursor_OMPTaskLoopSimdDirective = 259,
  1806.  
  1807.   /** OpenMP distribute directive.
  1808.    */
  1809.   CXCursor_OMPDistributeDirective = 260,
  1810.  
  1811.   /** OpenMP target enter data directive.
  1812.    */
  1813.   CXCursor_OMPTargetEnterDataDirective = 261,
  1814.  
  1815.   /** OpenMP target exit data directive.
  1816.    */
  1817.   CXCursor_OMPTargetExitDataDirective = 262,
  1818.  
  1819.   /** OpenMP target parallel directive.
  1820.    */
  1821.   CXCursor_OMPTargetParallelDirective = 263,
  1822.  
  1823.   /** OpenMP target parallel for directive.
  1824.    */
  1825.   CXCursor_OMPTargetParallelForDirective = 264,
  1826.  
  1827.   /** OpenMP target update directive.
  1828.    */
  1829.   CXCursor_OMPTargetUpdateDirective = 265,
  1830.  
  1831.   /** OpenMP distribute parallel for directive.
  1832.    */
  1833.   CXCursor_OMPDistributeParallelForDirective = 266,
  1834.  
  1835.   /** OpenMP distribute parallel for simd directive.
  1836.    */
  1837.   CXCursor_OMPDistributeParallelForSimdDirective = 267,
  1838.  
  1839.   /** OpenMP distribute simd directive.
  1840.    */
  1841.   CXCursor_OMPDistributeSimdDirective = 268,
  1842.  
  1843.   /** OpenMP target parallel for simd directive.
  1844.    */
  1845.   CXCursor_OMPTargetParallelForSimdDirective = 269,
  1846.  
  1847.   /** OpenMP target simd directive.
  1848.    */
  1849.   CXCursor_OMPTargetSimdDirective = 270,
  1850.  
  1851.   /** OpenMP teams distribute directive.
  1852.    */
  1853.   CXCursor_OMPTeamsDistributeDirective = 271,
  1854.  
  1855.   /** OpenMP teams distribute simd directive.
  1856.    */
  1857.   CXCursor_OMPTeamsDistributeSimdDirective = 272,
  1858.  
  1859.   /** OpenMP teams distribute parallel for simd directive.
  1860.    */
  1861.   CXCursor_OMPTeamsDistributeParallelForSimdDirective = 273,
  1862.  
  1863.   /** OpenMP teams distribute parallel for directive.
  1864.    */
  1865.   CXCursor_OMPTeamsDistributeParallelForDirective = 274,
  1866.  
  1867.   /** OpenMP target teams directive.
  1868.    */
  1869.   CXCursor_OMPTargetTeamsDirective = 275,
  1870.  
  1871.   /** OpenMP target teams distribute directive.
  1872.    */
  1873.   CXCursor_OMPTargetTeamsDistributeDirective = 276,
  1874.  
  1875.   /** OpenMP target teams distribute parallel for directive.
  1876.    */
  1877.   CXCursor_OMPTargetTeamsDistributeParallelForDirective = 277,
  1878.  
  1879.   /** OpenMP target teams distribute parallel for simd directive.
  1880.    */
  1881.   CXCursor_OMPTargetTeamsDistributeParallelForSimdDirective = 278,
  1882.  
  1883.   /** OpenMP target teams distribute simd directive.
  1884.    */
  1885.   CXCursor_OMPTargetTeamsDistributeSimdDirective = 279,
  1886.  
  1887.   /** C++2a std::bit_cast expression.
  1888.    */
  1889.   CXCursor_BuiltinBitCastExpr = 280,
  1890.  
  1891.   /** OpenMP master taskloop directive.
  1892.    */
  1893.   CXCursor_OMPMasterTaskLoopDirective = 281,
  1894.  
  1895.   /** OpenMP parallel master taskloop directive.
  1896.    */
  1897.   CXCursor_OMPParallelMasterTaskLoopDirective = 282,
  1898.  
  1899.   /** OpenMP master taskloop simd directive.
  1900.    */
  1901.   CXCursor_OMPMasterTaskLoopSimdDirective = 283,
  1902.  
  1903.   /** OpenMP parallel master taskloop simd directive.
  1904.    */
  1905.   CXCursor_OMPParallelMasterTaskLoopSimdDirective = 284,
  1906.  
  1907.   /** OpenMP parallel master directive.
  1908.    */
  1909.   CXCursor_OMPParallelMasterDirective = 285,
  1910.  
  1911.   /** OpenMP depobj directive.
  1912.    */
  1913.   CXCursor_OMPDepobjDirective = 286,
  1914.  
  1915.   /** OpenMP scan directive.
  1916.    */
  1917.   CXCursor_OMPScanDirective = 287,
  1918.  
  1919.   /** OpenMP tile directive.
  1920.    */
  1921.   CXCursor_OMPTileDirective = 288,
  1922.  
  1923.   /** OpenMP canonical loop.
  1924.    */
  1925.   CXCursor_OMPCanonicalLoop = 289,
  1926.  
  1927.   /** OpenMP interop directive.
  1928.    */
  1929.   CXCursor_OMPInteropDirective = 290,
  1930.  
  1931.   /** OpenMP dispatch directive.
  1932.    */
  1933.   CXCursor_OMPDispatchDirective = 291,
  1934.  
  1935.   /** OpenMP masked directive.
  1936.    */
  1937.   CXCursor_OMPMaskedDirective = 292,
  1938.  
  1939.   /** OpenMP unroll directive.
  1940.    */
  1941.   CXCursor_OMPUnrollDirective = 293,
  1942.  
  1943.   /** OpenMP metadirective directive.
  1944.    */
  1945.   CXCursor_OMPMetaDirective = 294,
  1946.  
  1947.   /** OpenMP loop directive.
  1948.    */
  1949.   CXCursor_OMPGenericLoopDirective = 295,
  1950.  
  1951.   /** OpenMP teams loop directive.
  1952.    */
  1953.   CXCursor_OMPTeamsGenericLoopDirective = 296,
  1954.  
  1955.   /** OpenMP target teams loop directive.
  1956.    */
  1957.   CXCursor_OMPTargetTeamsGenericLoopDirective = 297,
  1958.  
  1959.   /** OpenMP parallel loop directive.
  1960.    */
  1961.   CXCursor_OMPParallelGenericLoopDirective = 298,
  1962.  
  1963.   /** OpenMP target parallel loop directive.
  1964.    */
  1965.   CXCursor_OMPTargetParallelGenericLoopDirective = 299,
  1966.  
  1967.   /** OpenMP parallel masked directive.
  1968.    */
  1969.   CXCursor_OMPParallelMaskedDirective = 300,
  1970.  
  1971.   /** OpenMP masked taskloop directive.
  1972.    */
  1973.   CXCursor_OMPMaskedTaskLoopDirective = 301,
  1974.  
  1975.   /** OpenMP masked taskloop simd directive.
  1976.    */
  1977.   CXCursor_OMPMaskedTaskLoopSimdDirective = 302,
  1978.  
  1979.   /** OpenMP parallel masked taskloop directive.
  1980.    */
  1981.   CXCursor_OMPParallelMaskedTaskLoopDirective = 303,
  1982.  
  1983.   /** OpenMP parallel masked taskloop simd directive.
  1984.    */
  1985.   CXCursor_OMPParallelMaskedTaskLoopSimdDirective = 304,
  1986.  
  1987.   /** OpenMP error directive.
  1988.    */
  1989.   CXCursor_OMPErrorDirective = 305,
  1990.  
  1991.   CXCursor_LastStmt = CXCursor_OMPErrorDirective,
  1992.  
  1993.   /**
  1994.    * Cursor that represents the translation unit itself.
  1995.    *
  1996.    * The translation unit cursor exists primarily to act as the root
  1997.    * cursor for traversing the contents of a translation unit.
  1998.    */
  1999.   CXCursor_TranslationUnit = 350,
  2000.  
  2001.   /* Attributes */
  2002.   CXCursor_FirstAttr = 400,
  2003.   /**
  2004.    * An attribute whose specific kind is not exposed via this
  2005.    * interface.
  2006.    */
  2007.   CXCursor_UnexposedAttr = 400,
  2008.  
  2009.   CXCursor_IBActionAttr = 401,
  2010.   CXCursor_IBOutletAttr = 402,
  2011.   CXCursor_IBOutletCollectionAttr = 403,
  2012.   CXCursor_CXXFinalAttr = 404,
  2013.   CXCursor_CXXOverrideAttr = 405,
  2014.   CXCursor_AnnotateAttr = 406,
  2015.   CXCursor_AsmLabelAttr = 407,
  2016.   CXCursor_PackedAttr = 408,
  2017.   CXCursor_PureAttr = 409,
  2018.   CXCursor_ConstAttr = 410,
  2019.   CXCursor_NoDuplicateAttr = 411,
  2020.   CXCursor_CUDAConstantAttr = 412,
  2021.   CXCursor_CUDADeviceAttr = 413,
  2022.   CXCursor_CUDAGlobalAttr = 414,
  2023.   CXCursor_CUDAHostAttr = 415,
  2024.   CXCursor_CUDASharedAttr = 416,
  2025.   CXCursor_VisibilityAttr = 417,
  2026.   CXCursor_DLLExport = 418,
  2027.   CXCursor_DLLImport = 419,
  2028.   CXCursor_NSReturnsRetained = 420,
  2029.   CXCursor_NSReturnsNotRetained = 421,
  2030.   CXCursor_NSReturnsAutoreleased = 422,
  2031.   CXCursor_NSConsumesSelf = 423,
  2032.   CXCursor_NSConsumed = 424,
  2033.   CXCursor_ObjCException = 425,
  2034.   CXCursor_ObjCNSObject = 426,
  2035.   CXCursor_ObjCIndependentClass = 427,
  2036.   CXCursor_ObjCPreciseLifetime = 428,
  2037.   CXCursor_ObjCReturnsInnerPointer = 429,
  2038.   CXCursor_ObjCRequiresSuper = 430,
  2039.   CXCursor_ObjCRootClass = 431,
  2040.   CXCursor_ObjCSubclassingRestricted = 432,
  2041.   CXCursor_ObjCExplicitProtocolImpl = 433,
  2042.   CXCursor_ObjCDesignatedInitializer = 434,
  2043.   CXCursor_ObjCRuntimeVisible = 435,
  2044.   CXCursor_ObjCBoxable = 436,
  2045.   CXCursor_FlagEnum = 437,
  2046.   CXCursor_ConvergentAttr = 438,
  2047.   CXCursor_WarnUnusedAttr = 439,
  2048.   CXCursor_WarnUnusedResultAttr = 440,
  2049.   CXCursor_AlignedAttr = 441,
  2050.   CXCursor_LastAttr = CXCursor_AlignedAttr,
  2051.  
  2052.   /* Preprocessing */
  2053.   CXCursor_PreprocessingDirective = 500,
  2054.   CXCursor_MacroDefinition = 501,
  2055.   CXCursor_MacroExpansion = 502,
  2056.   CXCursor_MacroInstantiation = CXCursor_MacroExpansion,
  2057.   CXCursor_InclusionDirective = 503,
  2058.   CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective,
  2059.   CXCursor_LastPreprocessing = CXCursor_InclusionDirective,
  2060.  
  2061.   /* Extra Declarations */
  2062.   /**
  2063.    * A module import declaration.
  2064.    */
  2065.   CXCursor_ModuleImportDecl = 600,
  2066.   CXCursor_TypeAliasTemplateDecl = 601,
  2067.   /**
  2068.    * A static_assert or _Static_assert node
  2069.    */
  2070.   CXCursor_StaticAssert = 602,
  2071.   /**
  2072.    * a friend declaration.
  2073.    */
  2074.   CXCursor_FriendDecl = 603,
  2075.   /**
  2076.    * a concept declaration.
  2077.    */
  2078.   CXCursor_ConceptDecl = 604,
  2079.  
  2080.   CXCursor_FirstExtraDecl = CXCursor_ModuleImportDecl,
  2081.   CXCursor_LastExtraDecl = CXCursor_ConceptDecl,
  2082.  
  2083.   /**
  2084.    * A code completion overload candidate.
  2085.    */
  2086.   CXCursor_OverloadCandidate = 700
  2087. };
  2088.  
  2089. /**
  2090.  * A cursor representing some element in the abstract syntax tree for
  2091.  * a translation unit.
  2092.  *
  2093.  * The cursor abstraction unifies the different kinds of entities in a
  2094.  * program--declaration, statements, expressions, references to declarations,
  2095.  * etc.--under a single "cursor" abstraction with a common set of operations.
  2096.  * Common operation for a cursor include: getting the physical location in
  2097.  * a source file where the cursor points, getting the name associated with a
  2098.  * cursor, and retrieving cursors for any child nodes of a particular cursor.
  2099.  *
  2100.  * Cursors can be produced in two specific ways.
  2101.  * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
  2102.  * from which one can use clang_visitChildren() to explore the rest of the
  2103.  * translation unit. clang_getCursor() maps from a physical source location
  2104.  * to the entity that resides at that location, allowing one to map from the
  2105.  * source code into the AST.
  2106.  */
  2107. typedef struct {
  2108.   enum CXCursorKind kind;
  2109.   int xdata;
  2110.   const void *data[3];
  2111. } CXCursor;
  2112.  
  2113. /**
  2114.  * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
  2115.  *
  2116.  * @{
  2117.  */
  2118.  
  2119. /**
  2120.  * Retrieve the NULL cursor, which represents no entity.
  2121.  */
  2122. CINDEX_LINKAGE CXCursor clang_getNullCursor(void);
  2123.  
  2124. /**
  2125.  * Retrieve the cursor that represents the given translation unit.
  2126.  *
  2127.  * The translation unit cursor can be used to start traversing the
  2128.  * various declarations within the given translation unit.
  2129.  */
  2130. CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit);
  2131.  
  2132. /**
  2133.  * Determine whether two cursors are equivalent.
  2134.  */
  2135. CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor);
  2136.  
  2137. /**
  2138.  * Returns non-zero if \p cursor is null.
  2139.  */
  2140. CINDEX_LINKAGE int clang_Cursor_isNull(CXCursor cursor);
  2141.  
  2142. /**
  2143.  * Compute a hash value for the given cursor.
  2144.  */
  2145. CINDEX_LINKAGE unsigned clang_hashCursor(CXCursor);
  2146.  
  2147. /**
  2148.  * Retrieve the kind of the given cursor.
  2149.  */
  2150. CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
  2151.  
  2152. /**
  2153.  * Determine whether the given cursor kind represents a declaration.
  2154.  */
  2155. CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
  2156.  
  2157. /**
  2158.  * Determine whether the given declaration is invalid.
  2159.  *
  2160.  * A declaration is invalid if it could not be parsed successfully.
  2161.  *
  2162.  * \returns non-zero if the cursor represents a declaration and it is
  2163.  * invalid, otherwise NULL.
  2164.  */
  2165. CINDEX_LINKAGE unsigned clang_isInvalidDeclaration(CXCursor);
  2166.  
  2167. /**
  2168.  * Determine whether the given cursor kind represents a simple
  2169.  * reference.
  2170.  *
  2171.  * Note that other kinds of cursors (such as expressions) can also refer to
  2172.  * other cursors. Use clang_getCursorReferenced() to determine whether a
  2173.  * particular cursor refers to another entity.
  2174.  */
  2175. CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
  2176.  
  2177. /**
  2178.  * Determine whether the given cursor kind represents an expression.
  2179.  */
  2180. CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind);
  2181.  
  2182. /**
  2183.  * Determine whether the given cursor kind represents a statement.
  2184.  */
  2185. CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind);
  2186.  
  2187. /**
  2188.  * Determine whether the given cursor kind represents an attribute.
  2189.  */
  2190. CINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind);
  2191.  
  2192. /**
  2193.  * Determine whether the given cursor has any attributes.
  2194.  */
  2195. CINDEX_LINKAGE unsigned clang_Cursor_hasAttrs(CXCursor C);
  2196.  
  2197. /**
  2198.  * Determine whether the given cursor kind represents an invalid
  2199.  * cursor.
  2200.  */
  2201. CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
  2202.  
  2203. /**
  2204.  * Determine whether the given cursor kind represents a translation
  2205.  * unit.
  2206.  */
  2207. CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind);
  2208.  
  2209. /***
  2210.  * Determine whether the given cursor represents a preprocessing
  2211.  * element, such as a preprocessor directive or macro instantiation.
  2212.  */
  2213. CINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind);
  2214.  
  2215. /***
  2216.  * Determine whether the given cursor represents a currently
  2217.  *  unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).
  2218.  */
  2219. CINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind);
  2220.  
  2221. /**
  2222.  * Describe the linkage of the entity referred to by a cursor.
  2223.  */
  2224. enum CXLinkageKind {
  2225.   /** This value indicates that no linkage information is available
  2226.    * for a provided CXCursor. */
  2227.   CXLinkage_Invalid,
  2228.   /**
  2229.    * This is the linkage for variables, parameters, and so on that
  2230.    *  have automatic storage.  This covers normal (non-extern) local variables.
  2231.    */
  2232.   CXLinkage_NoLinkage,
  2233.   /** This is the linkage for static variables and static functions. */
  2234.   CXLinkage_Internal,
  2235.   /** This is the linkage for entities with external linkage that live
  2236.    * in C++ anonymous namespaces.*/
  2237.   CXLinkage_UniqueExternal,
  2238.   /** This is the linkage for entities with true, external linkage. */
  2239.   CXLinkage_External
  2240. };
  2241.  
  2242. /**
  2243.  * Determine the linkage of the entity referred to by a given cursor.
  2244.  */
  2245. CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor);
  2246.  
  2247. enum CXVisibilityKind {
  2248.   /** This value indicates that no visibility information is available
  2249.    * for a provided CXCursor. */
  2250.   CXVisibility_Invalid,
  2251.  
  2252.   /** Symbol not seen by the linker. */
  2253.   CXVisibility_Hidden,
  2254.   /** Symbol seen by the linker but resolves to a symbol inside this object. */
  2255.   CXVisibility_Protected,
  2256.   /** Symbol seen by the linker and acts like a normal symbol. */
  2257.   CXVisibility_Default
  2258. };
  2259.  
  2260. /**
  2261.  * Describe the visibility of the entity referred to by a cursor.
  2262.  *
  2263.  * This returns the default visibility if not explicitly specified by
  2264.  * a visibility attribute. The default visibility may be changed by
  2265.  * commandline arguments.
  2266.  *
  2267.  * \param cursor The cursor to query.
  2268.  *
  2269.  * \returns The visibility of the cursor.
  2270.  */
  2271. CINDEX_LINKAGE enum CXVisibilityKind clang_getCursorVisibility(CXCursor cursor);
  2272.  
  2273. /**
  2274.  * Determine the availability of the entity that this cursor refers to,
  2275.  * taking the current target platform into account.
  2276.  *
  2277.  * \param cursor The cursor to query.
  2278.  *
  2279.  * \returns The availability of the cursor.
  2280.  */
  2281. CINDEX_LINKAGE enum CXAvailabilityKind
  2282. clang_getCursorAvailability(CXCursor cursor);
  2283.  
  2284. /**
  2285.  * Describes the availability of a given entity on a particular platform, e.g.,
  2286.  * a particular class might only be available on Mac OS 10.7 or newer.
  2287.  */
  2288. typedef struct CXPlatformAvailability {
  2289.   /**
  2290.    * A string that describes the platform for which this structure
  2291.    * provides availability information.
  2292.    *
  2293.    * Possible values are "ios" or "macos".
  2294.    */
  2295.   CXString Platform;
  2296.   /**
  2297.    * The version number in which this entity was introduced.
  2298.    */
  2299.   CXVersion Introduced;
  2300.   /**
  2301.    * The version number in which this entity was deprecated (but is
  2302.    * still available).
  2303.    */
  2304.   CXVersion Deprecated;
  2305.   /**
  2306.    * The version number in which this entity was obsoleted, and therefore
  2307.    * is no longer available.
  2308.    */
  2309.   CXVersion Obsoleted;
  2310.   /**
  2311.    * Whether the entity is unconditionally unavailable on this platform.
  2312.    */
  2313.   int Unavailable;
  2314.   /**
  2315.    * An optional message to provide to a user of this API, e.g., to
  2316.    * suggest replacement APIs.
  2317.    */
  2318.   CXString Message;
  2319. } CXPlatformAvailability;
  2320.  
  2321. /**
  2322.  * Determine the availability of the entity that this cursor refers to
  2323.  * on any platforms for which availability information is known.
  2324.  *
  2325.  * \param cursor The cursor to query.
  2326.  *
  2327.  * \param always_deprecated If non-NULL, will be set to indicate whether the
  2328.  * entity is deprecated on all platforms.
  2329.  *
  2330.  * \param deprecated_message If non-NULL, will be set to the message text
  2331.  * provided along with the unconditional deprecation of this entity. The client
  2332.  * is responsible for deallocating this string.
  2333.  *
  2334.  * \param always_unavailable If non-NULL, will be set to indicate whether the
  2335.  * entity is unavailable on all platforms.
  2336.  *
  2337.  * \param unavailable_message If non-NULL, will be set to the message text
  2338.  * provided along with the unconditional unavailability of this entity. The
  2339.  * client is responsible for deallocating this string.
  2340.  *
  2341.  * \param availability If non-NULL, an array of CXPlatformAvailability instances
  2342.  * that will be populated with platform availability information, up to either
  2343.  * the number of platforms for which availability information is available (as
  2344.  * returned by this function) or \c availability_size, whichever is smaller.
  2345.  *
  2346.  * \param availability_size The number of elements available in the
  2347.  * \c availability array.
  2348.  *
  2349.  * \returns The number of platforms (N) for which availability information is
  2350.  * available (which is unrelated to \c availability_size).
  2351.  *
  2352.  * Note that the client is responsible for calling
  2353.  * \c clang_disposeCXPlatformAvailability to free each of the
  2354.  * platform-availability structures returned. There are
  2355.  * \c min(N, availability_size) such structures.
  2356.  */
  2357. CINDEX_LINKAGE int clang_getCursorPlatformAvailability(
  2358.     CXCursor cursor, int *always_deprecated, CXString *deprecated_message,
  2359.     int *always_unavailable, CXString *unavailable_message,
  2360.     CXPlatformAvailability *availability, int availability_size);
  2361.  
  2362. /**
  2363.  * Free the memory associated with a \c CXPlatformAvailability structure.
  2364.  */
  2365. CINDEX_LINKAGE void
  2366. clang_disposeCXPlatformAvailability(CXPlatformAvailability *availability);
  2367.  
  2368. /**
  2369.  * If cursor refers to a variable declaration and it has initializer returns
  2370.  * cursor referring to the initializer otherwise return null cursor.
  2371.  */
  2372. CINDEX_LINKAGE CXCursor clang_Cursor_getVarDeclInitializer(CXCursor cursor);
  2373.  
  2374. /**
  2375.  * If cursor refers to a variable declaration that has global storage returns 1.
  2376.  * If cursor refers to a variable declaration that doesn't have global storage
  2377.  * returns 0. Otherwise returns -1.
  2378.  */
  2379. CINDEX_LINKAGE int clang_Cursor_hasVarDeclGlobalStorage(CXCursor cursor);
  2380.  
  2381. /**
  2382.  * If cursor refers to a variable declaration that has external storage
  2383.  * returns 1. If cursor refers to a variable declaration that doesn't have
  2384.  * external storage returns 0. Otherwise returns -1.
  2385.  */
  2386. CINDEX_LINKAGE int clang_Cursor_hasVarDeclExternalStorage(CXCursor cursor);
  2387.  
  2388. /**
  2389.  * Describe the "language" of the entity referred to by a cursor.
  2390.  */
  2391. enum CXLanguageKind {
  2392.   CXLanguage_Invalid = 0,
  2393.   CXLanguage_C,
  2394.   CXLanguage_ObjC,
  2395.   CXLanguage_CPlusPlus
  2396. };
  2397.  
  2398. /**
  2399.  * Determine the "language" of the entity referred to by a given cursor.
  2400.  */
  2401. CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor);
  2402.  
  2403. /**
  2404.  * Describe the "thread-local storage (TLS) kind" of the declaration
  2405.  * referred to by a cursor.
  2406.  */
  2407. enum CXTLSKind { CXTLS_None = 0, CXTLS_Dynamic, CXTLS_Static };
  2408.  
  2409. /**
  2410.  * Determine the "thread-local storage (TLS) kind" of the declaration
  2411.  * referred to by a cursor.
  2412.  */
  2413. CINDEX_LINKAGE enum CXTLSKind clang_getCursorTLSKind(CXCursor cursor);
  2414.  
  2415. /**
  2416.  * Returns the translation unit that a cursor originated from.
  2417.  */
  2418. CINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor);
  2419.  
  2420. /**
  2421.  * A fast container representing a set of CXCursors.
  2422.  */
  2423. typedef struct CXCursorSetImpl *CXCursorSet;
  2424.  
  2425. /**
  2426.  * Creates an empty CXCursorSet.
  2427.  */
  2428. CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(void);
  2429.  
  2430. /**
  2431.  * Disposes a CXCursorSet and releases its associated memory.
  2432.  */
  2433. CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset);
  2434.  
  2435. /**
  2436.  * Queries a CXCursorSet to see if it contains a specific CXCursor.
  2437.  *
  2438.  * \returns non-zero if the set contains the specified cursor.
  2439.  */
  2440. CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset,
  2441.                                                    CXCursor cursor);
  2442.  
  2443. /**
  2444.  * Inserts a CXCursor into a CXCursorSet.
  2445.  *
  2446.  * \returns zero if the CXCursor was already in the set, and non-zero otherwise.
  2447.  */
  2448. CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset,
  2449.                                                  CXCursor cursor);
  2450.  
  2451. /**
  2452.  * Determine the semantic parent of the given cursor.
  2453.  *
  2454.  * The semantic parent of a cursor is the cursor that semantically contains
  2455.  * the given \p cursor. For many declarations, the lexical and semantic parents
  2456.  * are equivalent (the lexical parent is returned by
  2457.  * \c clang_getCursorLexicalParent()). They diverge when declarations or
  2458.  * definitions are provided out-of-line. For example:
  2459.  *
  2460.  * \code
  2461.  * class C {
  2462.  *  void f();
  2463.  * };
  2464.  *
  2465.  * void C::f() { }
  2466.  * \endcode
  2467.  *
  2468.  * In the out-of-line definition of \c C::f, the semantic parent is
  2469.  * the class \c C, of which this function is a member. The lexical parent is
  2470.  * the place where the declaration actually occurs in the source code; in this
  2471.  * case, the definition occurs in the translation unit. In general, the
  2472.  * lexical parent for a given entity can change without affecting the semantics
  2473.  * of the program, and the lexical parent of different declarations of the
  2474.  * same entity may be different. Changing the semantic parent of a declaration,
  2475.  * on the other hand, can have a major impact on semantics, and redeclarations
  2476.  * of a particular entity should all have the same semantic context.
  2477.  *
  2478.  * In the example above, both declarations of \c C::f have \c C as their
  2479.  * semantic context, while the lexical context of the first \c C::f is \c C
  2480.  * and the lexical context of the second \c C::f is the translation unit.
  2481.  *
  2482.  * For global declarations, the semantic parent is the translation unit.
  2483.  */
  2484. CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor);
  2485.  
  2486. /**
  2487.  * Determine the lexical parent of the given cursor.
  2488.  *
  2489.  * The lexical parent of a cursor is the cursor in which the given \p cursor
  2490.  * was actually written. For many declarations, the lexical and semantic parents
  2491.  * are equivalent (the semantic parent is returned by
  2492.  * \c clang_getCursorSemanticParent()). They diverge when declarations or
  2493.  * definitions are provided out-of-line. For example:
  2494.  *
  2495.  * \code
  2496.  * class C {
  2497.  *  void f();
  2498.  * };
  2499.  *
  2500.  * void C::f() { }
  2501.  * \endcode
  2502.  *
  2503.  * In the out-of-line definition of \c C::f, the semantic parent is
  2504.  * the class \c C, of which this function is a member. The lexical parent is
  2505.  * the place where the declaration actually occurs in the source code; in this
  2506.  * case, the definition occurs in the translation unit. In general, the
  2507.  * lexical parent for a given entity can change without affecting the semantics
  2508.  * of the program, and the lexical parent of different declarations of the
  2509.  * same entity may be different. Changing the semantic parent of a declaration,
  2510.  * on the other hand, can have a major impact on semantics, and redeclarations
  2511.  * of a particular entity should all have the same semantic context.
  2512.  *
  2513.  * In the example above, both declarations of \c C::f have \c C as their
  2514.  * semantic context, while the lexical context of the first \c C::f is \c C
  2515.  * and the lexical context of the second \c C::f is the translation unit.
  2516.  *
  2517.  * For declarations written in the global scope, the lexical parent is
  2518.  * the translation unit.
  2519.  */
  2520. CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor);
  2521.  
  2522. /**
  2523.  * Determine the set of methods that are overridden by the given
  2524.  * method.
  2525.  *
  2526.  * In both Objective-C and C++, a method (aka virtual member function,
  2527.  * in C++) can override a virtual method in a base class. For
  2528.  * Objective-C, a method is said to override any method in the class's
  2529.  * base class, its protocols, or its categories' protocols, that has the same
  2530.  * selector and is of the same kind (class or instance).
  2531.  * If no such method exists, the search continues to the class's superclass,
  2532.  * its protocols, and its categories, and so on. A method from an Objective-C
  2533.  * implementation is considered to override the same methods as its
  2534.  * corresponding method in the interface.
  2535.  *
  2536.  * For C++, a virtual member function overrides any virtual member
  2537.  * function with the same signature that occurs in its base
  2538.  * classes. With multiple inheritance, a virtual member function can
  2539.  * override several virtual member functions coming from different
  2540.  * base classes.
  2541.  *
  2542.  * In all cases, this function determines the immediate overridden
  2543.  * method, rather than all of the overridden methods. For example, if
  2544.  * a method is originally declared in a class A, then overridden in B
  2545.  * (which in inherits from A) and also in C (which inherited from B),
  2546.  * then the only overridden method returned from this function when
  2547.  * invoked on C's method will be B's method. The client may then
  2548.  * invoke this function again, given the previously-found overridden
  2549.  * methods, to map out the complete method-override set.
  2550.  *
  2551.  * \param cursor A cursor representing an Objective-C or C++
  2552.  * method. This routine will compute the set of methods that this
  2553.  * method overrides.
  2554.  *
  2555.  * \param overridden A pointer whose pointee will be replaced with a
  2556.  * pointer to an array of cursors, representing the set of overridden
  2557.  * methods. If there are no overridden methods, the pointee will be
  2558.  * set to NULL. The pointee must be freed via a call to
  2559.  * \c clang_disposeOverriddenCursors().
  2560.  *
  2561.  * \param num_overridden A pointer to the number of overridden
  2562.  * functions, will be set to the number of overridden functions in the
  2563.  * array pointed to by \p overridden.
  2564.  */
  2565. CINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor,
  2566.                                                CXCursor **overridden,
  2567.                                                unsigned *num_overridden);
  2568.  
  2569. /**
  2570.  * Free the set of overridden cursors returned by \c
  2571.  * clang_getOverriddenCursors().
  2572.  */
  2573. CINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden);
  2574.  
  2575. /**
  2576.  * Retrieve the file that is included by the given inclusion directive
  2577.  * cursor.
  2578.  */
  2579. CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor);
  2580.  
  2581. /**
  2582.  * @}
  2583.  */
  2584.  
  2585. /**
  2586.  * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
  2587.  *
  2588.  * Cursors represent a location within the Abstract Syntax Tree (AST). These
  2589.  * routines help map between cursors and the physical locations where the
  2590.  * described entities occur in the source code. The mapping is provided in
  2591.  * both directions, so one can map from source code to the AST and back.
  2592.  *
  2593.  * @{
  2594.  */
  2595.  
  2596. /**
  2597.  * Map a source location to the cursor that describes the entity at that
  2598.  * location in the source code.
  2599.  *
  2600.  * clang_getCursor() maps an arbitrary source location within a translation
  2601.  * unit down to the most specific cursor that describes the entity at that
  2602.  * location. For example, given an expression \c x + y, invoking
  2603.  * clang_getCursor() with a source location pointing to "x" will return the
  2604.  * cursor for "x"; similarly for "y". If the cursor points anywhere between
  2605.  * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
  2606.  * will return a cursor referring to the "+" expression.
  2607.  *
  2608.  * \returns a cursor representing the entity at the given source location, or
  2609.  * a NULL cursor if no such entity can be found.
  2610.  */
  2611. CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation);
  2612.  
  2613. /**
  2614.  * Retrieve the physical location of the source constructor referenced
  2615.  * by the given cursor.
  2616.  *
  2617.  * The location of a declaration is typically the location of the name of that
  2618.  * declaration, where the name of that declaration would occur if it is
  2619.  * unnamed, or some keyword that introduces that particular declaration.
  2620.  * The location of a reference is where that reference occurs within the
  2621.  * source code.
  2622.  */
  2623. CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor);
  2624.  
  2625. /**
  2626.  * Retrieve the physical extent of the source construct referenced by
  2627.  * the given cursor.
  2628.  *
  2629.  * The extent of a cursor starts with the file/line/column pointing at the
  2630.  * first character within the source construct that the cursor refers to and
  2631.  * ends with the last character within that source construct. For a
  2632.  * declaration, the extent covers the declaration itself. For a reference,
  2633.  * the extent covers the location of the reference (e.g., where the referenced
  2634.  * entity was actually used).
  2635.  */
  2636. CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor);
  2637.  
  2638. /**
  2639.  * @}
  2640.  */
  2641.  
  2642. /**
  2643.  * \defgroup CINDEX_TYPES Type information for CXCursors
  2644.  *
  2645.  * @{
  2646.  */
  2647.  
  2648. /**
  2649.  * Describes the kind of type
  2650.  */
  2651. enum CXTypeKind {
  2652.   /**
  2653.    * Represents an invalid type (e.g., where no type is available).
  2654.    */
  2655.   CXType_Invalid = 0,
  2656.  
  2657.   /**
  2658.    * A type whose specific kind is not exposed via this
  2659.    * interface.
  2660.    */
  2661.   CXType_Unexposed = 1,
  2662.  
  2663.   /* Builtin types */
  2664.   CXType_Void = 2,
  2665.   CXType_Bool = 3,
  2666.   CXType_Char_U = 4,
  2667.   CXType_UChar = 5,
  2668.   CXType_Char16 = 6,
  2669.   CXType_Char32 = 7,
  2670.   CXType_UShort = 8,
  2671.   CXType_UInt = 9,
  2672.   CXType_ULong = 10,
  2673.   CXType_ULongLong = 11,
  2674.   CXType_UInt128 = 12,
  2675.   CXType_Char_S = 13,
  2676.   CXType_SChar = 14,
  2677.   CXType_WChar = 15,
  2678.   CXType_Short = 16,
  2679.   CXType_Int = 17,
  2680.   CXType_Long = 18,
  2681.   CXType_LongLong = 19,
  2682.   CXType_Int128 = 20,
  2683.   CXType_Float = 21,
  2684.   CXType_Double = 22,
  2685.   CXType_LongDouble = 23,
  2686.   CXType_NullPtr = 24,
  2687.   CXType_Overload = 25,
  2688.   CXType_Dependent = 26,
  2689.   CXType_ObjCId = 27,
  2690.   CXType_ObjCClass = 28,
  2691.   CXType_ObjCSel = 29,
  2692.   CXType_Float128 = 30,
  2693.   CXType_Half = 31,
  2694.   CXType_Float16 = 32,
  2695.   CXType_ShortAccum = 33,
  2696.   CXType_Accum = 34,
  2697.   CXType_LongAccum = 35,
  2698.   CXType_UShortAccum = 36,
  2699.   CXType_UAccum = 37,
  2700.   CXType_ULongAccum = 38,
  2701.   CXType_BFloat16 = 39,
  2702.   CXType_Ibm128 = 40,
  2703.   CXType_FirstBuiltin = CXType_Void,
  2704.   CXType_LastBuiltin = CXType_Ibm128,
  2705.  
  2706.   CXType_Complex = 100,
  2707.   CXType_Pointer = 101,
  2708.   CXType_BlockPointer = 102,
  2709.   CXType_LValueReference = 103,
  2710.   CXType_RValueReference = 104,
  2711.   CXType_Record = 105,
  2712.   CXType_Enum = 106,
  2713.   CXType_Typedef = 107,
  2714.   CXType_ObjCInterface = 108,
  2715.   CXType_ObjCObjectPointer = 109,
  2716.   CXType_FunctionNoProto = 110,
  2717.   CXType_FunctionProto = 111,
  2718.   CXType_ConstantArray = 112,
  2719.   CXType_Vector = 113,
  2720.   CXType_IncompleteArray = 114,
  2721.   CXType_VariableArray = 115,
  2722.   CXType_DependentSizedArray = 116,
  2723.   CXType_MemberPointer = 117,
  2724.   CXType_Auto = 118,
  2725.  
  2726.   /**
  2727.    * Represents a type that was referred to using an elaborated type keyword.
  2728.    *
  2729.    * E.g., struct S, or via a qualified name, e.g., N::M::type, or both.
  2730.    */
  2731.   CXType_Elaborated = 119,
  2732.  
  2733.   /* OpenCL PipeType. */
  2734.   CXType_Pipe = 120,
  2735.  
  2736.   /* OpenCL builtin types. */
  2737.   CXType_OCLImage1dRO = 121,
  2738.   CXType_OCLImage1dArrayRO = 122,
  2739.   CXType_OCLImage1dBufferRO = 123,
  2740.   CXType_OCLImage2dRO = 124,
  2741.   CXType_OCLImage2dArrayRO = 125,
  2742.   CXType_OCLImage2dDepthRO = 126,
  2743.   CXType_OCLImage2dArrayDepthRO = 127,
  2744.   CXType_OCLImage2dMSAARO = 128,
  2745.   CXType_OCLImage2dArrayMSAARO = 129,
  2746.   CXType_OCLImage2dMSAADepthRO = 130,
  2747.   CXType_OCLImage2dArrayMSAADepthRO = 131,
  2748.   CXType_OCLImage3dRO = 132,
  2749.   CXType_OCLImage1dWO = 133,
  2750.   CXType_OCLImage1dArrayWO = 134,
  2751.   CXType_OCLImage1dBufferWO = 135,
  2752.   CXType_OCLImage2dWO = 136,
  2753.   CXType_OCLImage2dArrayWO = 137,
  2754.   CXType_OCLImage2dDepthWO = 138,
  2755.   CXType_OCLImage2dArrayDepthWO = 139,
  2756.   CXType_OCLImage2dMSAAWO = 140,
  2757.   CXType_OCLImage2dArrayMSAAWO = 141,
  2758.   CXType_OCLImage2dMSAADepthWO = 142,
  2759.   CXType_OCLImage2dArrayMSAADepthWO = 143,
  2760.   CXType_OCLImage3dWO = 144,
  2761.   CXType_OCLImage1dRW = 145,
  2762.   CXType_OCLImage1dArrayRW = 146,
  2763.   CXType_OCLImage1dBufferRW = 147,
  2764.   CXType_OCLImage2dRW = 148,
  2765.   CXType_OCLImage2dArrayRW = 149,
  2766.   CXType_OCLImage2dDepthRW = 150,
  2767.   CXType_OCLImage2dArrayDepthRW = 151,
  2768.   CXType_OCLImage2dMSAARW = 152,
  2769.   CXType_OCLImage2dArrayMSAARW = 153,
  2770.   CXType_OCLImage2dMSAADepthRW = 154,
  2771.   CXType_OCLImage2dArrayMSAADepthRW = 155,
  2772.   CXType_OCLImage3dRW = 156,
  2773.   CXType_OCLSampler = 157,
  2774.   CXType_OCLEvent = 158,
  2775.   CXType_OCLQueue = 159,
  2776.   CXType_OCLReserveID = 160,
  2777.  
  2778.   CXType_ObjCObject = 161,
  2779.   CXType_ObjCTypeParam = 162,
  2780.   CXType_Attributed = 163,
  2781.  
  2782.   CXType_OCLIntelSubgroupAVCMcePayload = 164,
  2783.   CXType_OCLIntelSubgroupAVCImePayload = 165,
  2784.   CXType_OCLIntelSubgroupAVCRefPayload = 166,
  2785.   CXType_OCLIntelSubgroupAVCSicPayload = 167,
  2786.   CXType_OCLIntelSubgroupAVCMceResult = 168,
  2787.   CXType_OCLIntelSubgroupAVCImeResult = 169,
  2788.   CXType_OCLIntelSubgroupAVCRefResult = 170,
  2789.   CXType_OCLIntelSubgroupAVCSicResult = 171,
  2790.   CXType_OCLIntelSubgroupAVCImeResultSingleRefStreamout = 172,
  2791.   CXType_OCLIntelSubgroupAVCImeResultDualRefStreamout = 173,
  2792.   CXType_OCLIntelSubgroupAVCImeSingleRefStreamin = 174,
  2793.  
  2794.   CXType_OCLIntelSubgroupAVCImeDualRefStreamin = 175,
  2795.  
  2796.   CXType_ExtVector = 176,
  2797.   CXType_Atomic = 177,
  2798.   CXType_BTFTagAttributed = 178
  2799. };
  2800.  
  2801. /**
  2802.  * Describes the calling convention of a function type
  2803.  */
  2804. enum CXCallingConv {
  2805.   CXCallingConv_Default = 0,
  2806.   CXCallingConv_C = 1,
  2807.   CXCallingConv_X86StdCall = 2,
  2808.   CXCallingConv_X86FastCall = 3,
  2809.   CXCallingConv_X86ThisCall = 4,
  2810.   CXCallingConv_X86Pascal = 5,
  2811.   CXCallingConv_AAPCS = 6,
  2812.   CXCallingConv_AAPCS_VFP = 7,
  2813.   CXCallingConv_X86RegCall = 8,
  2814.   CXCallingConv_IntelOclBicc = 9,
  2815.   CXCallingConv_Win64 = 10,
  2816.   /* Alias for compatibility with older versions of API. */
  2817.   CXCallingConv_X86_64Win64 = CXCallingConv_Win64,
  2818.   CXCallingConv_X86_64SysV = 11,
  2819.   CXCallingConv_X86VectorCall = 12,
  2820.   CXCallingConv_Swift = 13,
  2821.   CXCallingConv_PreserveMost = 14,
  2822.   CXCallingConv_PreserveAll = 15,
  2823.   CXCallingConv_AArch64VectorCall = 16,
  2824.   CXCallingConv_SwiftAsync = 17,
  2825.   CXCallingConv_AArch64SVEPCS = 18,
  2826.  
  2827.   CXCallingConv_Invalid = 100,
  2828.   CXCallingConv_Unexposed = 200
  2829. };
  2830.  
  2831. /**
  2832.  * The type of an element in the abstract syntax tree.
  2833.  *
  2834.  */
  2835. typedef struct {
  2836.   enum CXTypeKind kind;
  2837.   void *data[2];
  2838. } CXType;
  2839.  
  2840. /**
  2841.  * Retrieve the type of a CXCursor (if any).
  2842.  */
  2843. CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C);
  2844.  
  2845. /**
  2846.  * Pretty-print the underlying type using the rules of the
  2847.  * language of the translation unit from which it came.
  2848.  *
  2849.  * If the type is invalid, an empty string is returned.
  2850.  */
  2851. CINDEX_LINKAGE CXString clang_getTypeSpelling(CXType CT);
  2852.  
  2853. /**
  2854.  * Retrieve the underlying type of a typedef declaration.
  2855.  *
  2856.  * If the cursor does not reference a typedef declaration, an invalid type is
  2857.  * returned.
  2858.  */
  2859. CINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C);
  2860.  
  2861. /**
  2862.  * Retrieve the integer type of an enum declaration.
  2863.  *
  2864.  * If the cursor does not reference an enum declaration, an invalid type is
  2865.  * returned.
  2866.  */
  2867. CINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C);
  2868.  
  2869. /**
  2870.  * Retrieve the integer value of an enum constant declaration as a signed
  2871.  *  long long.
  2872.  *
  2873.  * If the cursor does not reference an enum constant declaration, LLONG_MIN is
  2874.  * returned. Since this is also potentially a valid constant value, the kind of
  2875.  * the cursor must be verified before calling this function.
  2876.  */
  2877. CINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C);
  2878.  
  2879. /**
  2880.  * Retrieve the integer value of an enum constant declaration as an unsigned
  2881.  *  long long.
  2882.  *
  2883.  * If the cursor does not reference an enum constant declaration, ULLONG_MAX is
  2884.  * returned. Since this is also potentially a valid constant value, the kind of
  2885.  * the cursor must be verified before calling this function.
  2886.  */
  2887. CINDEX_LINKAGE unsigned long long
  2888. clang_getEnumConstantDeclUnsignedValue(CXCursor C);
  2889.  
  2890. /**
  2891.  * Retrieve the bit width of a bit field declaration as an integer.
  2892.  *
  2893.  * If a cursor that is not a bit field declaration is passed in, -1 is returned.
  2894.  */
  2895. CINDEX_LINKAGE int clang_getFieldDeclBitWidth(CXCursor C);
  2896.  
  2897. /**
  2898.  * Retrieve the number of non-variadic arguments associated with a given
  2899.  * cursor.
  2900.  *
  2901.  * The number of arguments can be determined for calls as well as for
  2902.  * declarations of functions or methods. For other cursors -1 is returned.
  2903.  */
  2904. CINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C);
  2905.  
  2906. /**
  2907.  * Retrieve the argument cursor of a function or method.
  2908.  *
  2909.  * The argument cursor can be determined for calls as well as for declarations
  2910.  * of functions or methods. For other cursors and for invalid indices, an
  2911.  * invalid cursor is returned.
  2912.  */
  2913. CINDEX_LINKAGE CXCursor clang_Cursor_getArgument(CXCursor C, unsigned i);
  2914.  
  2915. /**
  2916.  * Describes the kind of a template argument.
  2917.  *
  2918.  * See the definition of llvm::clang::TemplateArgument::ArgKind for full
  2919.  * element descriptions.
  2920.  */
  2921. enum CXTemplateArgumentKind {
  2922.   CXTemplateArgumentKind_Null,
  2923.   CXTemplateArgumentKind_Type,
  2924.   CXTemplateArgumentKind_Declaration,
  2925.   CXTemplateArgumentKind_NullPtr,
  2926.   CXTemplateArgumentKind_Integral,
  2927.   CXTemplateArgumentKind_Template,
  2928.   CXTemplateArgumentKind_TemplateExpansion,
  2929.   CXTemplateArgumentKind_Expression,
  2930.   CXTemplateArgumentKind_Pack,
  2931.   /* Indicates an error case, preventing the kind from being deduced. */
  2932.   CXTemplateArgumentKind_Invalid
  2933. };
  2934.  
  2935. /**
  2936.  * Returns the number of template args of a function, struct, or class decl
  2937.  * representing a template specialization.
  2938.  *
  2939.  * If the argument cursor cannot be converted into a template function
  2940.  * declaration, -1 is returned.
  2941.  *
  2942.  * For example, for the following declaration and specialization:
  2943.  *   template <typename T, int kInt, bool kBool>
  2944.  *   void foo() { ... }
  2945.  *
  2946.  *   template <>
  2947.  *   void foo<float, -7, true>();
  2948.  *
  2949.  * The value 3 would be returned from this call.
  2950.  */
  2951. CINDEX_LINKAGE int clang_Cursor_getNumTemplateArguments(CXCursor C);
  2952.  
  2953. /**
  2954.  * Retrieve the kind of the I'th template argument of the CXCursor C.
  2955.  *
  2956.  * If the argument CXCursor does not represent a FunctionDecl, StructDecl, or
  2957.  * ClassTemplatePartialSpecialization, an invalid template argument kind is
  2958.  * returned.
  2959.  *
  2960.  * For example, for the following declaration and specialization:
  2961.  *   template <typename T, int kInt, bool kBool>
  2962.  *   void foo() { ... }
  2963.  *
  2964.  *   template <>
  2965.  *   void foo<float, -7, true>();
  2966.  *
  2967.  * For I = 0, 1, and 2, Type, Integral, and Integral will be returned,
  2968.  * respectively.
  2969.  */
  2970. CINDEX_LINKAGE enum CXTemplateArgumentKind
  2971. clang_Cursor_getTemplateArgumentKind(CXCursor C, unsigned I);
  2972.  
  2973. /**
  2974.  * Retrieve a CXType representing the type of a TemplateArgument of a
  2975.  *  function decl representing a template specialization.
  2976.  *
  2977.  * If the argument CXCursor does not represent a FunctionDecl, StructDecl,
  2978.  * ClassDecl or ClassTemplatePartialSpecialization whose I'th template argument
  2979.  * has a kind of CXTemplateArgKind_Integral, an invalid type is returned.
  2980.  *
  2981.  * For example, for the following declaration and specialization:
  2982.  *   template <typename T, int kInt, bool kBool>
  2983.  *   void foo() { ... }
  2984.  *
  2985.  *   template <>
  2986.  *   void foo<float, -7, true>();
  2987.  *
  2988.  * If called with I = 0, "float", will be returned.
  2989.  * Invalid types will be returned for I == 1 or 2.
  2990.  */
  2991. CINDEX_LINKAGE CXType clang_Cursor_getTemplateArgumentType(CXCursor C,
  2992.                                                            unsigned I);
  2993.  
  2994. /**
  2995.  * Retrieve the value of an Integral TemplateArgument (of a function
  2996.  *  decl representing a template specialization) as a signed long long.
  2997.  *
  2998.  * It is undefined to call this function on a CXCursor that does not represent a
  2999.  * FunctionDecl, StructDecl, ClassDecl or ClassTemplatePartialSpecialization
  3000.  * whose I'th template argument is not an integral value.
  3001.  *
  3002.  * For example, for the following declaration and specialization:
  3003.  *   template <typename T, int kInt, bool kBool>
  3004.  *   void foo() { ... }
  3005.  *
  3006.  *   template <>
  3007.  *   void foo<float, -7, true>();
  3008.  *
  3009.  * If called with I = 1 or 2, -7 or true will be returned, respectively.
  3010.  * For I == 0, this function's behavior is undefined.
  3011.  */
  3012. CINDEX_LINKAGE long long clang_Cursor_getTemplateArgumentValue(CXCursor C,
  3013.                                                                unsigned I);
  3014.  
  3015. /**
  3016.  * Retrieve the value of an Integral TemplateArgument (of a function
  3017.  *  decl representing a template specialization) as an unsigned long long.
  3018.  *
  3019.  * It is undefined to call this function on a CXCursor that does not represent a
  3020.  * FunctionDecl, StructDecl, ClassDecl or ClassTemplatePartialSpecialization or
  3021.  * whose I'th template argument is not an integral value.
  3022.  *
  3023.  * For example, for the following declaration and specialization:
  3024.  *   template <typename T, int kInt, bool kBool>
  3025.  *   void foo() { ... }
  3026.  *
  3027.  *   template <>
  3028.  *   void foo<float, 2147483649, true>();
  3029.  *
  3030.  * If called with I = 1 or 2, 2147483649 or true will be returned, respectively.
  3031.  * For I == 0, this function's behavior is undefined.
  3032.  */
  3033. CINDEX_LINKAGE unsigned long long
  3034. clang_Cursor_getTemplateArgumentUnsignedValue(CXCursor C, unsigned I);
  3035.  
  3036. /**
  3037.  * Determine whether two CXTypes represent the same type.
  3038.  *
  3039.  * \returns non-zero if the CXTypes represent the same type and
  3040.  *          zero otherwise.
  3041.  */
  3042. CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B);
  3043.  
  3044. /**
  3045.  * Return the canonical type for a CXType.
  3046.  *
  3047.  * Clang's type system explicitly models typedefs and all the ways
  3048.  * a specific type can be represented.  The canonical type is the underlying
  3049.  * type with all the "sugar" removed.  For example, if 'T' is a typedef
  3050.  * for 'int', the canonical type for 'T' would be 'int'.
  3051.  */
  3052. CINDEX_LINKAGE CXType clang_getCanonicalType(CXType T);
  3053.  
  3054. /**
  3055.  * Determine whether a CXType has the "const" qualifier set,
  3056.  * without looking through typedefs that may have added "const" at a
  3057.  * different level.
  3058.  */
  3059. CINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T);
  3060.  
  3061. /**
  3062.  * Determine whether a  CXCursor that is a macro, is
  3063.  * function like.
  3064.  */
  3065. CINDEX_LINKAGE unsigned clang_Cursor_isMacroFunctionLike(CXCursor C);
  3066.  
  3067. /**
  3068.  * Determine whether a  CXCursor that is a macro, is a
  3069.  * builtin one.
  3070.  */
  3071. CINDEX_LINKAGE unsigned clang_Cursor_isMacroBuiltin(CXCursor C);
  3072.  
  3073. /**
  3074.  * Determine whether a  CXCursor that is a function declaration, is an
  3075.  * inline declaration.
  3076.  */
  3077. CINDEX_LINKAGE unsigned clang_Cursor_isFunctionInlined(CXCursor C);
  3078.  
  3079. /**
  3080.  * Determine whether a CXType has the "volatile" qualifier set,
  3081.  * without looking through typedefs that may have added "volatile" at
  3082.  * a different level.
  3083.  */
  3084. CINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T);
  3085.  
  3086. /**
  3087.  * Determine whether a CXType has the "restrict" qualifier set,
  3088.  * without looking through typedefs that may have added "restrict" at a
  3089.  * different level.
  3090.  */
  3091. CINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T);
  3092.  
  3093. /**
  3094.  * Returns the address space of the given type.
  3095.  */
  3096. CINDEX_LINKAGE unsigned clang_getAddressSpace(CXType T);
  3097.  
  3098. /**
  3099.  * Returns the typedef name of the given type.
  3100.  */
  3101. CINDEX_LINKAGE CXString clang_getTypedefName(CXType CT);
  3102.  
  3103. /**
  3104.  * For pointer types, returns the type of the pointee.
  3105.  */
  3106. CINDEX_LINKAGE CXType clang_getPointeeType(CXType T);
  3107.  
  3108. /**
  3109.  * Retrieve the unqualified variant of the given type, removing as
  3110.  * little sugar as possible.
  3111.  *
  3112.  * For example, given the following series of typedefs:
  3113.  *
  3114.  * \code
  3115.  * typedef int Integer;
  3116.  * typedef const Integer CInteger;
  3117.  * typedef CInteger DifferenceType;
  3118.  * \endcode
  3119.  *
  3120.  * Executing \c clang_getUnqualifiedType() on a \c CXType that
  3121.  * represents \c DifferenceType, will desugar to a type representing
  3122.  * \c Integer, that has no qualifiers.
  3123.  *
  3124.  * And, executing \c clang_getUnqualifiedType() on the type of the
  3125.  * first argument of the following function declaration:
  3126.  *
  3127.  * \code
  3128.  * void foo(const int);
  3129.  * \endcode
  3130.  *
  3131.  * Will return a type representing \c int, removing the \c const
  3132.  * qualifier.
  3133.  *
  3134.  * Sugar over array types is not desugared.
  3135.  *
  3136.  * A type can be checked for qualifiers with \c
  3137.  * clang_isConstQualifiedType(), \c clang_isVolatileQualifiedType()
  3138.  * and \c clang_isRestrictQualifiedType().
  3139.  *
  3140.  * A type that resulted from a call to \c clang_getUnqualifiedType
  3141.  * will return \c false for all of the above calls.
  3142.  */
  3143. CINDEX_LINKAGE CXType clang_getUnqualifiedType(CXType CT);
  3144.  
  3145. /**
  3146.  * For reference types (e.g., "const int&"), returns the type that the
  3147.  * reference refers to (e.g "const int").
  3148.  *
  3149.  * Otherwise, returns the type itself.
  3150.  *
  3151.  * A type that has kind \c CXType_LValueReference or
  3152.  * \c CXType_RValueReference is a reference type.
  3153.  */
  3154. CINDEX_LINKAGE CXType clang_getNonReferenceType(CXType CT);
  3155.  
  3156. /**
  3157.  * Return the cursor for the declaration of the given type.
  3158.  */
  3159. CINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T);
  3160.  
  3161. /**
  3162.  * Returns the Objective-C type encoding for the specified declaration.
  3163.  */
  3164. CINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C);
  3165.  
  3166. /**
  3167.  * Returns the Objective-C type encoding for the specified CXType.
  3168.  */
  3169. CINDEX_LINKAGE CXString clang_Type_getObjCEncoding(CXType type);
  3170.  
  3171. /**
  3172.  * Retrieve the spelling of a given CXTypeKind.
  3173.  */
  3174. CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K);
  3175.  
  3176. /**
  3177.  * Retrieve the calling convention associated with a function type.
  3178.  *
  3179.  * If a non-function type is passed in, CXCallingConv_Invalid is returned.
  3180.  */
  3181. CINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T);
  3182.  
  3183. /**
  3184.  * Retrieve the return type associated with a function type.
  3185.  *
  3186.  * If a non-function type is passed in, an invalid type is returned.
  3187.  */
  3188. CINDEX_LINKAGE CXType clang_getResultType(CXType T);
  3189.  
  3190. /**
  3191.  * Retrieve the exception specification type associated with a function type.
  3192.  * This is a value of type CXCursor_ExceptionSpecificationKind.
  3193.  *
  3194.  * If a non-function type is passed in, an error code of -1 is returned.
  3195.  */
  3196. CINDEX_LINKAGE int clang_getExceptionSpecificationType(CXType T);
  3197.  
  3198. /**
  3199.  * Retrieve the number of non-variadic parameters associated with a
  3200.  * function type.
  3201.  *
  3202.  * If a non-function type is passed in, -1 is returned.
  3203.  */
  3204. CINDEX_LINKAGE int clang_getNumArgTypes(CXType T);
  3205.  
  3206. /**
  3207.  * Retrieve the type of a parameter of a function type.
  3208.  *
  3209.  * If a non-function type is passed in or the function does not have enough
  3210.  * parameters, an invalid type is returned.
  3211.  */
  3212. CINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i);
  3213.  
  3214. /**
  3215.  * Retrieves the base type of the ObjCObjectType.
  3216.  *
  3217.  * If the type is not an ObjC object, an invalid type is returned.
  3218.  */
  3219. CINDEX_LINKAGE CXType clang_Type_getObjCObjectBaseType(CXType T);
  3220.  
  3221. /**
  3222.  * Retrieve the number of protocol references associated with an ObjC object/id.
  3223.  *
  3224.  * If the type is not an ObjC object, 0 is returned.
  3225.  */
  3226. CINDEX_LINKAGE unsigned clang_Type_getNumObjCProtocolRefs(CXType T);
  3227.  
  3228. /**
  3229.  * Retrieve the decl for a protocol reference for an ObjC object/id.
  3230.  *
  3231.  * If the type is not an ObjC object or there are not enough protocol
  3232.  * references, an invalid cursor is returned.
  3233.  */
  3234. CINDEX_LINKAGE CXCursor clang_Type_getObjCProtocolDecl(CXType T, unsigned i);
  3235.  
  3236. /**
  3237.  * Retrieve the number of type arguments associated with an ObjC object.
  3238.  *
  3239.  * If the type is not an ObjC object, 0 is returned.
  3240.  */
  3241. CINDEX_LINKAGE unsigned clang_Type_getNumObjCTypeArgs(CXType T);
  3242.  
  3243. /**
  3244.  * Retrieve a type argument associated with an ObjC object.
  3245.  *
  3246.  * If the type is not an ObjC or the index is not valid,
  3247.  * an invalid type is returned.
  3248.  */
  3249. CINDEX_LINKAGE CXType clang_Type_getObjCTypeArg(CXType T, unsigned i);
  3250.  
  3251. /**
  3252.  * Return 1 if the CXType is a variadic function type, and 0 otherwise.
  3253.  */
  3254. CINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T);
  3255.  
  3256. /**
  3257.  * Retrieve the return type associated with a given cursor.
  3258.  *
  3259.  * This only returns a valid type if the cursor refers to a function or method.
  3260.  */
  3261. CINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C);
  3262.  
  3263. /**
  3264.  * Retrieve the exception specification type associated with a given cursor.
  3265.  * This is a value of type CXCursor_ExceptionSpecificationKind.
  3266.  *
  3267.  * This only returns a valid result if the cursor refers to a function or
  3268.  * method.
  3269.  */
  3270. CINDEX_LINKAGE int clang_getCursorExceptionSpecificationType(CXCursor C);
  3271.  
  3272. /**
  3273.  * Return 1 if the CXType is a POD (plain old data) type, and 0
  3274.  *  otherwise.
  3275.  */
  3276. CINDEX_LINKAGE unsigned clang_isPODType(CXType T);
  3277.  
  3278. /**
  3279.  * Return the element type of an array, complex, or vector type.
  3280.  *
  3281.  * If a type is passed in that is not an array, complex, or vector type,
  3282.  * an invalid type is returned.
  3283.  */
  3284. CINDEX_LINKAGE CXType clang_getElementType(CXType T);
  3285.  
  3286. /**
  3287.  * Return the number of elements of an array or vector type.
  3288.  *
  3289.  * If a type is passed in that is not an array or vector type,
  3290.  * -1 is returned.
  3291.  */
  3292. CINDEX_LINKAGE long long clang_getNumElements(CXType T);
  3293.  
  3294. /**
  3295.  * Return the element type of an array type.
  3296.  *
  3297.  * If a non-array type is passed in, an invalid type is returned.
  3298.  */
  3299. CINDEX_LINKAGE CXType clang_getArrayElementType(CXType T);
  3300.  
  3301. /**
  3302.  * Return the array size of a constant array.
  3303.  *
  3304.  * If a non-array type is passed in, -1 is returned.
  3305.  */
  3306. CINDEX_LINKAGE long long clang_getArraySize(CXType T);
  3307.  
  3308. /**
  3309.  * Retrieve the type named by the qualified-id.
  3310.  *
  3311.  * If a non-elaborated type is passed in, an invalid type is returned.
  3312.  */
  3313. CINDEX_LINKAGE CXType clang_Type_getNamedType(CXType T);
  3314.  
  3315. /**
  3316.  * Determine if a typedef is 'transparent' tag.
  3317.  *
  3318.  * A typedef is considered 'transparent' if it shares a name and spelling
  3319.  * location with its underlying tag type, as is the case with the NS_ENUM macro.
  3320.  *
  3321.  * \returns non-zero if transparent and zero otherwise.
  3322.  */
  3323. CINDEX_LINKAGE unsigned clang_Type_isTransparentTagTypedef(CXType T);
  3324.  
  3325. enum CXTypeNullabilityKind {
  3326.   /**
  3327.    * Values of this type can never be null.
  3328.    */
  3329.   CXTypeNullability_NonNull = 0,
  3330.   /**
  3331.    * Values of this type can be null.
  3332.    */
  3333.   CXTypeNullability_Nullable = 1,
  3334.   /**
  3335.    * Whether values of this type can be null is (explicitly)
  3336.    * unspecified. This captures a (fairly rare) case where we
  3337.    * can't conclude anything about the nullability of the type even
  3338.    * though it has been considered.
  3339.    */
  3340.   CXTypeNullability_Unspecified = 2,
  3341.   /**
  3342.    * Nullability is not applicable to this type.
  3343.    */
  3344.   CXTypeNullability_Invalid = 3,
  3345.  
  3346.   /**
  3347.    * Generally behaves like Nullable, except when used in a block parameter that
  3348.    * was imported into a swift async method. There, swift will assume that the
  3349.    * parameter can get null even if no error occurred. _Nullable parameters are
  3350.    * assumed to only get null on error.
  3351.    */
  3352.   CXTypeNullability_NullableResult = 4
  3353. };
  3354.  
  3355. /**
  3356.  * Retrieve the nullability kind of a pointer type.
  3357.  */
  3358. CINDEX_LINKAGE enum CXTypeNullabilityKind clang_Type_getNullability(CXType T);
  3359.  
  3360. /**
  3361.  * List the possible error codes for \c clang_Type_getSizeOf,
  3362.  *   \c clang_Type_getAlignOf, \c clang_Type_getOffsetOf and
  3363.  *   \c clang_Cursor_getOffsetOf.
  3364.  *
  3365.  * A value of this enumeration type can be returned if the target type is not
  3366.  * a valid argument to sizeof, alignof or offsetof.
  3367.  */
  3368. enum CXTypeLayoutError {
  3369.   /**
  3370.    * Type is of kind CXType_Invalid.
  3371.    */
  3372.   CXTypeLayoutError_Invalid = -1,
  3373.   /**
  3374.    * The type is an incomplete Type.
  3375.    */
  3376.   CXTypeLayoutError_Incomplete = -2,
  3377.   /**
  3378.    * The type is a dependent Type.
  3379.    */
  3380.   CXTypeLayoutError_Dependent = -3,
  3381.   /**
  3382.    * The type is not a constant size type.
  3383.    */
  3384.   CXTypeLayoutError_NotConstantSize = -4,
  3385.   /**
  3386.    * The Field name is not valid for this record.
  3387.    */
  3388.   CXTypeLayoutError_InvalidFieldName = -5,
  3389.   /**
  3390.    * The type is undeduced.
  3391.    */
  3392.   CXTypeLayoutError_Undeduced = -6
  3393. };
  3394.  
  3395. /**
  3396.  * Return the alignment of a type in bytes as per C++[expr.alignof]
  3397.  *   standard.
  3398.  *
  3399.  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
  3400.  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
  3401.  *   is returned.
  3402.  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
  3403.  *   returned.
  3404.  * If the type declaration is not a constant size type,
  3405.  *   CXTypeLayoutError_NotConstantSize is returned.
  3406.  */
  3407. CINDEX_LINKAGE long long clang_Type_getAlignOf(CXType T);
  3408.  
  3409. /**
  3410.  * Return the class type of an member pointer type.
  3411.  *
  3412.  * If a non-member-pointer type is passed in, an invalid type is returned.
  3413.  */
  3414. CINDEX_LINKAGE CXType clang_Type_getClassType(CXType T);
  3415.  
  3416. /**
  3417.  * Return the size of a type in bytes as per C++[expr.sizeof] standard.
  3418.  *
  3419.  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
  3420.  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
  3421.  *   is returned.
  3422.  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
  3423.  *   returned.
  3424.  */
  3425. CINDEX_LINKAGE long long clang_Type_getSizeOf(CXType T);
  3426.  
  3427. /**
  3428.  * Return the offset of a field named S in a record of type T in bits
  3429.  *   as it would be returned by __offsetof__ as per C++11[18.2p4]
  3430.  *
  3431.  * If the cursor is not a record field declaration, CXTypeLayoutError_Invalid
  3432.  *   is returned.
  3433.  * If the field's type declaration is an incomplete type,
  3434.  *   CXTypeLayoutError_Incomplete is returned.
  3435.  * If the field's type declaration is a dependent type,
  3436.  *   CXTypeLayoutError_Dependent is returned.
  3437.  * If the field's name S is not found,
  3438.  *   CXTypeLayoutError_InvalidFieldName is returned.
  3439.  */
  3440. CINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S);
  3441.  
  3442. /**
  3443.  * Return the type that was modified by this attributed type.
  3444.  *
  3445.  * If the type is not an attributed type, an invalid type is returned.
  3446.  */
  3447. CINDEX_LINKAGE CXType clang_Type_getModifiedType(CXType T);
  3448.  
  3449. /**
  3450.  * Gets the type contained by this atomic type.
  3451.  *
  3452.  * If a non-atomic type is passed in, an invalid type is returned.
  3453.  */
  3454. CINDEX_LINKAGE CXType clang_Type_getValueType(CXType CT);
  3455.  
  3456. /**
  3457.  * Return the offset of the field represented by the Cursor.
  3458.  *
  3459.  * If the cursor is not a field declaration, -1 is returned.
  3460.  * If the cursor semantic parent is not a record field declaration,
  3461.  *   CXTypeLayoutError_Invalid is returned.
  3462.  * If the field's type declaration is an incomplete type,
  3463.  *   CXTypeLayoutError_Incomplete is returned.
  3464.  * If the field's type declaration is a dependent type,
  3465.  *   CXTypeLayoutError_Dependent is returned.
  3466.  * If the field's name S is not found,
  3467.  *   CXTypeLayoutError_InvalidFieldName is returned.
  3468.  */
  3469. CINDEX_LINKAGE long long clang_Cursor_getOffsetOfField(CXCursor C);
  3470.  
  3471. /**
  3472.  * Determine whether the given cursor represents an anonymous
  3473.  * tag or namespace
  3474.  */
  3475. CINDEX_LINKAGE unsigned clang_Cursor_isAnonymous(CXCursor C);
  3476.  
  3477. /**
  3478.  * Determine whether the given cursor represents an anonymous record
  3479.  * declaration.
  3480.  */
  3481. CINDEX_LINKAGE unsigned clang_Cursor_isAnonymousRecordDecl(CXCursor C);
  3482.  
  3483. /**
  3484.  * Determine whether the given cursor represents an inline namespace
  3485.  * declaration.
  3486.  */
  3487. CINDEX_LINKAGE unsigned clang_Cursor_isInlineNamespace(CXCursor C);
  3488.  
  3489. enum CXRefQualifierKind {
  3490.   /** No ref-qualifier was provided. */
  3491.   CXRefQualifier_None = 0,
  3492.   /** An lvalue ref-qualifier was provided (\c &). */
  3493.   CXRefQualifier_LValue,
  3494.   /** An rvalue ref-qualifier was provided (\c &&). */
  3495.   CXRefQualifier_RValue
  3496. };
  3497.  
  3498. /**
  3499.  * Returns the number of template arguments for given template
  3500.  * specialization, or -1 if type \c T is not a template specialization.
  3501.  */
  3502. CINDEX_LINKAGE int clang_Type_getNumTemplateArguments(CXType T);
  3503.  
  3504. /**
  3505.  * Returns the type template argument of a template class specialization
  3506.  * at given index.
  3507.  *
  3508.  * This function only returns template type arguments and does not handle
  3509.  * template template arguments or variadic packs.
  3510.  */
  3511. CINDEX_LINKAGE CXType clang_Type_getTemplateArgumentAsType(CXType T,
  3512.                                                            unsigned i);
  3513.  
  3514. /**
  3515.  * Retrieve the ref-qualifier kind of a function or method.
  3516.  *
  3517.  * The ref-qualifier is returned for C++ functions or methods. For other types
  3518.  * or non-C++ declarations, CXRefQualifier_None is returned.
  3519.  */
  3520. CINDEX_LINKAGE enum CXRefQualifierKind clang_Type_getCXXRefQualifier(CXType T);
  3521.  
  3522. /**
  3523.  * Returns non-zero if the cursor specifies a Record member that is a
  3524.  *   bitfield.
  3525.  */
  3526. CINDEX_LINKAGE unsigned clang_Cursor_isBitField(CXCursor C);
  3527.  
  3528. /**
  3529.  * Returns 1 if the base class specified by the cursor with kind
  3530.  *   CX_CXXBaseSpecifier is virtual.
  3531.  */
  3532. CINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor);
  3533.  
  3534. /**
  3535.  * Represents the C++ access control level to a base class for a
  3536.  * cursor with kind CX_CXXBaseSpecifier.
  3537.  */
  3538. enum CX_CXXAccessSpecifier {
  3539.   CX_CXXInvalidAccessSpecifier,
  3540.   CX_CXXPublic,
  3541.   CX_CXXProtected,
  3542.   CX_CXXPrivate
  3543. };
  3544.  
  3545. /**
  3546.  * Returns the access control level for the referenced object.
  3547.  *
  3548.  * If the cursor refers to a C++ declaration, its access control level within
  3549.  * its parent scope is returned. Otherwise, if the cursor refers to a base
  3550.  * specifier or access specifier, the specifier itself is returned.
  3551.  */
  3552. CINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor);
  3553.  
  3554. /**
  3555.  * Represents the storage classes as declared in the source. CX_SC_Invalid
  3556.  * was added for the case that the passed cursor in not a declaration.
  3557.  */
  3558. enum CX_StorageClass {
  3559.   CX_SC_Invalid,
  3560.   CX_SC_None,
  3561.   CX_SC_Extern,
  3562.   CX_SC_Static,
  3563.   CX_SC_PrivateExtern,
  3564.   CX_SC_OpenCLWorkGroupLocal,
  3565.   CX_SC_Auto,
  3566.   CX_SC_Register
  3567. };
  3568.  
  3569. /**
  3570.  * Returns the storage class for a function or variable declaration.
  3571.  *
  3572.  * If the passed in Cursor is not a function or variable declaration,
  3573.  * CX_SC_Invalid is returned else the storage class.
  3574.  */
  3575. CINDEX_LINKAGE enum CX_StorageClass clang_Cursor_getStorageClass(CXCursor);
  3576.  
  3577. /**
  3578.  * Determine the number of overloaded declarations referenced by a
  3579.  * \c CXCursor_OverloadedDeclRef cursor.
  3580.  *
  3581.  * \param cursor The cursor whose overloaded declarations are being queried.
  3582.  *
  3583.  * \returns The number of overloaded declarations referenced by \c cursor. If it
  3584.  * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0.
  3585.  */
  3586. CINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor);
  3587.  
  3588. /**
  3589.  * Retrieve a cursor for one of the overloaded declarations referenced
  3590.  * by a \c CXCursor_OverloadedDeclRef cursor.
  3591.  *
  3592.  * \param cursor The cursor whose overloaded declarations are being queried.
  3593.  *
  3594.  * \param index The zero-based index into the set of overloaded declarations in
  3595.  * the cursor.
  3596.  *
  3597.  * \returns A cursor representing the declaration referenced by the given
  3598.  * \c cursor at the specified \c index. If the cursor does not have an
  3599.  * associated set of overloaded declarations, or if the index is out of bounds,
  3600.  * returns \c clang_getNullCursor();
  3601.  */
  3602. CINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor,
  3603.                                                 unsigned index);
  3604.  
  3605. /**
  3606.  * @}
  3607.  */
  3608.  
  3609. /**
  3610.  * \defgroup CINDEX_ATTRIBUTES Information for attributes
  3611.  *
  3612.  * @{
  3613.  */
  3614.  
  3615. /**
  3616.  * For cursors representing an iboutletcollection attribute,
  3617.  *  this function returns the collection element type.
  3618.  *
  3619.  */
  3620. CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor);
  3621.  
  3622. /**
  3623.  * @}
  3624.  */
  3625.  
  3626. /**
  3627.  * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
  3628.  *
  3629.  * These routines provide the ability to traverse the abstract syntax tree
  3630.  * using cursors.
  3631.  *
  3632.  * @{
  3633.  */
  3634.  
  3635. /**
  3636.  * Describes how the traversal of the children of a particular
  3637.  * cursor should proceed after visiting a particular child cursor.
  3638.  *
  3639.  * A value of this enumeration type should be returned by each
  3640.  * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
  3641.  */
  3642. enum CXChildVisitResult {
  3643.   /**
  3644.    * Terminates the cursor traversal.
  3645.    */
  3646.   CXChildVisit_Break,
  3647.   /**
  3648.    * Continues the cursor traversal with the next sibling of
  3649.    * the cursor just visited, without visiting its children.
  3650.    */
  3651.   CXChildVisit_Continue,
  3652.   /**
  3653.    * Recursively traverse the children of this cursor, using
  3654.    * the same visitor and client data.
  3655.    */
  3656.   CXChildVisit_Recurse
  3657. };
  3658.  
  3659. /**
  3660.  * Visitor invoked for each cursor found by a traversal.
  3661.  *
  3662.  * This visitor function will be invoked for each cursor found by
  3663.  * clang_visitCursorChildren(). Its first argument is the cursor being
  3664.  * visited, its second argument is the parent visitor for that cursor,
  3665.  * and its third argument is the client data provided to
  3666.  * clang_visitCursorChildren().
  3667.  *
  3668.  * The visitor should return one of the \c CXChildVisitResult values
  3669.  * to direct clang_visitCursorChildren().
  3670.  */
  3671. typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor,
  3672.                                                    CXCursor parent,
  3673.                                                    CXClientData client_data);
  3674.  
  3675. /**
  3676.  * Visit the children of a particular cursor.
  3677.  *
  3678.  * This function visits all the direct children of the given cursor,
  3679.  * invoking the given \p visitor function with the cursors of each
  3680.  * visited child. The traversal may be recursive, if the visitor returns
  3681.  * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
  3682.  * the visitor returns \c CXChildVisit_Break.
  3683.  *
  3684.  * \param parent the cursor whose child may be visited. All kinds of
  3685.  * cursors can be visited, including invalid cursors (which, by
  3686.  * definition, have no children).
  3687.  *
  3688.  * \param visitor the visitor function that will be invoked for each
  3689.  * child of \p parent.
  3690.  *
  3691.  * \param client_data pointer data supplied by the client, which will
  3692.  * be passed to the visitor each time it is invoked.
  3693.  *
  3694.  * \returns a non-zero value if the traversal was terminated
  3695.  * prematurely by the visitor returning \c CXChildVisit_Break.
  3696.  */
  3697. CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent,
  3698.                                             CXCursorVisitor visitor,
  3699.                                             CXClientData client_data);
  3700. #ifdef __has_feature
  3701. #if __has_feature(blocks)
  3702. /**
  3703.  * Visitor invoked for each cursor found by a traversal.
  3704.  *
  3705.  * This visitor block will be invoked for each cursor found by
  3706.  * clang_visitChildrenWithBlock(). Its first argument is the cursor being
  3707.  * visited, its second argument is the parent visitor for that cursor.
  3708.  *
  3709.  * The visitor should return one of the \c CXChildVisitResult values
  3710.  * to direct clang_visitChildrenWithBlock().
  3711.  */
  3712. typedef enum CXChildVisitResult (^CXCursorVisitorBlock)(CXCursor cursor,
  3713.                                                         CXCursor parent);
  3714.  
  3715. /**
  3716.  * Visits the children of a cursor using the specified block.  Behaves
  3717.  * identically to clang_visitChildren() in all other respects.
  3718.  */
  3719. CINDEX_LINKAGE unsigned
  3720. clang_visitChildrenWithBlock(CXCursor parent, CXCursorVisitorBlock block);
  3721. #endif
  3722. #endif
  3723.  
  3724. /**
  3725.  * @}
  3726.  */
  3727.  
  3728. /**
  3729.  * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
  3730.  *
  3731.  * These routines provide the ability to determine references within and
  3732.  * across translation units, by providing the names of the entities referenced
  3733.  * by cursors, follow reference cursors to the declarations they reference,
  3734.  * and associate declarations with their definitions.
  3735.  *
  3736.  * @{
  3737.  */
  3738.  
  3739. /**
  3740.  * Retrieve a Unified Symbol Resolution (USR) for the entity referenced
  3741.  * by the given cursor.
  3742.  *
  3743.  * A Unified Symbol Resolution (USR) is a string that identifies a particular
  3744.  * entity (function, class, variable, etc.) within a program. USRs can be
  3745.  * compared across translation units to determine, e.g., when references in
  3746.  * one translation refer to an entity defined in another translation unit.
  3747.  */
  3748. CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor);
  3749.  
  3750. /**
  3751.  * Construct a USR for a specified Objective-C class.
  3752.  */
  3753. CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name);
  3754.  
  3755. /**
  3756.  * Construct a USR for a specified Objective-C category.
  3757.  */
  3758. CINDEX_LINKAGE CXString clang_constructUSR_ObjCCategory(
  3759.     const char *class_name, const char *category_name);
  3760.  
  3761. /**
  3762.  * Construct a USR for a specified Objective-C protocol.
  3763.  */
  3764. CINDEX_LINKAGE CXString
  3765. clang_constructUSR_ObjCProtocol(const char *protocol_name);
  3766.  
  3767. /**
  3768.  * Construct a USR for a specified Objective-C instance variable and
  3769.  *   the USR for its containing class.
  3770.  */
  3771. CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name,
  3772.                                                     CXString classUSR);
  3773.  
  3774. /**
  3775.  * Construct a USR for a specified Objective-C method and
  3776.  *   the USR for its containing class.
  3777.  */
  3778. CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name,
  3779.                                                       unsigned isInstanceMethod,
  3780.                                                       CXString classUSR);
  3781.  
  3782. /**
  3783.  * Construct a USR for a specified Objective-C property and the USR
  3784.  *  for its containing class.
  3785.  */
  3786. CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property,
  3787.                                                         CXString classUSR);
  3788.  
  3789. /**
  3790.  * Retrieve a name for the entity referenced by this cursor.
  3791.  */
  3792. CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
  3793.  
  3794. /**
  3795.  * Retrieve a range for a piece that forms the cursors spelling name.
  3796.  * Most of the times there is only one range for the complete spelling but for
  3797.  * Objective-C methods and Objective-C message expressions, there are multiple
  3798.  * pieces for each selector identifier.
  3799.  *
  3800.  * \param pieceIndex the index of the spelling name piece. If this is greater
  3801.  * than the actual number of pieces, it will return a NULL (invalid) range.
  3802.  *
  3803.  * \param options Reserved.
  3804.  */
  3805. CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(
  3806.     CXCursor, unsigned pieceIndex, unsigned options);
  3807.  
  3808. /**
  3809.  * Opaque pointer representing a policy that controls pretty printing
  3810.  * for \c clang_getCursorPrettyPrinted.
  3811.  */
  3812. typedef void *CXPrintingPolicy;
  3813.  
  3814. /**
  3815.  * Properties for the printing policy.
  3816.  *
  3817.  * See \c clang::PrintingPolicy for more information.
  3818.  */
  3819. enum CXPrintingPolicyProperty {
  3820.   CXPrintingPolicy_Indentation,
  3821.   CXPrintingPolicy_SuppressSpecifiers,
  3822.   CXPrintingPolicy_SuppressTagKeyword,
  3823.   CXPrintingPolicy_IncludeTagDefinition,
  3824.   CXPrintingPolicy_SuppressScope,
  3825.   CXPrintingPolicy_SuppressUnwrittenScope,
  3826.   CXPrintingPolicy_SuppressInitializers,
  3827.   CXPrintingPolicy_ConstantArraySizeAsWritten,
  3828.   CXPrintingPolicy_AnonymousTagLocations,
  3829.   CXPrintingPolicy_SuppressStrongLifetime,
  3830.   CXPrintingPolicy_SuppressLifetimeQualifiers,
  3831.   CXPrintingPolicy_SuppressTemplateArgsInCXXConstructors,
  3832.   CXPrintingPolicy_Bool,
  3833.   CXPrintingPolicy_Restrict,
  3834.   CXPrintingPolicy_Alignof,
  3835.   CXPrintingPolicy_UnderscoreAlignof,
  3836.   CXPrintingPolicy_UseVoidForZeroParams,
  3837.   CXPrintingPolicy_TerseOutput,
  3838.   CXPrintingPolicy_PolishForDeclaration,
  3839.   CXPrintingPolicy_Half,
  3840.   CXPrintingPolicy_MSWChar,
  3841.   CXPrintingPolicy_IncludeNewlines,
  3842.   CXPrintingPolicy_MSVCFormatting,
  3843.   CXPrintingPolicy_ConstantsAsWritten,
  3844.   CXPrintingPolicy_SuppressImplicitBase,
  3845.   CXPrintingPolicy_FullyQualifiedName,
  3846.  
  3847.   CXPrintingPolicy_LastProperty = CXPrintingPolicy_FullyQualifiedName
  3848. };
  3849.  
  3850. /**
  3851.  * Get a property value for the given printing policy.
  3852.  */
  3853. CINDEX_LINKAGE unsigned
  3854. clang_PrintingPolicy_getProperty(CXPrintingPolicy Policy,
  3855.                                  enum CXPrintingPolicyProperty Property);
  3856.  
  3857. /**
  3858.  * Set a property value for the given printing policy.
  3859.  */
  3860. CINDEX_LINKAGE void
  3861. clang_PrintingPolicy_setProperty(CXPrintingPolicy Policy,
  3862.                                  enum CXPrintingPolicyProperty Property,
  3863.                                  unsigned Value);
  3864.  
  3865. /**
  3866.  * Retrieve the default policy for the cursor.
  3867.  *
  3868.  * The policy should be released after use with \c
  3869.  * clang_PrintingPolicy_dispose.
  3870.  */
  3871. CINDEX_LINKAGE CXPrintingPolicy clang_getCursorPrintingPolicy(CXCursor);
  3872.  
  3873. /**
  3874.  * Release a printing policy.
  3875.  */
  3876. CINDEX_LINKAGE void clang_PrintingPolicy_dispose(CXPrintingPolicy Policy);
  3877.  
  3878. /**
  3879.  * Pretty print declarations.
  3880.  *
  3881.  * \param Cursor The cursor representing a declaration.
  3882.  *
  3883.  * \param Policy The policy to control the entities being printed. If
  3884.  * NULL, a default policy is used.
  3885.  *
  3886.  * \returns The pretty printed declaration or the empty string for
  3887.  * other cursors.
  3888.  */
  3889. CINDEX_LINKAGE CXString clang_getCursorPrettyPrinted(CXCursor Cursor,
  3890.                                                      CXPrintingPolicy Policy);
  3891.  
  3892. /**
  3893.  * Retrieve the display name for the entity referenced by this cursor.
  3894.  *
  3895.  * The display name contains extra information that helps identify the cursor,
  3896.  * such as the parameters of a function or template or the arguments of a
  3897.  * class template specialization.
  3898.  */
  3899. CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor);
  3900.  
  3901. /** For a cursor that is a reference, retrieve a cursor representing the
  3902.  * entity that it references.
  3903.  *
  3904.  * Reference cursors refer to other entities in the AST. For example, an
  3905.  * Objective-C superclass reference cursor refers to an Objective-C class.
  3906.  * This function produces the cursor for the Objective-C class from the
  3907.  * cursor for the superclass reference. If the input cursor is a declaration or
  3908.  * definition, it returns that declaration or definition unchanged.
  3909.  * Otherwise, returns the NULL cursor.
  3910.  */
  3911. CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor);
  3912.  
  3913. /**
  3914.  *  For a cursor that is either a reference to or a declaration
  3915.  *  of some entity, retrieve a cursor that describes the definition of
  3916.  *  that entity.
  3917.  *
  3918.  *  Some entities can be declared multiple times within a translation
  3919.  *  unit, but only one of those declarations can also be a
  3920.  *  definition. For example, given:
  3921.  *
  3922.  *  \code
  3923.  *  int f(int, int);
  3924.  *  int g(int x, int y) { return f(x, y); }
  3925.  *  int f(int a, int b) { return a + b; }
  3926.  *  int f(int, int);
  3927.  *  \endcode
  3928.  *
  3929.  *  there are three declarations of the function "f", but only the
  3930.  *  second one is a definition. The clang_getCursorDefinition()
  3931.  *  function will take any cursor pointing to a declaration of "f"
  3932.  *  (the first or fourth lines of the example) or a cursor referenced
  3933.  *  that uses "f" (the call to "f' inside "g") and will return a
  3934.  *  declaration cursor pointing to the definition (the second "f"
  3935.  *  declaration).
  3936.  *
  3937.  *  If given a cursor for which there is no corresponding definition,
  3938.  *  e.g., because there is no definition of that entity within this
  3939.  *  translation unit, returns a NULL cursor.
  3940.  */
  3941. CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor);
  3942.  
  3943. /**
  3944.  * Determine whether the declaration pointed to by this cursor
  3945.  * is also a definition of that entity.
  3946.  */
  3947. CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor);
  3948.  
  3949. /**
  3950.  * Retrieve the canonical cursor corresponding to the given cursor.
  3951.  *
  3952.  * In the C family of languages, many kinds of entities can be declared several
  3953.  * times within a single translation unit. For example, a structure type can
  3954.  * be forward-declared (possibly multiple times) and later defined:
  3955.  *
  3956.  * \code
  3957.  * struct X;
  3958.  * struct X;
  3959.  * struct X {
  3960.  *   int member;
  3961.  * };
  3962.  * \endcode
  3963.  *
  3964.  * The declarations and the definition of \c X are represented by three
  3965.  * different cursors, all of which are declarations of the same underlying
  3966.  * entity. One of these cursor is considered the "canonical" cursor, which
  3967.  * is effectively the representative for the underlying entity. One can
  3968.  * determine if two cursors are declarations of the same underlying entity by
  3969.  * comparing their canonical cursors.
  3970.  *
  3971.  * \returns The canonical cursor for the entity referred to by the given cursor.
  3972.  */
  3973. CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor);
  3974.  
  3975. /**
  3976.  * If the cursor points to a selector identifier in an Objective-C
  3977.  * method or message expression, this returns the selector index.
  3978.  *
  3979.  * After getting a cursor with #clang_getCursor, this can be called to
  3980.  * determine if the location points to a selector identifier.
  3981.  *
  3982.  * \returns The selector index if the cursor is an Objective-C method or message
  3983.  * expression and the cursor is pointing to a selector identifier, or -1
  3984.  * otherwise.
  3985.  */
  3986. CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor);
  3987.  
  3988. /**
  3989.  * Given a cursor pointing to a C++ method call or an Objective-C
  3990.  * message, returns non-zero if the method/message is "dynamic", meaning:
  3991.  *
  3992.  * For a C++ method: the call is virtual.
  3993.  * For an Objective-C message: the receiver is an object instance, not 'super'
  3994.  * or a specific class.
  3995.  *
  3996.  * If the method/message is "static" or the cursor does not point to a
  3997.  * method/message, it will return zero.
  3998.  */
  3999. CINDEX_LINKAGE int clang_Cursor_isDynamicCall(CXCursor C);
  4000.  
  4001. /**
  4002.  * Given a cursor pointing to an Objective-C message or property
  4003.  * reference, or C++ method call, returns the CXType of the receiver.
  4004.  */
  4005. CINDEX_LINKAGE CXType clang_Cursor_getReceiverType(CXCursor C);
  4006.  
  4007. /**
  4008.  * Property attributes for a \c CXCursor_ObjCPropertyDecl.
  4009.  */
  4010. typedef enum {
  4011.   CXObjCPropertyAttr_noattr = 0x00,
  4012.   CXObjCPropertyAttr_readonly = 0x01,
  4013.   CXObjCPropertyAttr_getter = 0x02,
  4014.   CXObjCPropertyAttr_assign = 0x04,
  4015.   CXObjCPropertyAttr_readwrite = 0x08,
  4016.   CXObjCPropertyAttr_retain = 0x10,
  4017.   CXObjCPropertyAttr_copy = 0x20,
  4018.   CXObjCPropertyAttr_nonatomic = 0x40,
  4019.   CXObjCPropertyAttr_setter = 0x80,
  4020.   CXObjCPropertyAttr_atomic = 0x100,
  4021.   CXObjCPropertyAttr_weak = 0x200,
  4022.   CXObjCPropertyAttr_strong = 0x400,
  4023.   CXObjCPropertyAttr_unsafe_unretained = 0x800,
  4024.   CXObjCPropertyAttr_class = 0x1000
  4025. } CXObjCPropertyAttrKind;
  4026.  
  4027. /**
  4028.  * Given a cursor that represents a property declaration, return the
  4029.  * associated property attributes. The bits are formed from
  4030.  * \c CXObjCPropertyAttrKind.
  4031.  *
  4032.  * \param reserved Reserved for future use, pass 0.
  4033.  */
  4034. CINDEX_LINKAGE unsigned
  4035. clang_Cursor_getObjCPropertyAttributes(CXCursor C, unsigned reserved);
  4036.  
  4037. /**
  4038.  * Given a cursor that represents a property declaration, return the
  4039.  * name of the method that implements the getter.
  4040.  */
  4041. CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertyGetterName(CXCursor C);
  4042.  
  4043. /**
  4044.  * Given a cursor that represents a property declaration, return the
  4045.  * name of the method that implements the setter, if any.
  4046.  */
  4047. CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertySetterName(CXCursor C);
  4048.  
  4049. /**
  4050.  * 'Qualifiers' written next to the return and parameter types in
  4051.  * Objective-C method declarations.
  4052.  */
  4053. typedef enum {
  4054.   CXObjCDeclQualifier_None = 0x0,
  4055.   CXObjCDeclQualifier_In = 0x1,
  4056.   CXObjCDeclQualifier_Inout = 0x2,
  4057.   CXObjCDeclQualifier_Out = 0x4,
  4058.   CXObjCDeclQualifier_Bycopy = 0x8,
  4059.   CXObjCDeclQualifier_Byref = 0x10,
  4060.   CXObjCDeclQualifier_Oneway = 0x20
  4061. } CXObjCDeclQualifierKind;
  4062.  
  4063. /**
  4064.  * Given a cursor that represents an Objective-C method or parameter
  4065.  * declaration, return the associated Objective-C qualifiers for the return
  4066.  * type or the parameter respectively. The bits are formed from
  4067.  * CXObjCDeclQualifierKind.
  4068.  */
  4069. CINDEX_LINKAGE unsigned clang_Cursor_getObjCDeclQualifiers(CXCursor C);
  4070.  
  4071. /**
  4072.  * Given a cursor that represents an Objective-C method or property
  4073.  * declaration, return non-zero if the declaration was affected by "\@optional".
  4074.  * Returns zero if the cursor is not such a declaration or it is "\@required".
  4075.  */
  4076. CINDEX_LINKAGE unsigned clang_Cursor_isObjCOptional(CXCursor C);
  4077.  
  4078. /**
  4079.  * Returns non-zero if the given cursor is a variadic function or method.
  4080.  */
  4081. CINDEX_LINKAGE unsigned clang_Cursor_isVariadic(CXCursor C);
  4082.  
  4083. /**
  4084.  * Returns non-zero if the given cursor points to a symbol marked with
  4085.  * external_source_symbol attribute.
  4086.  *
  4087.  * \param language If non-NULL, and the attribute is present, will be set to
  4088.  * the 'language' string from the attribute.
  4089.  *
  4090.  * \param definedIn If non-NULL, and the attribute is present, will be set to
  4091.  * the 'definedIn' string from the attribute.
  4092.  *
  4093.  * \param isGenerated If non-NULL, and the attribute is present, will be set to
  4094.  * non-zero if the 'generated_declaration' is set in the attribute.
  4095.  */
  4096. CINDEX_LINKAGE unsigned clang_Cursor_isExternalSymbol(CXCursor C,
  4097.                                                       CXString *language,
  4098.                                                       CXString *definedIn,
  4099.                                                       unsigned *isGenerated);
  4100.  
  4101. /**
  4102.  * Given a cursor that represents a declaration, return the associated
  4103.  * comment's source range.  The range may include multiple consecutive comments
  4104.  * with whitespace in between.
  4105.  */
  4106. CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange(CXCursor C);
  4107.  
  4108. /**
  4109.  * Given a cursor that represents a declaration, return the associated
  4110.  * comment text, including comment markers.
  4111.  */
  4112. CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText(CXCursor C);
  4113.  
  4114. /**
  4115.  * Given a cursor that represents a documentable entity (e.g.,
  4116.  * declaration), return the associated \paragraph; otherwise return the
  4117.  * first paragraph.
  4118.  */
  4119. CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C);
  4120.  
  4121. /**
  4122.  * @}
  4123.  */
  4124.  
  4125. /** \defgroup CINDEX_MANGLE Name Mangling API Functions
  4126.  *
  4127.  * @{
  4128.  */
  4129.  
  4130. /**
  4131.  * Retrieve the CXString representing the mangled name of the cursor.
  4132.  */
  4133. CINDEX_LINKAGE CXString clang_Cursor_getMangling(CXCursor);
  4134.  
  4135. /**
  4136.  * Retrieve the CXStrings representing the mangled symbols of the C++
  4137.  * constructor or destructor at the cursor.
  4138.  */
  4139. CINDEX_LINKAGE CXStringSet *clang_Cursor_getCXXManglings(CXCursor);
  4140.  
  4141. /**
  4142.  * Retrieve the CXStrings representing the mangled symbols of the ObjC
  4143.  * class interface or implementation at the cursor.
  4144.  */
  4145. CINDEX_LINKAGE CXStringSet *clang_Cursor_getObjCManglings(CXCursor);
  4146.  
  4147. /**
  4148.  * @}
  4149.  */
  4150.  
  4151. /**
  4152.  * \defgroup CINDEX_MODULE Module introspection
  4153.  *
  4154.  * The functions in this group provide access to information about modules.
  4155.  *
  4156.  * @{
  4157.  */
  4158.  
  4159. typedef void *CXModule;
  4160.  
  4161. /**
  4162.  * Given a CXCursor_ModuleImportDecl cursor, return the associated module.
  4163.  */
  4164. CINDEX_LINKAGE CXModule clang_Cursor_getModule(CXCursor C);
  4165.  
  4166. /**
  4167.  * Given a CXFile header file, return the module that contains it, if one
  4168.  * exists.
  4169.  */
  4170. CINDEX_LINKAGE CXModule clang_getModuleForFile(CXTranslationUnit, CXFile);
  4171.  
  4172. /**
  4173.  * \param Module a module object.
  4174.  *
  4175.  * \returns the module file where the provided module object came from.
  4176.  */
  4177. CINDEX_LINKAGE CXFile clang_Module_getASTFile(CXModule Module);
  4178.  
  4179. /**
  4180.  * \param Module a module object.
  4181.  *
  4182.  * \returns the parent of a sub-module or NULL if the given module is top-level,
  4183.  * e.g. for 'std.vector' it will return the 'std' module.
  4184.  */
  4185. CINDEX_LINKAGE CXModule clang_Module_getParent(CXModule Module);
  4186.  
  4187. /**
  4188.  * \param Module a module object.
  4189.  *
  4190.  * \returns the name of the module, e.g. for the 'std.vector' sub-module it
  4191.  * will return "vector".
  4192.  */
  4193. CINDEX_LINKAGE CXString clang_Module_getName(CXModule Module);
  4194.  
  4195. /**
  4196.  * \param Module a module object.
  4197.  *
  4198.  * \returns the full name of the module, e.g. "std.vector".
  4199.  */
  4200. CINDEX_LINKAGE CXString clang_Module_getFullName(CXModule Module);
  4201.  
  4202. /**
  4203.  * \param Module a module object.
  4204.  *
  4205.  * \returns non-zero if the module is a system one.
  4206.  */
  4207. CINDEX_LINKAGE int clang_Module_isSystem(CXModule Module);
  4208.  
  4209. /**
  4210.  * \param Module a module object.
  4211.  *
  4212.  * \returns the number of top level headers associated with this module.
  4213.  */
  4214. CINDEX_LINKAGE unsigned clang_Module_getNumTopLevelHeaders(CXTranslationUnit,
  4215.                                                            CXModule Module);
  4216.  
  4217. /**
  4218.  * \param Module a module object.
  4219.  *
  4220.  * \param Index top level header index (zero-based).
  4221.  *
  4222.  * \returns the specified top level header associated with the module.
  4223.  */
  4224. CINDEX_LINKAGE
  4225. CXFile clang_Module_getTopLevelHeader(CXTranslationUnit, CXModule Module,
  4226.                                       unsigned Index);
  4227.  
  4228. /**
  4229.  * @}
  4230.  */
  4231.  
  4232. /**
  4233.  * \defgroup CINDEX_CPP C++ AST introspection
  4234.  *
  4235.  * The routines in this group provide access information in the ASTs specific
  4236.  * to C++ language features.
  4237.  *
  4238.  * @{
  4239.  */
  4240.  
  4241. /**
  4242.  * Determine if a C++ constructor is a converting constructor.
  4243.  */
  4244. CINDEX_LINKAGE unsigned
  4245. clang_CXXConstructor_isConvertingConstructor(CXCursor C);
  4246.  
  4247. /**
  4248.  * Determine if a C++ constructor is a copy constructor.
  4249.  */
  4250. CINDEX_LINKAGE unsigned clang_CXXConstructor_isCopyConstructor(CXCursor C);
  4251.  
  4252. /**
  4253.  * Determine if a C++ constructor is the default constructor.
  4254.  */
  4255. CINDEX_LINKAGE unsigned clang_CXXConstructor_isDefaultConstructor(CXCursor C);
  4256.  
  4257. /**
  4258.  * Determine if a C++ constructor is a move constructor.
  4259.  */
  4260. CINDEX_LINKAGE unsigned clang_CXXConstructor_isMoveConstructor(CXCursor C);
  4261.  
  4262. /**
  4263.  * Determine if a C++ field is declared 'mutable'.
  4264.  */
  4265. CINDEX_LINKAGE unsigned clang_CXXField_isMutable(CXCursor C);
  4266.  
  4267. /**
  4268.  * Determine if a C++ method is declared '= default'.
  4269.  */
  4270. CINDEX_LINKAGE unsigned clang_CXXMethod_isDefaulted(CXCursor C);
  4271.  
  4272. /**
  4273.  * Determine if a C++ method is declared '= delete'.
  4274.  */
  4275. CINDEX_LINKAGE unsigned clang_CXXMethod_isDeleted(CXCursor C);
  4276.  
  4277. /**
  4278.  * Determine if a C++ member function or member function template is
  4279.  * pure virtual.
  4280.  */
  4281. CINDEX_LINKAGE unsigned clang_CXXMethod_isPureVirtual(CXCursor C);
  4282.  
  4283. /**
  4284.  * Determine if a C++ member function or member function template is
  4285.  * declared 'static'.
  4286.  */
  4287. CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C);
  4288.  
  4289. /**
  4290.  * Determine if a C++ member function or member function template is
  4291.  * explicitly declared 'virtual' or if it overrides a virtual method from
  4292.  * one of the base classes.
  4293.  */
  4294. CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C);
  4295.  
  4296. /**
  4297.  * Determine if a C++ member function is a copy-assignment operator,
  4298.  * returning 1 if such is the case and 0 otherwise.
  4299.  *
  4300.  * > A copy-assignment operator `X::operator=` is a non-static,
  4301.  * > non-template member function of _class_ `X` with exactly one
  4302.  * > parameter of type `X`, `X&`, `const X&`, `volatile X&` or `const
  4303.  * > volatile X&`.
  4304.  *
  4305.  * That is, for example, the `operator=` in:
  4306.  *
  4307.  *    class Foo {
  4308.  *        bool operator=(const volatile Foo&);
  4309.  *    };
  4310.  *
  4311.  * Is a copy-assignment operator, while the `operator=` in:
  4312.  *
  4313.  *    class Bar {
  4314.  *        bool operator=(const int&);
  4315.  *    };
  4316.  *
  4317.  * Is not.
  4318.  */
  4319. CINDEX_LINKAGE unsigned clang_CXXMethod_isCopyAssignmentOperator(CXCursor C);
  4320.  
  4321. /**
  4322.  * Determine if a C++ member function is a move-assignment operator,
  4323.  * returning 1 if such is the case and 0 otherwise.
  4324.  *
  4325.  * > A move-assignment operator `X::operator=` is a non-static,
  4326.  * > non-template member function of _class_ `X` with exactly one
  4327.  * > parameter of type `X&&`, `const X&&`, `volatile X&&` or `const
  4328.  * > volatile X&&`.
  4329.  *
  4330.  * That is, for example, the `operator=` in:
  4331.  *
  4332.  *    class Foo {
  4333.  *        bool operator=(const volatile Foo&&);
  4334.  *    };
  4335.  *
  4336.  * Is a move-assignment operator, while the `operator=` in:
  4337.  *
  4338.  *    class Bar {
  4339.  *        bool operator=(const int&&);
  4340.  *    };
  4341.  *
  4342.  * Is not.
  4343.  */
  4344. CINDEX_LINKAGE unsigned clang_CXXMethod_isMoveAssignmentOperator(CXCursor C);
  4345.  
  4346. /**
  4347.  * Determine if a C++ record is abstract, i.e. whether a class or struct
  4348.  * has a pure virtual member function.
  4349.  */
  4350. CINDEX_LINKAGE unsigned clang_CXXRecord_isAbstract(CXCursor C);
  4351.  
  4352. /**
  4353.  * Determine if an enum declaration refers to a scoped enum.
  4354.  */
  4355. CINDEX_LINKAGE unsigned clang_EnumDecl_isScoped(CXCursor C);
  4356.  
  4357. /**
  4358.  * Determine if a C++ member function or member function template is
  4359.  * declared 'const'.
  4360.  */
  4361. CINDEX_LINKAGE unsigned clang_CXXMethod_isConst(CXCursor C);
  4362.  
  4363. /**
  4364.  * Given a cursor that represents a template, determine
  4365.  * the cursor kind of the specializations would be generated by instantiating
  4366.  * the template.
  4367.  *
  4368.  * This routine can be used to determine what flavor of function template,
  4369.  * class template, or class template partial specialization is stored in the
  4370.  * cursor. For example, it can describe whether a class template cursor is
  4371.  * declared with "struct", "class" or "union".
  4372.  *
  4373.  * \param C The cursor to query. This cursor should represent a template
  4374.  * declaration.
  4375.  *
  4376.  * \returns The cursor kind of the specializations that would be generated
  4377.  * by instantiating the template \p C. If \p C is not a template, returns
  4378.  * \c CXCursor_NoDeclFound.
  4379.  */
  4380. CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C);
  4381.  
  4382. /**
  4383.  * Given a cursor that may represent a specialization or instantiation
  4384.  * of a template, retrieve the cursor that represents the template that it
  4385.  * specializes or from which it was instantiated.
  4386.  *
  4387.  * This routine determines the template involved both for explicit
  4388.  * specializations of templates and for implicit instantiations of the template,
  4389.  * both of which are referred to as "specializations". For a class template
  4390.  * specialization (e.g., \c std::vector<bool>), this routine will return
  4391.  * either the primary template (\c std::vector) or, if the specialization was
  4392.  * instantiated from a class template partial specialization, the class template
  4393.  * partial specialization. For a class template partial specialization and a
  4394.  * function template specialization (including instantiations), this
  4395.  * this routine will return the specialized template.
  4396.  *
  4397.  * For members of a class template (e.g., member functions, member classes, or
  4398.  * static data members), returns the specialized or instantiated member.
  4399.  * Although not strictly "templates" in the C++ language, members of class
  4400.  * templates have the same notions of specializations and instantiations that
  4401.  * templates do, so this routine treats them similarly.
  4402.  *
  4403.  * \param C A cursor that may be a specialization of a template or a member
  4404.  * of a template.
  4405.  *
  4406.  * \returns If the given cursor is a specialization or instantiation of a
  4407.  * template or a member thereof, the template or member that it specializes or
  4408.  * from which it was instantiated. Otherwise, returns a NULL cursor.
  4409.  */
  4410. CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C);
  4411.  
  4412. /**
  4413.  * Given a cursor that references something else, return the source range
  4414.  * covering that reference.
  4415.  *
  4416.  * \param C A cursor pointing to a member reference, a declaration reference, or
  4417.  * an operator call.
  4418.  * \param NameFlags A bitset with three independent flags:
  4419.  * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and
  4420.  * CXNameRange_WantSinglePiece.
  4421.  * \param PieceIndex For contiguous names or when passing the flag
  4422.  * CXNameRange_WantSinglePiece, only one piece with index 0 is
  4423.  * available. When the CXNameRange_WantSinglePiece flag is not passed for a
  4424.  * non-contiguous names, this index can be used to retrieve the individual
  4425.  * pieces of the name. See also CXNameRange_WantSinglePiece.
  4426.  *
  4427.  * \returns The piece of the name pointed to by the given cursor. If there is no
  4428.  * name, or if the PieceIndex is out-of-range, a null-cursor will be returned.
  4429.  */
  4430. CINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(
  4431.     CXCursor C, unsigned NameFlags, unsigned PieceIndex);
  4432.  
  4433. enum CXNameRefFlags {
  4434.   /**
  4435.    * Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the
  4436.    * range.
  4437.    */
  4438.   CXNameRange_WantQualifier = 0x1,
  4439.  
  4440.   /**
  4441.    * Include the explicit template arguments, e.g. \<int> in x.f<int>,
  4442.    * in the range.
  4443.    */
  4444.   CXNameRange_WantTemplateArgs = 0x2,
  4445.  
  4446.   /**
  4447.    * If the name is non-contiguous, return the full spanning range.
  4448.    *
  4449.    * Non-contiguous names occur in Objective-C when a selector with two or more
  4450.    * parameters is used, or in C++ when using an operator:
  4451.    * \code
  4452.    * [object doSomething:here withValue:there]; // Objective-C
  4453.    * return some_vector[1]; // C++
  4454.    * \endcode
  4455.    */
  4456.   CXNameRange_WantSinglePiece = 0x4
  4457. };
  4458.  
  4459. /**
  4460.  * @}
  4461.  */
  4462.  
  4463. /**
  4464.  * \defgroup CINDEX_LEX Token extraction and manipulation
  4465.  *
  4466.  * The routines in this group provide access to the tokens within a
  4467.  * translation unit, along with a semantic mapping of those tokens to
  4468.  * their corresponding cursors.
  4469.  *
  4470.  * @{
  4471.  */
  4472.  
  4473. /**
  4474.  * Describes a kind of token.
  4475.  */
  4476. typedef enum CXTokenKind {
  4477.   /**
  4478.    * A token that contains some kind of punctuation.
  4479.    */
  4480.   CXToken_Punctuation,
  4481.  
  4482.   /**
  4483.    * A language keyword.
  4484.    */
  4485.   CXToken_Keyword,
  4486.  
  4487.   /**
  4488.    * An identifier (that is not a keyword).
  4489.    */
  4490.   CXToken_Identifier,
  4491.  
  4492.   /**
  4493.    * A numeric, string, or character literal.
  4494.    */
  4495.   CXToken_Literal,
  4496.  
  4497.   /**
  4498.    * A comment.
  4499.    */
  4500.   CXToken_Comment
  4501. } CXTokenKind;
  4502.  
  4503. /**
  4504.  * Describes a single preprocessing token.
  4505.  */
  4506. typedef struct {
  4507.   unsigned int_data[4];
  4508.   void *ptr_data;
  4509. } CXToken;
  4510.  
  4511. /**
  4512.  * Get the raw lexical token starting with the given location.
  4513.  *
  4514.  * \param TU the translation unit whose text is being tokenized.
  4515.  *
  4516.  * \param Location the source location with which the token starts.
  4517.  *
  4518.  * \returns The token starting with the given location or NULL if no such token
  4519.  * exist. The returned pointer must be freed with clang_disposeTokens before the
  4520.  * translation unit is destroyed.
  4521.  */
  4522. CINDEX_LINKAGE CXToken *clang_getToken(CXTranslationUnit TU,
  4523.                                        CXSourceLocation Location);
  4524.  
  4525. /**
  4526.  * Determine the kind of the given token.
  4527.  */
  4528. CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken);
  4529.  
  4530. /**
  4531.  * Determine the spelling of the given token.
  4532.  *
  4533.  * The spelling of a token is the textual representation of that token, e.g.,
  4534.  * the text of an identifier or keyword.
  4535.  */
  4536. CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken);
  4537.  
  4538. /**
  4539.  * Retrieve the source location of the given token.
  4540.  */
  4541. CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit,
  4542.                                                        CXToken);
  4543.  
  4544. /**
  4545.  * Retrieve a source range that covers the given token.
  4546.  */
  4547. CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken);
  4548.  
  4549. /**
  4550.  * Tokenize the source code described by the given range into raw
  4551.  * lexical tokens.
  4552.  *
  4553.  * \param TU the translation unit whose text is being tokenized.
  4554.  *
  4555.  * \param Range the source range in which text should be tokenized. All of the
  4556.  * tokens produced by tokenization will fall within this source range,
  4557.  *
  4558.  * \param Tokens this pointer will be set to point to the array of tokens
  4559.  * that occur within the given source range. The returned pointer must be
  4560.  * freed with clang_disposeTokens() before the translation unit is destroyed.
  4561.  *
  4562.  * \param NumTokens will be set to the number of tokens in the \c *Tokens
  4563.  * array.
  4564.  *
  4565.  */
  4566. CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range,
  4567.                                    CXToken **Tokens, unsigned *NumTokens);
  4568.  
  4569. /**
  4570.  * Annotate the given set of tokens by providing cursors for each token
  4571.  * that can be mapped to a specific entity within the abstract syntax tree.
  4572.  *
  4573.  * This token-annotation routine is equivalent to invoking
  4574.  * clang_getCursor() for the source locations of each of the
  4575.  * tokens. The cursors provided are filtered, so that only those
  4576.  * cursors that have a direct correspondence to the token are
  4577.  * accepted. For example, given a function call \c f(x),
  4578.  * clang_getCursor() would provide the following cursors:
  4579.  *
  4580.  *   * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
  4581.  *   * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
  4582.  *   * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
  4583.  *
  4584.  * Only the first and last of these cursors will occur within the
  4585.  * annotate, since the tokens "f" and "x' directly refer to a function
  4586.  * and a variable, respectively, but the parentheses are just a small
  4587.  * part of the full syntax of the function call expression, which is
  4588.  * not provided as an annotation.
  4589.  *
  4590.  * \param TU the translation unit that owns the given tokens.
  4591.  *
  4592.  * \param Tokens the set of tokens to annotate.
  4593.  *
  4594.  * \param NumTokens the number of tokens in \p Tokens.
  4595.  *
  4596.  * \param Cursors an array of \p NumTokens cursors, whose contents will be
  4597.  * replaced with the cursors corresponding to each token.
  4598.  */
  4599. CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, CXToken *Tokens,
  4600.                                          unsigned NumTokens, CXCursor *Cursors);
  4601.  
  4602. /**
  4603.  * Free the given set of tokens.
  4604.  */
  4605. CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, CXToken *Tokens,
  4606.                                         unsigned NumTokens);
  4607.  
  4608. /**
  4609.  * @}
  4610.  */
  4611.  
  4612. /**
  4613.  * \defgroup CINDEX_DEBUG Debugging facilities
  4614.  *
  4615.  * These routines are used for testing and debugging, only, and should not
  4616.  * be relied upon.
  4617.  *
  4618.  * @{
  4619.  */
  4620.  
  4621. /* for debug/testing */
  4622. CINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind);
  4623. CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(
  4624.     CXCursor, const char **startBuf, const char **endBuf, unsigned *startLine,
  4625.     unsigned *startColumn, unsigned *endLine, unsigned *endColumn);
  4626. CINDEX_LINKAGE void clang_enableStackTraces(void);
  4627. CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void *), void *user_data,
  4628.                                           unsigned stack_size);
  4629.  
  4630. /**
  4631.  * @}
  4632.  */
  4633.  
  4634. /**
  4635.  * \defgroup CINDEX_CODE_COMPLET Code completion
  4636.  *
  4637.  * Code completion involves taking an (incomplete) source file, along with
  4638.  * knowledge of where the user is actively editing that file, and suggesting
  4639.  * syntactically- and semantically-valid constructs that the user might want to
  4640.  * use at that particular point in the source code. These data structures and
  4641.  * routines provide support for code completion.
  4642.  *
  4643.  * @{
  4644.  */
  4645.  
  4646. /**
  4647.  * A semantic string that describes a code-completion result.
  4648.  *
  4649.  * A semantic string that describes the formatting of a code-completion
  4650.  * result as a single "template" of text that should be inserted into the
  4651.  * source buffer when a particular code-completion result is selected.
  4652.  * Each semantic string is made up of some number of "chunks", each of which
  4653.  * contains some text along with a description of what that text means, e.g.,
  4654.  * the name of the entity being referenced, whether the text chunk is part of
  4655.  * the template, or whether it is a "placeholder" that the user should replace
  4656.  * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
  4657.  * description of the different kinds of chunks.
  4658.  */
  4659. typedef void *CXCompletionString;
  4660.  
  4661. /**
  4662.  * A single result of code completion.
  4663.  */
  4664. typedef struct {
  4665.   /**
  4666.    * The kind of entity that this completion refers to.
  4667.    *
  4668.    * The cursor kind will be a macro, keyword, or a declaration (one of the
  4669.    * *Decl cursor kinds), describing the entity that the completion is
  4670.    * referring to.
  4671.    *
  4672.    * \todo In the future, we would like to provide a full cursor, to allow
  4673.    * the client to extract additional information from declaration.
  4674.    */
  4675.   enum CXCursorKind CursorKind;
  4676.  
  4677.   /**
  4678.    * The code-completion string that describes how to insert this
  4679.    * code-completion result into the editing buffer.
  4680.    */
  4681.   CXCompletionString CompletionString;
  4682. } CXCompletionResult;
  4683.  
  4684. /**
  4685.  * Describes a single piece of text within a code-completion string.
  4686.  *
  4687.  * Each "chunk" within a code-completion string (\c CXCompletionString) is
  4688.  * either a piece of text with a specific "kind" that describes how that text
  4689.  * should be interpreted by the client or is another completion string.
  4690.  */
  4691. enum CXCompletionChunkKind {
  4692.   /**
  4693.    * A code-completion string that describes "optional" text that
  4694.    * could be a part of the template (but is not required).
  4695.    *
  4696.    * The Optional chunk is the only kind of chunk that has a code-completion
  4697.    * string for its representation, which is accessible via
  4698.    * \c clang_getCompletionChunkCompletionString(). The code-completion string
  4699.    * describes an additional part of the template that is completely optional.
  4700.    * For example, optional chunks can be used to describe the placeholders for
  4701.    * arguments that match up with defaulted function parameters, e.g. given:
  4702.    *
  4703.    * \code
  4704.    * void f(int x, float y = 3.14, double z = 2.71828);
  4705.    * \endcode
  4706.    *
  4707.    * The code-completion string for this function would contain:
  4708.    *   - a TypedText chunk for "f".
  4709.    *   - a LeftParen chunk for "(".
  4710.    *   - a Placeholder chunk for "int x"
  4711.    *   - an Optional chunk containing the remaining defaulted arguments, e.g.,
  4712.    *       - a Comma chunk for ","
  4713.    *       - a Placeholder chunk for "float y"
  4714.    *       - an Optional chunk containing the last defaulted argument:
  4715.    *           - a Comma chunk for ","
  4716.    *           - a Placeholder chunk for "double z"
  4717.    *   - a RightParen chunk for ")"
  4718.    *
  4719.    * There are many ways to handle Optional chunks. Two simple approaches are:
  4720.    *   - Completely ignore optional chunks, in which case the template for the
  4721.    *     function "f" would only include the first parameter ("int x").
  4722.    *   - Fully expand all optional chunks, in which case the template for the
  4723.    *     function "f" would have all of the parameters.
  4724.    */
  4725.   CXCompletionChunk_Optional,
  4726.   /**
  4727.    * Text that a user would be expected to type to get this
  4728.    * code-completion result.
  4729.    *
  4730.    * There will be exactly one "typed text" chunk in a semantic string, which
  4731.    * will typically provide the spelling of a keyword or the name of a
  4732.    * declaration that could be used at the current code point. Clients are
  4733.    * expected to filter the code-completion results based on the text in this
  4734.    * chunk.
  4735.    */
  4736.   CXCompletionChunk_TypedText,
  4737.   /**
  4738.    * Text that should be inserted as part of a code-completion result.
  4739.    *
  4740.    * A "text" chunk represents text that is part of the template to be
  4741.    * inserted into user code should this particular code-completion result
  4742.    * be selected.
  4743.    */
  4744.   CXCompletionChunk_Text,
  4745.   /**
  4746.    * Placeholder text that should be replaced by the user.
  4747.    *
  4748.    * A "placeholder" chunk marks a place where the user should insert text
  4749.    * into the code-completion template. For example, placeholders might mark
  4750.    * the function parameters for a function declaration, to indicate that the
  4751.    * user should provide arguments for each of those parameters. The actual
  4752.    * text in a placeholder is a suggestion for the text to display before
  4753.    * the user replaces the placeholder with real code.
  4754.    */
  4755.   CXCompletionChunk_Placeholder,
  4756.   /**
  4757.    * Informative text that should be displayed but never inserted as
  4758.    * part of the template.
  4759.    *
  4760.    * An "informative" chunk contains annotations that can be displayed to
  4761.    * help the user decide whether a particular code-completion result is the
  4762.    * right option, but which is not part of the actual template to be inserted
  4763.    * by code completion.
  4764.    */
  4765.   CXCompletionChunk_Informative,
  4766.   /**
  4767.    * Text that describes the current parameter when code-completion is
  4768.    * referring to function call, message send, or template specialization.
  4769.    *
  4770.    * A "current parameter" chunk occurs when code-completion is providing
  4771.    * information about a parameter corresponding to the argument at the
  4772.    * code-completion point. For example, given a function
  4773.    *
  4774.    * \code
  4775.    * int add(int x, int y);
  4776.    * \endcode
  4777.    *
  4778.    * and the source code \c add(, where the code-completion point is after the
  4779.    * "(", the code-completion string will contain a "current parameter" chunk
  4780.    * for "int x", indicating that the current argument will initialize that
  4781.    * parameter. After typing further, to \c add(17, (where the code-completion
  4782.    * point is after the ","), the code-completion string will contain a
  4783.    * "current parameter" chunk to "int y".
  4784.    */
  4785.   CXCompletionChunk_CurrentParameter,
  4786.   /**
  4787.    * A left parenthesis ('('), used to initiate a function call or
  4788.    * signal the beginning of a function parameter list.
  4789.    */
  4790.   CXCompletionChunk_LeftParen,
  4791.   /**
  4792.    * A right parenthesis (')'), used to finish a function call or
  4793.    * signal the end of a function parameter list.
  4794.    */
  4795.   CXCompletionChunk_RightParen,
  4796.   /**
  4797.    * A left bracket ('[').
  4798.    */
  4799.   CXCompletionChunk_LeftBracket,
  4800.   /**
  4801.    * A right bracket (']').
  4802.    */
  4803.   CXCompletionChunk_RightBracket,
  4804.   /**
  4805.    * A left brace ('{').
  4806.    */
  4807.   CXCompletionChunk_LeftBrace,
  4808.   /**
  4809.    * A right brace ('}').
  4810.    */
  4811.   CXCompletionChunk_RightBrace,
  4812.   /**
  4813.    * A left angle bracket ('<').
  4814.    */
  4815.   CXCompletionChunk_LeftAngle,
  4816.   /**
  4817.    * A right angle bracket ('>').
  4818.    */
  4819.   CXCompletionChunk_RightAngle,
  4820.   /**
  4821.    * A comma separator (',').
  4822.    */
  4823.   CXCompletionChunk_Comma,
  4824.   /**
  4825.    * Text that specifies the result type of a given result.
  4826.    *
  4827.    * This special kind of informative chunk is not meant to be inserted into
  4828.    * the text buffer. Rather, it is meant to illustrate the type that an
  4829.    * expression using the given completion string would have.
  4830.    */
  4831.   CXCompletionChunk_ResultType,
  4832.   /**
  4833.    * A colon (':').
  4834.    */
  4835.   CXCompletionChunk_Colon,
  4836.   /**
  4837.    * A semicolon (';').
  4838.    */
  4839.   CXCompletionChunk_SemiColon,
  4840.   /**
  4841.    * An '=' sign.
  4842.    */
  4843.   CXCompletionChunk_Equal,
  4844.   /**
  4845.    * Horizontal space (' ').
  4846.    */
  4847.   CXCompletionChunk_HorizontalSpace,
  4848.   /**
  4849.    * Vertical space ('\\n'), after which it is generally a good idea to
  4850.    * perform indentation.
  4851.    */
  4852.   CXCompletionChunk_VerticalSpace
  4853. };
  4854.  
  4855. /**
  4856.  * Determine the kind of a particular chunk within a completion string.
  4857.  *
  4858.  * \param completion_string the completion string to query.
  4859.  *
  4860.  * \param chunk_number the 0-based index of the chunk in the completion string.
  4861.  *
  4862.  * \returns the kind of the chunk at the index \c chunk_number.
  4863.  */
  4864. CINDEX_LINKAGE enum CXCompletionChunkKind
  4865. clang_getCompletionChunkKind(CXCompletionString completion_string,
  4866.                              unsigned chunk_number);
  4867.  
  4868. /**
  4869.  * Retrieve the text associated with a particular chunk within a
  4870.  * completion string.
  4871.  *
  4872.  * \param completion_string the completion string to query.
  4873.  *
  4874.  * \param chunk_number the 0-based index of the chunk in the completion string.
  4875.  *
  4876.  * \returns the text associated with the chunk at index \c chunk_number.
  4877.  */
  4878. CINDEX_LINKAGE CXString clang_getCompletionChunkText(
  4879.     CXCompletionString completion_string, unsigned chunk_number);
  4880.  
  4881. /**
  4882.  * Retrieve the completion string associated with a particular chunk
  4883.  * within a completion string.
  4884.  *
  4885.  * \param completion_string the completion string to query.
  4886.  *
  4887.  * \param chunk_number the 0-based index of the chunk in the completion string.
  4888.  *
  4889.  * \returns the completion string associated with the chunk at index
  4890.  * \c chunk_number.
  4891.  */
  4892. CINDEX_LINKAGE CXCompletionString clang_getCompletionChunkCompletionString(
  4893.     CXCompletionString completion_string, unsigned chunk_number);
  4894.  
  4895. /**
  4896.  * Retrieve the number of chunks in the given code-completion string.
  4897.  */
  4898. CINDEX_LINKAGE unsigned
  4899. clang_getNumCompletionChunks(CXCompletionString completion_string);
  4900.  
  4901. /**
  4902.  * Determine the priority of this code completion.
  4903.  *
  4904.  * The priority of a code completion indicates how likely it is that this
  4905.  * particular completion is the completion that the user will select. The
  4906.  * priority is selected by various internal heuristics.
  4907.  *
  4908.  * \param completion_string The completion string to query.
  4909.  *
  4910.  * \returns The priority of this completion string. Smaller values indicate
  4911.  * higher-priority (more likely) completions.
  4912.  */
  4913. CINDEX_LINKAGE unsigned
  4914. clang_getCompletionPriority(CXCompletionString completion_string);
  4915.  
  4916. /**
  4917.  * Determine the availability of the entity that this code-completion
  4918.  * string refers to.
  4919.  *
  4920.  * \param completion_string The completion string to query.
  4921.  *
  4922.  * \returns The availability of the completion string.
  4923.  */
  4924. CINDEX_LINKAGE enum CXAvailabilityKind
  4925. clang_getCompletionAvailability(CXCompletionString completion_string);
  4926.  
  4927. /**
  4928.  * Retrieve the number of annotations associated with the given
  4929.  * completion string.
  4930.  *
  4931.  * \param completion_string the completion string to query.
  4932.  *
  4933.  * \returns the number of annotations associated with the given completion
  4934.  * string.
  4935.  */
  4936. CINDEX_LINKAGE unsigned
  4937. clang_getCompletionNumAnnotations(CXCompletionString completion_string);
  4938.  
  4939. /**
  4940.  * Retrieve the annotation associated with the given completion string.
  4941.  *
  4942.  * \param completion_string the completion string to query.
  4943.  *
  4944.  * \param annotation_number the 0-based index of the annotation of the
  4945.  * completion string.
  4946.  *
  4947.  * \returns annotation string associated with the completion at index
  4948.  * \c annotation_number, or a NULL string if that annotation is not available.
  4949.  */
  4950. CINDEX_LINKAGE CXString clang_getCompletionAnnotation(
  4951.     CXCompletionString completion_string, unsigned annotation_number);
  4952.  
  4953. /**
  4954.  * Retrieve the parent context of the given completion string.
  4955.  *
  4956.  * The parent context of a completion string is the semantic parent of
  4957.  * the declaration (if any) that the code completion represents. For example,
  4958.  * a code completion for an Objective-C method would have the method's class
  4959.  * or protocol as its context.
  4960.  *
  4961.  * \param completion_string The code completion string whose parent is
  4962.  * being queried.
  4963.  *
  4964.  * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL.
  4965.  *
  4966.  * \returns The name of the completion parent, e.g., "NSObject" if
  4967.  * the completion string represents a method in the NSObject class.
  4968.  */
  4969. CINDEX_LINKAGE CXString clang_getCompletionParent(
  4970.     CXCompletionString completion_string, enum CXCursorKind *kind);
  4971.  
  4972. /**
  4973.  * Retrieve the brief documentation comment attached to the declaration
  4974.  * that corresponds to the given completion string.
  4975.  */
  4976. CINDEX_LINKAGE CXString
  4977. clang_getCompletionBriefComment(CXCompletionString completion_string);
  4978.  
  4979. /**
  4980.  * Retrieve a completion string for an arbitrary declaration or macro
  4981.  * definition cursor.
  4982.  *
  4983.  * \param cursor The cursor to query.
  4984.  *
  4985.  * \returns A non-context-sensitive completion string for declaration and macro
  4986.  * definition cursors, or NULL for other kinds of cursors.
  4987.  */
  4988. CINDEX_LINKAGE CXCompletionString
  4989. clang_getCursorCompletionString(CXCursor cursor);
  4990.  
  4991. /**
  4992.  * Contains the results of code-completion.
  4993.  *
  4994.  * This data structure contains the results of code completion, as
  4995.  * produced by \c clang_codeCompleteAt(). Its contents must be freed by
  4996.  * \c clang_disposeCodeCompleteResults.
  4997.  */
  4998. typedef struct {
  4999.   /**
  5000.    * The code-completion results.
  5001.    */
  5002.   CXCompletionResult *Results;
  5003.  
  5004.   /**
  5005.    * The number of code-completion results stored in the
  5006.    * \c Results array.
  5007.    */
  5008.   unsigned NumResults;
  5009. } CXCodeCompleteResults;
  5010.  
  5011. /**
  5012.  * Retrieve the number of fix-its for the given completion index.
  5013.  *
  5014.  * Calling this makes sense only if CXCodeComplete_IncludeCompletionsWithFixIts
  5015.  * option was set.
  5016.  *
  5017.  * \param results The structure keeping all completion results
  5018.  *
  5019.  * \param completion_index The index of the completion
  5020.  *
  5021.  * \return The number of fix-its which must be applied before the completion at
  5022.  * completion_index can be applied
  5023.  */
  5024. CINDEX_LINKAGE unsigned
  5025. clang_getCompletionNumFixIts(CXCodeCompleteResults *results,
  5026.                              unsigned completion_index);
  5027.  
  5028. /**
  5029.  * Fix-its that *must* be applied before inserting the text for the
  5030.  * corresponding completion.
  5031.  *
  5032.  * By default, clang_codeCompleteAt() only returns completions with empty
  5033.  * fix-its. Extra completions with non-empty fix-its should be explicitly
  5034.  * requested by setting CXCodeComplete_IncludeCompletionsWithFixIts.
  5035.  *
  5036.  * For the clients to be able to compute position of the cursor after applying
  5037.  * fix-its, the following conditions are guaranteed to hold for
  5038.  * replacement_range of the stored fix-its:
  5039.  *  - Ranges in the fix-its are guaranteed to never contain the completion
  5040.  *  point (or identifier under completion point, if any) inside them, except
  5041.  *  at the start or at the end of the range.
  5042.  *  - If a fix-it range starts or ends with completion point (or starts or
  5043.  *  ends after the identifier under completion point), it will contain at
  5044.  *  least one character. It allows to unambiguously recompute completion
  5045.  *  point after applying the fix-it.
  5046.  *
  5047.  * The intuition is that provided fix-its change code around the identifier we
  5048.  * complete, but are not allowed to touch the identifier itself or the
  5049.  * completion point. One example of completions with corrections are the ones
  5050.  * replacing '.' with '->' and vice versa:
  5051.  *
  5052.  * std::unique_ptr<std::vector<int>> vec_ptr;
  5053.  * In 'vec_ptr.^', one of the completions is 'push_back', it requires
  5054.  * replacing '.' with '->'.
  5055.  * In 'vec_ptr->^', one of the completions is 'release', it requires
  5056.  * replacing '->' with '.'.
  5057.  *
  5058.  * \param results The structure keeping all completion results
  5059.  *
  5060.  * \param completion_index The index of the completion
  5061.  *
  5062.  * \param fixit_index The index of the fix-it for the completion at
  5063.  * completion_index
  5064.  *
  5065.  * \param replacement_range The fix-it range that must be replaced before the
  5066.  * completion at completion_index can be applied
  5067.  *
  5068.  * \returns The fix-it string that must replace the code at replacement_range
  5069.  * before the completion at completion_index can be applied
  5070.  */
  5071. CINDEX_LINKAGE CXString clang_getCompletionFixIt(
  5072.     CXCodeCompleteResults *results, unsigned completion_index,
  5073.     unsigned fixit_index, CXSourceRange *replacement_range);
  5074.  
  5075. /**
  5076.  * Flags that can be passed to \c clang_codeCompleteAt() to
  5077.  * modify its behavior.
  5078.  *
  5079.  * The enumerators in this enumeration can be bitwise-OR'd together to
  5080.  * provide multiple options to \c clang_codeCompleteAt().
  5081.  */
  5082. enum CXCodeComplete_Flags {
  5083.   /**
  5084.    * Whether to include macros within the set of code
  5085.    * completions returned.
  5086.    */
  5087.   CXCodeComplete_IncludeMacros = 0x01,
  5088.  
  5089.   /**
  5090.    * Whether to include code patterns for language constructs
  5091.    * within the set of code completions, e.g., for loops.
  5092.    */
  5093.   CXCodeComplete_IncludeCodePatterns = 0x02,
  5094.  
  5095.   /**
  5096.    * Whether to include brief documentation within the set of code
  5097.    * completions returned.
  5098.    */
  5099.   CXCodeComplete_IncludeBriefComments = 0x04,
  5100.  
  5101.   /**
  5102.    * Whether to speed up completion by omitting top- or namespace-level entities
  5103.    * defined in the preamble. There's no guarantee any particular entity is
  5104.    * omitted. This may be useful if the headers are indexed externally.
  5105.    */
  5106.   CXCodeComplete_SkipPreamble = 0x08,
  5107.  
  5108.   /**
  5109.    * Whether to include completions with small
  5110.    * fix-its, e.g. change '.' to '->' on member access, etc.
  5111.    */
  5112.   CXCodeComplete_IncludeCompletionsWithFixIts = 0x10
  5113. };
  5114.  
  5115. /**
  5116.  * Bits that represent the context under which completion is occurring.
  5117.  *
  5118.  * The enumerators in this enumeration may be bitwise-OR'd together if multiple
  5119.  * contexts are occurring simultaneously.
  5120.  */
  5121. enum CXCompletionContext {
  5122.   /**
  5123.    * The context for completions is unexposed, as only Clang results
  5124.    * should be included. (This is equivalent to having no context bits set.)
  5125.    */
  5126.   CXCompletionContext_Unexposed = 0,
  5127.  
  5128.   /**
  5129.    * Completions for any possible type should be included in the results.
  5130.    */
  5131.   CXCompletionContext_AnyType = 1 << 0,
  5132.  
  5133.   /**
  5134.    * Completions for any possible value (variables, function calls, etc.)
  5135.    * should be included in the results.
  5136.    */
  5137.   CXCompletionContext_AnyValue = 1 << 1,
  5138.   /**
  5139.    * Completions for values that resolve to an Objective-C object should
  5140.    * be included in the results.
  5141.    */
  5142.   CXCompletionContext_ObjCObjectValue = 1 << 2,
  5143.   /**
  5144.    * Completions for values that resolve to an Objective-C selector
  5145.    * should be included in the results.
  5146.    */
  5147.   CXCompletionContext_ObjCSelectorValue = 1 << 3,
  5148.   /**
  5149.    * Completions for values that resolve to a C++ class type should be
  5150.    * included in the results.
  5151.    */
  5152.   CXCompletionContext_CXXClassTypeValue = 1 << 4,
  5153.  
  5154.   /**
  5155.    * Completions for fields of the member being accessed using the dot
  5156.    * operator should be included in the results.
  5157.    */
  5158.   CXCompletionContext_DotMemberAccess = 1 << 5,
  5159.   /**
  5160.    * Completions for fields of the member being accessed using the arrow
  5161.    * operator should be included in the results.
  5162.    */
  5163.   CXCompletionContext_ArrowMemberAccess = 1 << 6,
  5164.   /**
  5165.    * Completions for properties of the Objective-C object being accessed
  5166.    * using the dot operator should be included in the results.
  5167.    */
  5168.   CXCompletionContext_ObjCPropertyAccess = 1 << 7,
  5169.  
  5170.   /**
  5171.    * Completions for enum tags should be included in the results.
  5172.    */
  5173.   CXCompletionContext_EnumTag = 1 << 8,
  5174.   /**
  5175.    * Completions for union tags should be included in the results.
  5176.    */
  5177.   CXCompletionContext_UnionTag = 1 << 9,
  5178.   /**
  5179.    * Completions for struct tags should be included in the results.
  5180.    */
  5181.   CXCompletionContext_StructTag = 1 << 10,
  5182.  
  5183.   /**
  5184.    * Completions for C++ class names should be included in the results.
  5185.    */
  5186.   CXCompletionContext_ClassTag = 1 << 11,
  5187.   /**
  5188.    * Completions for C++ namespaces and namespace aliases should be
  5189.    * included in the results.
  5190.    */
  5191.   CXCompletionContext_Namespace = 1 << 12,
  5192.   /**
  5193.    * Completions for C++ nested name specifiers should be included in
  5194.    * the results.
  5195.    */
  5196.   CXCompletionContext_NestedNameSpecifier = 1 << 13,
  5197.  
  5198.   /**
  5199.    * Completions for Objective-C interfaces (classes) should be included
  5200.    * in the results.
  5201.    */
  5202.   CXCompletionContext_ObjCInterface = 1 << 14,
  5203.   /**
  5204.    * Completions for Objective-C protocols should be included in
  5205.    * the results.
  5206.    */
  5207.   CXCompletionContext_ObjCProtocol = 1 << 15,
  5208.   /**
  5209.    * Completions for Objective-C categories should be included in
  5210.    * the results.
  5211.    */
  5212.   CXCompletionContext_ObjCCategory = 1 << 16,
  5213.   /**
  5214.    * Completions for Objective-C instance messages should be included
  5215.    * in the results.
  5216.    */
  5217.   CXCompletionContext_ObjCInstanceMessage = 1 << 17,
  5218.   /**
  5219.    * Completions for Objective-C class messages should be included in
  5220.    * the results.
  5221.    */
  5222.   CXCompletionContext_ObjCClassMessage = 1 << 18,
  5223.   /**
  5224.    * Completions for Objective-C selector names should be included in
  5225.    * the results.
  5226.    */
  5227.   CXCompletionContext_ObjCSelectorName = 1 << 19,
  5228.  
  5229.   /**
  5230.    * Completions for preprocessor macro names should be included in
  5231.    * the results.
  5232.    */
  5233.   CXCompletionContext_MacroName = 1 << 20,
  5234.  
  5235.   /**
  5236.    * Natural language completions should be included in the results.
  5237.    */
  5238.   CXCompletionContext_NaturalLanguage = 1 << 21,
  5239.  
  5240.   /**
  5241.    * #include file completions should be included in the results.
  5242.    */
  5243.   CXCompletionContext_IncludedFile = 1 << 22,
  5244.  
  5245.   /**
  5246.    * The current context is unknown, so set all contexts.
  5247.    */
  5248.   CXCompletionContext_Unknown = ((1 << 23) - 1)
  5249. };
  5250.  
  5251. /**
  5252.  * Returns a default set of code-completion options that can be
  5253.  * passed to\c clang_codeCompleteAt().
  5254.  */
  5255. CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void);
  5256.  
  5257. /**
  5258.  * Perform code completion at a given location in a translation unit.
  5259.  *
  5260.  * This function performs code completion at a particular file, line, and
  5261.  * column within source code, providing results that suggest potential
  5262.  * code snippets based on the context of the completion. The basic model
  5263.  * for code completion is that Clang will parse a complete source file,
  5264.  * performing syntax checking up to the location where code-completion has
  5265.  * been requested. At that point, a special code-completion token is passed
  5266.  * to the parser, which recognizes this token and determines, based on the
  5267.  * current location in the C/Objective-C/C++ grammar and the state of
  5268.  * semantic analysis, what completions to provide. These completions are
  5269.  * returned via a new \c CXCodeCompleteResults structure.
  5270.  *
  5271.  * Code completion itself is meant to be triggered by the client when the
  5272.  * user types punctuation characters or whitespace, at which point the
  5273.  * code-completion location will coincide with the cursor. For example, if \c p
  5274.  * is a pointer, code-completion might be triggered after the "-" and then
  5275.  * after the ">" in \c p->. When the code-completion location is after the ">",
  5276.  * the completion results will provide, e.g., the members of the struct that
  5277.  * "p" points to. The client is responsible for placing the cursor at the
  5278.  * beginning of the token currently being typed, then filtering the results
  5279.  * based on the contents of the token. For example, when code-completing for
  5280.  * the expression \c p->get, the client should provide the location just after
  5281.  * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
  5282.  * client can filter the results based on the current token text ("get"), only
  5283.  * showing those results that start with "get". The intent of this interface
  5284.  * is to separate the relatively high-latency acquisition of code-completion
  5285.  * results from the filtering of results on a per-character basis, which must
  5286.  * have a lower latency.
  5287.  *
  5288.  * \param TU The translation unit in which code-completion should
  5289.  * occur. The source files for this translation unit need not be
  5290.  * completely up-to-date (and the contents of those source files may
  5291.  * be overridden via \p unsaved_files). Cursors referring into the
  5292.  * translation unit may be invalidated by this invocation.
  5293.  *
  5294.  * \param complete_filename The name of the source file where code
  5295.  * completion should be performed. This filename may be any file
  5296.  * included in the translation unit.
  5297.  *
  5298.  * \param complete_line The line at which code-completion should occur.
  5299.  *
  5300.  * \param complete_column The column at which code-completion should occur.
  5301.  * Note that the column should point just after the syntactic construct that
  5302.  * initiated code completion, and not in the middle of a lexical token.
  5303.  *
  5304.  * \param unsaved_files the Files that have not yet been saved to disk
  5305.  * but may be required for parsing or code completion, including the
  5306.  * contents of those files.  The contents and name of these files (as
  5307.  * specified by CXUnsavedFile) are copied when necessary, so the
  5308.  * client only needs to guarantee their validity until the call to
  5309.  * this function returns.
  5310.  *
  5311.  * \param num_unsaved_files The number of unsaved file entries in \p
  5312.  * unsaved_files.
  5313.  *
  5314.  * \param options Extra options that control the behavior of code
  5315.  * completion, expressed as a bitwise OR of the enumerators of the
  5316.  * CXCodeComplete_Flags enumeration. The
  5317.  * \c clang_defaultCodeCompleteOptions() function returns a default set
  5318.  * of code-completion options.
  5319.  *
  5320.  * \returns If successful, a new \c CXCodeCompleteResults structure
  5321.  * containing code-completion results, which should eventually be
  5322.  * freed with \c clang_disposeCodeCompleteResults(). If code
  5323.  * completion fails, returns NULL.
  5324.  */
  5325. CINDEX_LINKAGE
  5326. CXCodeCompleteResults *
  5327. clang_codeCompleteAt(CXTranslationUnit TU, const char *complete_filename,
  5328.                      unsigned complete_line, unsigned complete_column,
  5329.                      struct CXUnsavedFile *unsaved_files,
  5330.                      unsigned num_unsaved_files, unsigned options);
  5331.  
  5332. /**
  5333.  * Sort the code-completion results in case-insensitive alphabetical
  5334.  * order.
  5335.  *
  5336.  * \param Results The set of results to sort.
  5337.  * \param NumResults The number of results in \p Results.
  5338.  */
  5339. CINDEX_LINKAGE
  5340. void clang_sortCodeCompletionResults(CXCompletionResult *Results,
  5341.                                      unsigned NumResults);
  5342.  
  5343. /**
  5344.  * Free the given set of code-completion results.
  5345.  */
  5346. CINDEX_LINKAGE
  5347. void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results);
  5348.  
  5349. /**
  5350.  * Determine the number of diagnostics produced prior to the
  5351.  * location where code completion was performed.
  5352.  */
  5353. CINDEX_LINKAGE
  5354. unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results);
  5355.  
  5356. /**
  5357.  * Retrieve a diagnostic associated with the given code completion.
  5358.  *
  5359.  * \param Results the code completion results to query.
  5360.  * \param Index the zero-based diagnostic number to retrieve.
  5361.  *
  5362.  * \returns the requested diagnostic. This diagnostic must be freed
  5363.  * via a call to \c clang_disposeDiagnostic().
  5364.  */
  5365. CINDEX_LINKAGE
  5366. CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results,
  5367.                                              unsigned Index);
  5368.  
  5369. /**
  5370.  * Determines what completions are appropriate for the context
  5371.  * the given code completion.
  5372.  *
  5373.  * \param Results the code completion results to query
  5374.  *
  5375.  * \returns the kinds of completions that are appropriate for use
  5376.  * along with the given code completion results.
  5377.  */
  5378. CINDEX_LINKAGE
  5379. unsigned long long
  5380. clang_codeCompleteGetContexts(CXCodeCompleteResults *Results);
  5381.  
  5382. /**
  5383.  * Returns the cursor kind for the container for the current code
  5384.  * completion context. The container is only guaranteed to be set for
  5385.  * contexts where a container exists (i.e. member accesses or Objective-C
  5386.  * message sends); if there is not a container, this function will return
  5387.  * CXCursor_InvalidCode.
  5388.  *
  5389.  * \param Results the code completion results to query
  5390.  *
  5391.  * \param IsIncomplete on return, this value will be false if Clang has complete
  5392.  * information about the container. If Clang does not have complete
  5393.  * information, this value will be true.
  5394.  *
  5395.  * \returns the container kind, or CXCursor_InvalidCode if there is not a
  5396.  * container
  5397.  */
  5398. CINDEX_LINKAGE
  5399. enum CXCursorKind
  5400. clang_codeCompleteGetContainerKind(CXCodeCompleteResults *Results,
  5401.                                    unsigned *IsIncomplete);
  5402.  
  5403. /**
  5404.  * Returns the USR for the container for the current code completion
  5405.  * context. If there is not a container for the current context, this
  5406.  * function will return the empty string.
  5407.  *
  5408.  * \param Results the code completion results to query
  5409.  *
  5410.  * \returns the USR for the container
  5411.  */
  5412. CINDEX_LINKAGE
  5413. CXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results);
  5414.  
  5415. /**
  5416.  * Returns the currently-entered selector for an Objective-C message
  5417.  * send, formatted like "initWithFoo:bar:". Only guaranteed to return a
  5418.  * non-empty string for CXCompletionContext_ObjCInstanceMessage and
  5419.  * CXCompletionContext_ObjCClassMessage.
  5420.  *
  5421.  * \param Results the code completion results to query
  5422.  *
  5423.  * \returns the selector (or partial selector) that has been entered thus far
  5424.  * for an Objective-C message send.
  5425.  */
  5426. CINDEX_LINKAGE
  5427. CXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results);
  5428.  
  5429. /**
  5430.  * @}
  5431.  */
  5432.  
  5433. /**
  5434.  * \defgroup CINDEX_MISC Miscellaneous utility functions
  5435.  *
  5436.  * @{
  5437.  */
  5438.  
  5439. /**
  5440.  * Return a version string, suitable for showing to a user, but not
  5441.  *        intended to be parsed (the format is not guaranteed to be stable).
  5442.  */
  5443. CINDEX_LINKAGE CXString clang_getClangVersion(void);
  5444.  
  5445. /**
  5446.  * Enable/disable crash recovery.
  5447.  *
  5448.  * \param isEnabled Flag to indicate if crash recovery is enabled.  A non-zero
  5449.  *        value enables crash recovery, while 0 disables it.
  5450.  */
  5451. CINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled);
  5452.  
  5453. /**
  5454.  * Visitor invoked for each file in a translation unit
  5455.  *        (used with clang_getInclusions()).
  5456.  *
  5457.  * This visitor function will be invoked by clang_getInclusions() for each
  5458.  * file included (either at the top-level or by \#include directives) within
  5459.  * a translation unit.  The first argument is the file being included, and
  5460.  * the second and third arguments provide the inclusion stack.  The
  5461.  * array is sorted in order of immediate inclusion.  For example,
  5462.  * the first element refers to the location that included 'included_file'.
  5463.  */
  5464. typedef void (*CXInclusionVisitor)(CXFile included_file,
  5465.                                    CXSourceLocation *inclusion_stack,
  5466.                                    unsigned include_len,
  5467.                                    CXClientData client_data);
  5468.  
  5469. /**
  5470.  * Visit the set of preprocessor inclusions in a translation unit.
  5471.  *   The visitor function is called with the provided data for every included
  5472.  *   file.  This does not include headers included by the PCH file (unless one
  5473.  *   is inspecting the inclusions in the PCH file itself).
  5474.  */
  5475. CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu,
  5476.                                         CXInclusionVisitor visitor,
  5477.                                         CXClientData client_data);
  5478.  
  5479. typedef enum {
  5480.   CXEval_Int = 1,
  5481.   CXEval_Float = 2,
  5482.   CXEval_ObjCStrLiteral = 3,
  5483.   CXEval_StrLiteral = 4,
  5484.   CXEval_CFStr = 5,
  5485.   CXEval_Other = 6,
  5486.  
  5487.   CXEval_UnExposed = 0
  5488.  
  5489. } CXEvalResultKind;
  5490.  
  5491. /**
  5492.  * Evaluation result of a cursor
  5493.  */
  5494. typedef void *CXEvalResult;
  5495.  
  5496. /**
  5497.  * If cursor is a statement declaration tries to evaluate the
  5498.  * statement and if its variable, tries to evaluate its initializer,
  5499.  * into its corresponding type.
  5500.  * If it's an expression, tries to evaluate the expression.
  5501.  */
  5502. CINDEX_LINKAGE CXEvalResult clang_Cursor_Evaluate(CXCursor C);
  5503.  
  5504. /**
  5505.  * Returns the kind of the evaluated result.
  5506.  */
  5507. CINDEX_LINKAGE CXEvalResultKind clang_EvalResult_getKind(CXEvalResult E);
  5508.  
  5509. /**
  5510.  * Returns the evaluation result as integer if the
  5511.  * kind is Int.
  5512.  */
  5513. CINDEX_LINKAGE int clang_EvalResult_getAsInt(CXEvalResult E);
  5514.  
  5515. /**
  5516.  * Returns the evaluation result as a long long integer if the
  5517.  * kind is Int. This prevents overflows that may happen if the result is
  5518.  * returned with clang_EvalResult_getAsInt.
  5519.  */
  5520. CINDEX_LINKAGE long long clang_EvalResult_getAsLongLong(CXEvalResult E);
  5521.  
  5522. /**
  5523.  * Returns a non-zero value if the kind is Int and the evaluation
  5524.  * result resulted in an unsigned integer.
  5525.  */
  5526. CINDEX_LINKAGE unsigned clang_EvalResult_isUnsignedInt(CXEvalResult E);
  5527.  
  5528. /**
  5529.  * Returns the evaluation result as an unsigned integer if
  5530.  * the kind is Int and clang_EvalResult_isUnsignedInt is non-zero.
  5531.  */
  5532. CINDEX_LINKAGE unsigned long long
  5533. clang_EvalResult_getAsUnsigned(CXEvalResult E);
  5534.  
  5535. /**
  5536.  * Returns the evaluation result as double if the
  5537.  * kind is double.
  5538.  */
  5539. CINDEX_LINKAGE double clang_EvalResult_getAsDouble(CXEvalResult E);
  5540.  
  5541. /**
  5542.  * Returns the evaluation result as a constant string if the
  5543.  * kind is other than Int or float. User must not free this pointer,
  5544.  * instead call clang_EvalResult_dispose on the CXEvalResult returned
  5545.  * by clang_Cursor_Evaluate.
  5546.  */
  5547. CINDEX_LINKAGE const char *clang_EvalResult_getAsStr(CXEvalResult E);
  5548.  
  5549. /**
  5550.  * Disposes the created Eval memory.
  5551.  */
  5552. CINDEX_LINKAGE void clang_EvalResult_dispose(CXEvalResult E);
  5553. /**
  5554.  * @}
  5555.  */
  5556.  
  5557. /** \defgroup CINDEX_REMAPPING Remapping functions
  5558.  *
  5559.  * @{
  5560.  */
  5561.  
  5562. /**
  5563.  * A remapping of original source files and their translated files.
  5564.  */
  5565. typedef void *CXRemapping;
  5566.  
  5567. /**
  5568.  * Retrieve a remapping.
  5569.  *
  5570.  * \param path the path that contains metadata about remappings.
  5571.  *
  5572.  * \returns the requested remapping. This remapping must be freed
  5573.  * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred.
  5574.  */
  5575. CINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path);
  5576.  
  5577. /**
  5578.  * Retrieve a remapping.
  5579.  *
  5580.  * \param filePaths pointer to an array of file paths containing remapping info.
  5581.  *
  5582.  * \param numFiles number of file paths.
  5583.  *
  5584.  * \returns the requested remapping. This remapping must be freed
  5585.  * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred.
  5586.  */
  5587. CINDEX_LINKAGE
  5588. CXRemapping clang_getRemappingsFromFileList(const char **filePaths,
  5589.                                             unsigned numFiles);
  5590.  
  5591. /**
  5592.  * Determine the number of remappings.
  5593.  */
  5594. CINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping);
  5595.  
  5596. /**
  5597.  * Get the original and the associated filename from the remapping.
  5598.  *
  5599.  * \param original If non-NULL, will be set to the original filename.
  5600.  *
  5601.  * \param transformed If non-NULL, will be set to the filename that the original
  5602.  * is associated with.
  5603.  */
  5604. CINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index,
  5605.                                              CXString *original,
  5606.                                              CXString *transformed);
  5607.  
  5608. /**
  5609.  * Dispose the remapping.
  5610.  */
  5611. CINDEX_LINKAGE void clang_remap_dispose(CXRemapping);
  5612.  
  5613. /**
  5614.  * @}
  5615.  */
  5616.  
  5617. /** \defgroup CINDEX_HIGH Higher level API functions
  5618.  *
  5619.  * @{
  5620.  */
  5621.  
  5622. enum CXVisitorResult { CXVisit_Break, CXVisit_Continue };
  5623.  
  5624. typedef struct CXCursorAndRangeVisitor {
  5625.   void *context;
  5626.   enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange);
  5627. } CXCursorAndRangeVisitor;
  5628.  
  5629. typedef enum {
  5630.   /**
  5631.    * Function returned successfully.
  5632.    */
  5633.   CXResult_Success = 0,
  5634.   /**
  5635.    * One of the parameters was invalid for the function.
  5636.    */
  5637.   CXResult_Invalid = 1,
  5638.   /**
  5639.    * The function was terminated by a callback (e.g. it returned
  5640.    * CXVisit_Break)
  5641.    */
  5642.   CXResult_VisitBreak = 2
  5643.  
  5644. } CXResult;
  5645.  
  5646. /**
  5647.  * Find references of a declaration in a specific file.
  5648.  *
  5649.  * \param cursor pointing to a declaration or a reference of one.
  5650.  *
  5651.  * \param file to search for references.
  5652.  *
  5653.  * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for
  5654.  * each reference found.
  5655.  * The CXSourceRange will point inside the file; if the reference is inside
  5656.  * a macro (and not a macro argument) the CXSourceRange will be invalid.
  5657.  *
  5658.  * \returns one of the CXResult enumerators.
  5659.  */
  5660. CINDEX_LINKAGE CXResult clang_findReferencesInFile(
  5661.     CXCursor cursor, CXFile file, CXCursorAndRangeVisitor visitor);
  5662.  
  5663. /**
  5664.  * Find #import/#include directives in a specific file.
  5665.  *
  5666.  * \param TU translation unit containing the file to query.
  5667.  *
  5668.  * \param file to search for #import/#include directives.
  5669.  *
  5670.  * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for
  5671.  * each directive found.
  5672.  *
  5673.  * \returns one of the CXResult enumerators.
  5674.  */
  5675. CINDEX_LINKAGE CXResult clang_findIncludesInFile(
  5676.     CXTranslationUnit TU, CXFile file, CXCursorAndRangeVisitor visitor);
  5677.  
  5678. #ifdef __has_feature
  5679. #if __has_feature(blocks)
  5680.  
  5681. typedef enum CXVisitorResult (^CXCursorAndRangeVisitorBlock)(CXCursor,
  5682.                                                              CXSourceRange);
  5683.  
  5684. CINDEX_LINKAGE
  5685. CXResult clang_findReferencesInFileWithBlock(CXCursor, CXFile,
  5686.                                              CXCursorAndRangeVisitorBlock);
  5687.  
  5688. CINDEX_LINKAGE
  5689. CXResult clang_findIncludesInFileWithBlock(CXTranslationUnit, CXFile,
  5690.                                            CXCursorAndRangeVisitorBlock);
  5691.  
  5692. #endif
  5693. #endif
  5694.  
  5695. /**
  5696.  * The client's data object that is associated with a CXFile.
  5697.  */
  5698. typedef void *CXIdxClientFile;
  5699.  
  5700. /**
  5701.  * The client's data object that is associated with a semantic entity.
  5702.  */
  5703. typedef void *CXIdxClientEntity;
  5704.  
  5705. /**
  5706.  * The client's data object that is associated with a semantic container
  5707.  * of entities.
  5708.  */
  5709. typedef void *CXIdxClientContainer;
  5710.  
  5711. /**
  5712.  * The client's data object that is associated with an AST file (PCH
  5713.  * or module).
  5714.  */
  5715. typedef void *CXIdxClientASTFile;
  5716.  
  5717. /**
  5718.  * Source location passed to index callbacks.
  5719.  */
  5720. typedef struct {
  5721.   void *ptr_data[2];
  5722.   unsigned int_data;
  5723. } CXIdxLoc;
  5724.  
  5725. /**
  5726.  * Data for ppIncludedFile callback.
  5727.  */
  5728. typedef struct {
  5729.   /**
  5730.    * Location of '#' in the \#include/\#import directive.
  5731.    */
  5732.   CXIdxLoc hashLoc;
  5733.   /**
  5734.    * Filename as written in the \#include/\#import directive.
  5735.    */
  5736.   const char *filename;
  5737.   /**
  5738.    * The actual file that the \#include/\#import directive resolved to.
  5739.    */
  5740.   CXFile file;
  5741.   int isImport;
  5742.   int isAngled;
  5743.   /**
  5744.    * Non-zero if the directive was automatically turned into a module
  5745.    * import.
  5746.    */
  5747.   int isModuleImport;
  5748. } CXIdxIncludedFileInfo;
  5749.  
  5750. /**
  5751.  * Data for IndexerCallbacks#importedASTFile.
  5752.  */
  5753. typedef struct {
  5754.   /**
  5755.    * Top level AST file containing the imported PCH, module or submodule.
  5756.    */
  5757.   CXFile file;
  5758.   /**
  5759.    * The imported module or NULL if the AST file is a PCH.
  5760.    */
  5761.   CXModule module;
  5762.   /**
  5763.    * Location where the file is imported. Applicable only for modules.
  5764.    */
  5765.   CXIdxLoc loc;
  5766.   /**
  5767.    * Non-zero if an inclusion directive was automatically turned into
  5768.    * a module import. Applicable only for modules.
  5769.    */
  5770.   int isImplicit;
  5771.  
  5772. } CXIdxImportedASTFileInfo;
  5773.  
  5774. typedef enum {
  5775.   CXIdxEntity_Unexposed = 0,
  5776.   CXIdxEntity_Typedef = 1,
  5777.   CXIdxEntity_Function = 2,
  5778.   CXIdxEntity_Variable = 3,
  5779.   CXIdxEntity_Field = 4,
  5780.   CXIdxEntity_EnumConstant = 5,
  5781.  
  5782.   CXIdxEntity_ObjCClass = 6,
  5783.   CXIdxEntity_ObjCProtocol = 7,
  5784.   CXIdxEntity_ObjCCategory = 8,
  5785.  
  5786.   CXIdxEntity_ObjCInstanceMethod = 9,
  5787.   CXIdxEntity_ObjCClassMethod = 10,
  5788.   CXIdxEntity_ObjCProperty = 11,
  5789.   CXIdxEntity_ObjCIvar = 12,
  5790.  
  5791.   CXIdxEntity_Enum = 13,
  5792.   CXIdxEntity_Struct = 14,
  5793.   CXIdxEntity_Union = 15,
  5794.  
  5795.   CXIdxEntity_CXXClass = 16,
  5796.   CXIdxEntity_CXXNamespace = 17,
  5797.   CXIdxEntity_CXXNamespaceAlias = 18,
  5798.   CXIdxEntity_CXXStaticVariable = 19,
  5799.   CXIdxEntity_CXXStaticMethod = 20,
  5800.   CXIdxEntity_CXXInstanceMethod = 21,
  5801.   CXIdxEntity_CXXConstructor = 22,
  5802.   CXIdxEntity_CXXDestructor = 23,
  5803.   CXIdxEntity_CXXConversionFunction = 24,
  5804.   CXIdxEntity_CXXTypeAlias = 25,
  5805.   CXIdxEntity_CXXInterface = 26,
  5806.   CXIdxEntity_CXXConcept = 27
  5807.  
  5808. } CXIdxEntityKind;
  5809.  
  5810. typedef enum {
  5811.   CXIdxEntityLang_None = 0,
  5812.   CXIdxEntityLang_C = 1,
  5813.   CXIdxEntityLang_ObjC = 2,
  5814.   CXIdxEntityLang_CXX = 3,
  5815.   CXIdxEntityLang_Swift = 4
  5816. } CXIdxEntityLanguage;
  5817.  
  5818. /**
  5819.  * Extra C++ template information for an entity. This can apply to:
  5820.  * CXIdxEntity_Function
  5821.  * CXIdxEntity_CXXClass
  5822.  * CXIdxEntity_CXXStaticMethod
  5823.  * CXIdxEntity_CXXInstanceMethod
  5824.  * CXIdxEntity_CXXConstructor
  5825.  * CXIdxEntity_CXXConversionFunction
  5826.  * CXIdxEntity_CXXTypeAlias
  5827.  */
  5828. typedef enum {
  5829.   CXIdxEntity_NonTemplate = 0,
  5830.   CXIdxEntity_Template = 1,
  5831.   CXIdxEntity_TemplatePartialSpecialization = 2,
  5832.   CXIdxEntity_TemplateSpecialization = 3
  5833. } CXIdxEntityCXXTemplateKind;
  5834.  
  5835. typedef enum {
  5836.   CXIdxAttr_Unexposed = 0,
  5837.   CXIdxAttr_IBAction = 1,
  5838.   CXIdxAttr_IBOutlet = 2,
  5839.   CXIdxAttr_IBOutletCollection = 3
  5840. } CXIdxAttrKind;
  5841.  
  5842. typedef struct {
  5843.   CXIdxAttrKind kind;
  5844.   CXCursor cursor;
  5845.   CXIdxLoc loc;
  5846. } CXIdxAttrInfo;
  5847.  
  5848. typedef struct {
  5849.   CXIdxEntityKind kind;
  5850.   CXIdxEntityCXXTemplateKind templateKind;
  5851.   CXIdxEntityLanguage lang;
  5852.   const char *name;
  5853.   const char *USR;
  5854.   CXCursor cursor;
  5855.   const CXIdxAttrInfo *const *attributes;
  5856.   unsigned numAttributes;
  5857. } CXIdxEntityInfo;
  5858.  
  5859. typedef struct {
  5860.   CXCursor cursor;
  5861. } CXIdxContainerInfo;
  5862.  
  5863. typedef struct {
  5864.   const CXIdxAttrInfo *attrInfo;
  5865.   const CXIdxEntityInfo *objcClass;
  5866.   CXCursor classCursor;
  5867.   CXIdxLoc classLoc;
  5868. } CXIdxIBOutletCollectionAttrInfo;
  5869.  
  5870. typedef enum { CXIdxDeclFlag_Skipped = 0x1 } CXIdxDeclInfoFlags;
  5871.  
  5872. typedef struct {
  5873.   const CXIdxEntityInfo *entityInfo;
  5874.   CXCursor cursor;
  5875.   CXIdxLoc loc;
  5876.   const CXIdxContainerInfo *semanticContainer;
  5877.   /**
  5878.    * Generally same as #semanticContainer but can be different in
  5879.    * cases like out-of-line C++ member functions.
  5880.    */
  5881.   const CXIdxContainerInfo *lexicalContainer;
  5882.   int isRedeclaration;
  5883.   int isDefinition;
  5884.   int isContainer;
  5885.   const CXIdxContainerInfo *declAsContainer;
  5886.   /**
  5887.    * Whether the declaration exists in code or was created implicitly
  5888.    * by the compiler, e.g. implicit Objective-C methods for properties.
  5889.    */
  5890.   int isImplicit;
  5891.   const CXIdxAttrInfo *const *attributes;
  5892.   unsigned numAttributes;
  5893.  
  5894.   unsigned flags;
  5895.  
  5896. } CXIdxDeclInfo;
  5897.  
  5898. typedef enum {
  5899.   CXIdxObjCContainer_ForwardRef = 0,
  5900.   CXIdxObjCContainer_Interface = 1,
  5901.   CXIdxObjCContainer_Implementation = 2
  5902. } CXIdxObjCContainerKind;
  5903.  
  5904. typedef struct {
  5905.   const CXIdxDeclInfo *declInfo;
  5906.   CXIdxObjCContainerKind kind;
  5907. } CXIdxObjCContainerDeclInfo;
  5908.  
  5909. typedef struct {
  5910.   const CXIdxEntityInfo *base;
  5911.   CXCursor cursor;
  5912.   CXIdxLoc loc;
  5913. } CXIdxBaseClassInfo;
  5914.  
  5915. typedef struct {
  5916.   const CXIdxEntityInfo *protocol;
  5917.   CXCursor cursor;
  5918.   CXIdxLoc loc;
  5919. } CXIdxObjCProtocolRefInfo;
  5920.  
  5921. typedef struct {
  5922.   const CXIdxObjCProtocolRefInfo *const *protocols;
  5923.   unsigned numProtocols;
  5924. } CXIdxObjCProtocolRefListInfo;
  5925.  
  5926. typedef struct {
  5927.   const CXIdxObjCContainerDeclInfo *containerInfo;
  5928.   const CXIdxBaseClassInfo *superInfo;
  5929.   const CXIdxObjCProtocolRefListInfo *protocols;
  5930. } CXIdxObjCInterfaceDeclInfo;
  5931.  
  5932. typedef struct {
  5933.   const CXIdxObjCContainerDeclInfo *containerInfo;
  5934.   const CXIdxEntityInfo *objcClass;
  5935.   CXCursor classCursor;
  5936.   CXIdxLoc classLoc;
  5937.   const CXIdxObjCProtocolRefListInfo *protocols;
  5938. } CXIdxObjCCategoryDeclInfo;
  5939.  
  5940. typedef struct {
  5941.   const CXIdxDeclInfo *declInfo;
  5942.   const CXIdxEntityInfo *getter;
  5943.   const CXIdxEntityInfo *setter;
  5944. } CXIdxObjCPropertyDeclInfo;
  5945.  
  5946. typedef struct {
  5947.   const CXIdxDeclInfo *declInfo;
  5948.   const CXIdxBaseClassInfo *const *bases;
  5949.   unsigned numBases;
  5950. } CXIdxCXXClassDeclInfo;
  5951.  
  5952. /**
  5953.  * Data for IndexerCallbacks#indexEntityReference.
  5954.  *
  5955.  * This may be deprecated in a future version as this duplicates
  5956.  * the \c CXSymbolRole_Implicit bit in \c CXSymbolRole.
  5957.  */
  5958. typedef enum {
  5959.   /**
  5960.    * The entity is referenced directly in user's code.
  5961.    */
  5962.   CXIdxEntityRef_Direct = 1,
  5963.   /**
  5964.    * An implicit reference, e.g. a reference of an Objective-C method
  5965.    * via the dot syntax.
  5966.    */
  5967.   CXIdxEntityRef_Implicit = 2
  5968. } CXIdxEntityRefKind;
  5969.  
  5970. /**
  5971.  * Roles that are attributed to symbol occurrences.
  5972.  *
  5973.  * Internal: this currently mirrors low 9 bits of clang::index::SymbolRole with
  5974.  * higher bits zeroed. These high bits may be exposed in the future.
  5975.  */
  5976. typedef enum {
  5977.   CXSymbolRole_None = 0,
  5978.   CXSymbolRole_Declaration = 1 << 0,
  5979.   CXSymbolRole_Definition = 1 << 1,
  5980.   CXSymbolRole_Reference = 1 << 2,
  5981.   CXSymbolRole_Read = 1 << 3,
  5982.   CXSymbolRole_Write = 1 << 4,
  5983.   CXSymbolRole_Call = 1 << 5,
  5984.   CXSymbolRole_Dynamic = 1 << 6,
  5985.   CXSymbolRole_AddressOf = 1 << 7,
  5986.   CXSymbolRole_Implicit = 1 << 8
  5987. } CXSymbolRole;
  5988.  
  5989. /**
  5990.  * Data for IndexerCallbacks#indexEntityReference.
  5991.  */
  5992. typedef struct {
  5993.   CXIdxEntityRefKind kind;
  5994.   /**
  5995.    * Reference cursor.
  5996.    */
  5997.   CXCursor cursor;
  5998.   CXIdxLoc loc;
  5999.   /**
  6000.    * The entity that gets referenced.
  6001.    */
  6002.   const CXIdxEntityInfo *referencedEntity;
  6003.   /**
  6004.    * Immediate "parent" of the reference. For example:
  6005.    *
  6006.    * \code
  6007.    * Foo *var;
  6008.    * \endcode
  6009.    *
  6010.    * The parent of reference of type 'Foo' is the variable 'var'.
  6011.    * For references inside statement bodies of functions/methods,
  6012.    * the parentEntity will be the function/method.
  6013.    */
  6014.   const CXIdxEntityInfo *parentEntity;
  6015.   /**
  6016.    * Lexical container context of the reference.
  6017.    */
  6018.   const CXIdxContainerInfo *container;
  6019.   /**
  6020.    * Sets of symbol roles of the reference.
  6021.    */
  6022.   CXSymbolRole role;
  6023. } CXIdxEntityRefInfo;
  6024.  
  6025. /**
  6026.  * A group of callbacks used by #clang_indexSourceFile and
  6027.  * #clang_indexTranslationUnit.
  6028.  */
  6029. typedef struct {
  6030.   /**
  6031.    * Called periodically to check whether indexing should be aborted.
  6032.    * Should return 0 to continue, and non-zero to abort.
  6033.    */
  6034.   int (*abortQuery)(CXClientData client_data, void *reserved);
  6035.  
  6036.   /**
  6037.    * Called at the end of indexing; passes the complete diagnostic set.
  6038.    */
  6039.   void (*diagnostic)(CXClientData client_data, CXDiagnosticSet, void *reserved);
  6040.  
  6041.   CXIdxClientFile (*enteredMainFile)(CXClientData client_data, CXFile mainFile,
  6042.                                      void *reserved);
  6043.  
  6044.   /**
  6045.    * Called when a file gets \#included/\#imported.
  6046.    */
  6047.   CXIdxClientFile (*ppIncludedFile)(CXClientData client_data,
  6048.                                     const CXIdxIncludedFileInfo *);
  6049.  
  6050.   /**
  6051.    * Called when a AST file (PCH or module) gets imported.
  6052.    *
  6053.    * AST files will not get indexed (there will not be callbacks to index all
  6054.    * the entities in an AST file). The recommended action is that, if the AST
  6055.    * file is not already indexed, to initiate a new indexing job specific to
  6056.    * the AST file.
  6057.    */
  6058.   CXIdxClientASTFile (*importedASTFile)(CXClientData client_data,
  6059.                                         const CXIdxImportedASTFileInfo *);
  6060.  
  6061.   /**
  6062.    * Called at the beginning of indexing a translation unit.
  6063.    */
  6064.   CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data,
  6065.                                                  void *reserved);
  6066.  
  6067.   void (*indexDeclaration)(CXClientData client_data, const CXIdxDeclInfo *);
  6068.  
  6069.   /**
  6070.    * Called to index a reference of an entity.
  6071.    */
  6072.   void (*indexEntityReference)(CXClientData client_data,
  6073.                                const CXIdxEntityRefInfo *);
  6074.  
  6075. } IndexerCallbacks;
  6076.  
  6077. CINDEX_LINKAGE int clang_index_isEntityObjCContainerKind(CXIdxEntityKind);
  6078. CINDEX_LINKAGE const CXIdxObjCContainerDeclInfo *
  6079. clang_index_getObjCContainerDeclInfo(const CXIdxDeclInfo *);
  6080.  
  6081. CINDEX_LINKAGE const CXIdxObjCInterfaceDeclInfo *
  6082. clang_index_getObjCInterfaceDeclInfo(const CXIdxDeclInfo *);
  6083.  
  6084. CINDEX_LINKAGE
  6085. const CXIdxObjCCategoryDeclInfo *
  6086. clang_index_getObjCCategoryDeclInfo(const CXIdxDeclInfo *);
  6087.  
  6088. CINDEX_LINKAGE const CXIdxObjCProtocolRefListInfo *
  6089. clang_index_getObjCProtocolRefListInfo(const CXIdxDeclInfo *);
  6090.  
  6091. CINDEX_LINKAGE const CXIdxObjCPropertyDeclInfo *
  6092. clang_index_getObjCPropertyDeclInfo(const CXIdxDeclInfo *);
  6093.  
  6094. CINDEX_LINKAGE const CXIdxIBOutletCollectionAttrInfo *
  6095. clang_index_getIBOutletCollectionAttrInfo(const CXIdxAttrInfo *);
  6096.  
  6097. CINDEX_LINKAGE const CXIdxCXXClassDeclInfo *
  6098. clang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *);
  6099.  
  6100. /**
  6101.  * For retrieving a custom CXIdxClientContainer attached to a
  6102.  * container.
  6103.  */
  6104. CINDEX_LINKAGE CXIdxClientContainer
  6105. clang_index_getClientContainer(const CXIdxContainerInfo *);
  6106.  
  6107. /**
  6108.  * For setting a custom CXIdxClientContainer attached to a
  6109.  * container.
  6110.  */
  6111. CINDEX_LINKAGE void clang_index_setClientContainer(const CXIdxContainerInfo *,
  6112.                                                    CXIdxClientContainer);
  6113.  
  6114. /**
  6115.  * For retrieving a custom CXIdxClientEntity attached to an entity.
  6116.  */
  6117. CINDEX_LINKAGE CXIdxClientEntity
  6118. clang_index_getClientEntity(const CXIdxEntityInfo *);
  6119.  
  6120. /**
  6121.  * For setting a custom CXIdxClientEntity attached to an entity.
  6122.  */
  6123. CINDEX_LINKAGE void clang_index_setClientEntity(const CXIdxEntityInfo *,
  6124.                                                 CXIdxClientEntity);
  6125.  
  6126. /**
  6127.  * An indexing action/session, to be applied to one or multiple
  6128.  * translation units.
  6129.  */
  6130. typedef void *CXIndexAction;
  6131.  
  6132. /**
  6133.  * An indexing action/session, to be applied to one or multiple
  6134.  * translation units.
  6135.  *
  6136.  * \param CIdx The index object with which the index action will be associated.
  6137.  */
  6138. CINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx);
  6139.  
  6140. /**
  6141.  * Destroy the given index action.
  6142.  *
  6143.  * The index action must not be destroyed until all of the translation units
  6144.  * created within that index action have been destroyed.
  6145.  */
  6146. CINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction);
  6147.  
  6148. typedef enum {
  6149.   /**
  6150.    * Used to indicate that no special indexing options are needed.
  6151.    */
  6152.   CXIndexOpt_None = 0x0,
  6153.  
  6154.   /**
  6155.    * Used to indicate that IndexerCallbacks#indexEntityReference should
  6156.    * be invoked for only one reference of an entity per source file that does
  6157.    * not also include a declaration/definition of the entity.
  6158.    */
  6159.   CXIndexOpt_SuppressRedundantRefs = 0x1,
  6160.  
  6161.   /**
  6162.    * Function-local symbols should be indexed. If this is not set
  6163.    * function-local symbols will be ignored.
  6164.    */
  6165.   CXIndexOpt_IndexFunctionLocalSymbols = 0x2,
  6166.  
  6167.   /**
  6168.    * Implicit function/class template instantiations should be indexed.
  6169.    * If this is not set, implicit instantiations will be ignored.
  6170.    */
  6171.   CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4,
  6172.  
  6173.   /**
  6174.    * Suppress all compiler warnings when parsing for indexing.
  6175.    */
  6176.   CXIndexOpt_SuppressWarnings = 0x8,
  6177.  
  6178.   /**
  6179.    * Skip a function/method body that was already parsed during an
  6180.    * indexing session associated with a \c CXIndexAction object.
  6181.    * Bodies in system headers are always skipped.
  6182.    */
  6183.   CXIndexOpt_SkipParsedBodiesInSession = 0x10
  6184.  
  6185. } CXIndexOptFlags;
  6186.  
  6187. /**
  6188.  * Index the given source file and the translation unit corresponding
  6189.  * to that file via callbacks implemented through #IndexerCallbacks.
  6190.  *
  6191.  * \param client_data pointer data supplied by the client, which will
  6192.  * be passed to the invoked callbacks.
  6193.  *
  6194.  * \param index_callbacks Pointer to indexing callbacks that the client
  6195.  * implements.
  6196.  *
  6197.  * \param index_callbacks_size Size of #IndexerCallbacks structure that gets
  6198.  * passed in index_callbacks.
  6199.  *
  6200.  * \param index_options A bitmask of options that affects how indexing is
  6201.  * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags.
  6202.  *
  6203.  * \param[out] out_TU pointer to store a \c CXTranslationUnit that can be
  6204.  * reused after indexing is finished. Set to \c NULL if you do not require it.
  6205.  *
  6206.  * \returns 0 on success or if there were errors from which the compiler could
  6207.  * recover.  If there is a failure from which there is no recovery, returns
  6208.  * a non-zero \c CXErrorCode.
  6209.  *
  6210.  * The rest of the parameters are the same as #clang_parseTranslationUnit.
  6211.  */
  6212. CINDEX_LINKAGE int clang_indexSourceFile(
  6213.     CXIndexAction, CXClientData client_data, IndexerCallbacks *index_callbacks,
  6214.     unsigned index_callbacks_size, unsigned index_options,
  6215.     const char *source_filename, const char *const *command_line_args,
  6216.     int num_command_line_args, struct CXUnsavedFile *unsaved_files,
  6217.     unsigned num_unsaved_files, CXTranslationUnit *out_TU, unsigned TU_options);
  6218.  
  6219. /**
  6220.  * Same as clang_indexSourceFile but requires a full command line
  6221.  * for \c command_line_args including argv[0]. This is useful if the standard
  6222.  * library paths are relative to the binary.
  6223.  */
  6224. CINDEX_LINKAGE int clang_indexSourceFileFullArgv(
  6225.     CXIndexAction, CXClientData client_data, IndexerCallbacks *index_callbacks,
  6226.     unsigned index_callbacks_size, unsigned index_options,
  6227.     const char *source_filename, const char *const *command_line_args,
  6228.     int num_command_line_args, struct CXUnsavedFile *unsaved_files,
  6229.     unsigned num_unsaved_files, CXTranslationUnit *out_TU, unsigned TU_options);
  6230.  
  6231. /**
  6232.  * Index the given translation unit via callbacks implemented through
  6233.  * #IndexerCallbacks.
  6234.  *
  6235.  * The order of callback invocations is not guaranteed to be the same as
  6236.  * when indexing a source file. The high level order will be:
  6237.  *
  6238.  *   -Preprocessor callbacks invocations
  6239.  *   -Declaration/reference callbacks invocations
  6240.  *   -Diagnostic callback invocations
  6241.  *
  6242.  * The parameters are the same as #clang_indexSourceFile.
  6243.  *
  6244.  * \returns If there is a failure from which there is no recovery, returns
  6245.  * non-zero, otherwise returns 0.
  6246.  */
  6247. CINDEX_LINKAGE int clang_indexTranslationUnit(
  6248.     CXIndexAction, CXClientData client_data, IndexerCallbacks *index_callbacks,
  6249.     unsigned index_callbacks_size, unsigned index_options, CXTranslationUnit);
  6250.  
  6251. /**
  6252.  * Retrieve the CXIdxFile, file, line, column, and offset represented by
  6253.  * the given CXIdxLoc.
  6254.  *
  6255.  * If the location refers into a macro expansion, retrieves the
  6256.  * location of the macro expansion and if it refers into a macro argument
  6257.  * retrieves the location of the argument.
  6258.  */
  6259. CINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc,
  6260.                                                    CXIdxClientFile *indexFile,
  6261.                                                    CXFile *file, unsigned *line,
  6262.                                                    unsigned *column,
  6263.                                                    unsigned *offset);
  6264.  
  6265. /**
  6266.  * Retrieve the CXSourceLocation represented by the given CXIdxLoc.
  6267.  */
  6268. CINDEX_LINKAGE
  6269. CXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc);
  6270.  
  6271. /**
  6272.  * Visitor invoked for each field found by a traversal.
  6273.  *
  6274.  * This visitor function will be invoked for each field found by
  6275.  * \c clang_Type_visitFields. Its first argument is the cursor being
  6276.  * visited, its second argument is the client data provided to
  6277.  * \c clang_Type_visitFields.
  6278.  *
  6279.  * The visitor should return one of the \c CXVisitorResult values
  6280.  * to direct \c clang_Type_visitFields.
  6281.  */
  6282. typedef enum CXVisitorResult (*CXFieldVisitor)(CXCursor C,
  6283.                                                CXClientData client_data);
  6284.  
  6285. /**
  6286.  * Visit the fields of a particular type.
  6287.  *
  6288.  * This function visits all the direct fields of the given cursor,
  6289.  * invoking the given \p visitor function with the cursors of each
  6290.  * visited field. The traversal may be ended prematurely, if
  6291.  * the visitor returns \c CXFieldVisit_Break.
  6292.  *
  6293.  * \param T the record type whose field may be visited.
  6294.  *
  6295.  * \param visitor the visitor function that will be invoked for each
  6296.  * field of \p T.
  6297.  *
  6298.  * \param client_data pointer data supplied by the client, which will
  6299.  * be passed to the visitor each time it is invoked.
  6300.  *
  6301.  * \returns a non-zero value if the traversal was terminated
  6302.  * prematurely by the visitor returning \c CXFieldVisit_Break.
  6303.  */
  6304. CINDEX_LINKAGE unsigned clang_Type_visitFields(CXType T, CXFieldVisitor visitor,
  6305.                                                CXClientData client_data);
  6306.  
  6307. /**
  6308.  * @}
  6309.  */
  6310.  
  6311. /**
  6312.  * @}
  6313.  */
  6314.  
  6315. LLVM_CLANG_C_EXTERN_C_END
  6316.  
  6317. #endif
  6318.