зеркало из https://github.com/microsoft/clang-1.git
734 строки
28 KiB
C
734 строки
28 KiB
C
/*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
|
|
|* *|
|
|
|* The LLVM Compiler Infrastructure *|
|
|
|* *|
|
|
|* This file is distributed under the University of Illinois Open Source *|
|
|
|* License. See LICENSE.TXT for details. *|
|
|
|* *|
|
|
|*===----------------------------------------------------------------------===*|
|
|
|* *|
|
|
|* This header provides a public inferface to a Clang library for extracting *|
|
|
|* high-level symbol information from source files without exposing the full *|
|
|
|* Clang C++ API. *|
|
|
|* *|
|
|
\*===----------------------------------------------------------------------===*/
|
|
|
|
#ifndef CLANG_C_INDEX_H
|
|
#define CLANG_C_INDEX_H
|
|
|
|
#include <sys/stat.h>
|
|
#include <time.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* MSVC DLL import/export. */
|
|
#ifdef _MSC_VER
|
|
#ifdef _CINDEX_LIB_
|
|
#define CINDEX_LINKAGE __declspec(dllexport)
|
|
#else
|
|
#define CINDEX_LINKAGE __declspec(dllimport)
|
|
#endif
|
|
#else
|
|
#define CINDEX_LINKAGE
|
|
#endif
|
|
|
|
/*
|
|
Clang indeX abstractions. The backing store for the following API's will be
|
|
clangs AST file (currently based on PCH). AST files are created as follows:
|
|
|
|
"clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>".
|
|
|
|
Naming Conventions: To avoid namespace pollution, data types are prefixed
|
|
with "CX" and functions are prefixed with "clang_".
|
|
*/
|
|
typedef void *CXIndex; /* An indexing instance. */
|
|
|
|
typedef void *CXTranslationUnit; /* A translation unit instance. */
|
|
|
|
typedef void *CXFile; /* A source file */
|
|
typedef void *CXDecl; /* A specific declaration within a translation unit. */
|
|
typedef void *CXStmt; /* A specific statement within a function/method */
|
|
|
|
/* Cursors represent declarations, definitions, and references. */
|
|
enum CXCursorKind {
|
|
/* Declarations */
|
|
CXCursor_FirstDecl = 1,
|
|
CXCursor_TypedefDecl = 2,
|
|
CXCursor_StructDecl = 3,
|
|
CXCursor_UnionDecl = 4,
|
|
CXCursor_ClassDecl = 5,
|
|
CXCursor_EnumDecl = 6,
|
|
CXCursor_FieldDecl = 7,
|
|
CXCursor_EnumConstantDecl = 8,
|
|
CXCursor_FunctionDecl = 9,
|
|
CXCursor_VarDecl = 10,
|
|
CXCursor_ParmDecl = 11,
|
|
CXCursor_ObjCInterfaceDecl = 12,
|
|
CXCursor_ObjCCategoryDecl = 13,
|
|
CXCursor_ObjCProtocolDecl = 14,
|
|
CXCursor_ObjCPropertyDecl = 15,
|
|
CXCursor_ObjCIvarDecl = 16,
|
|
CXCursor_ObjCInstanceMethodDecl = 17,
|
|
CXCursor_ObjCClassMethodDecl = 18,
|
|
CXCursor_LastDecl = 18,
|
|
|
|
/* Definitions */
|
|
CXCursor_FirstDefn = 32,
|
|
CXCursor_FunctionDefn = 32,
|
|
CXCursor_ObjCClassDefn = 33,
|
|
CXCursor_ObjCCategoryDefn = 34,
|
|
CXCursor_ObjCInstanceMethodDefn = 35,
|
|
CXCursor_ObjCClassMethodDefn = 36,
|
|
CXCursor_LastDefn = 36,
|
|
|
|
/* References */
|
|
CXCursor_FirstRef = 40, /* Decl references */
|
|
CXCursor_ObjCSuperClassRef = 40,
|
|
CXCursor_ObjCProtocolRef = 41,
|
|
CXCursor_ObjCClassRef = 42,
|
|
|
|
CXCursor_ObjCSelectorRef = 43, /* Expression references */
|
|
CXCursor_ObjCIvarRef = 44,
|
|
CXCursor_VarRef = 45,
|
|
CXCursor_FunctionRef = 46,
|
|
CXCursor_EnumConstantRef = 47,
|
|
CXCursor_MemberRef = 48,
|
|
CXCursor_LastRef = 48,
|
|
|
|
/* Error conditions */
|
|
CXCursor_FirstInvalid = 70,
|
|
CXCursor_InvalidFile = 70,
|
|
CXCursor_NoDeclFound = 71,
|
|
CXCursor_NotImplemented = 72,
|
|
CXCursor_LastInvalid = 72
|
|
};
|
|
|
|
/**
|
|
* \brief Provides the contents of a file that has not yet been saved to disk.
|
|
*
|
|
* Each CXUnsavedFile instance provides the name of a file on the
|
|
* system along with the current contents of that file that have not
|
|
* yet been saved to disk.
|
|
*/
|
|
struct CXUnsavedFile {
|
|
/**
|
|
* \brief The file whose contents have not yet been saved.
|
|
*
|
|
* This file must already exist in the file system.
|
|
*/
|
|
const char *Filename;
|
|
|
|
/**
|
|
* \brief A null-terminated buffer containing the unsaved contents
|
|
* of this file.
|
|
*/
|
|
const char *Contents;
|
|
|
|
/**
|
|
* \brief The length of the unsaved contents of this buffer, not
|
|
* counting the NULL at the end of the buffer.
|
|
*/
|
|
unsigned long Length;
|
|
};
|
|
|
|
/* A cursor into the CXTranslationUnit. */
|
|
|
|
typedef struct {
|
|
enum CXCursorKind kind;
|
|
CXDecl decl;
|
|
CXStmt stmt; /* expression reference */
|
|
} CXCursor;
|
|
|
|
/* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */
|
|
typedef void *CXEntity;
|
|
|
|
/**
|
|
* For functions returning a string that might or might not need
|
|
* to be internally allocated and freed.
|
|
* Use clang_getCString to access the C string value.
|
|
* Use clang_disposeString to free the value.
|
|
* Treat it as an opaque type.
|
|
*/
|
|
typedef struct {
|
|
const char *Spelling;
|
|
/* A 1 value indicates the clang_ indexing API needed to allocate the string
|
|
(and it must be freed by clang_disposeString()). */
|
|
int MustFreeString;
|
|
} CXString;
|
|
|
|
/* Get C string pointer from a CXString. */
|
|
CINDEX_LINKAGE const char *clang_getCString(CXString string);
|
|
|
|
/* Free CXString. */
|
|
CINDEX_LINKAGE void clang_disposeString(CXString string);
|
|
|
|
/**
|
|
* \brief clang_createIndex() provides a shared context for creating
|
|
* translation units. It provides two options:
|
|
*
|
|
* - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
|
|
* declarations (when loading any new translation units). A "local" declaration
|
|
* is one that belongs in the translation unit itself and not in a precompiled
|
|
* header that was used by the translation unit. If zero, all declarations
|
|
* will be enumerated.
|
|
*
|
|
* - displayDiagnostics: when non-zero, diagnostics will be output. If zero,
|
|
* diagnostics will be ignored.
|
|
*
|
|
* Here is an example:
|
|
*
|
|
* // excludeDeclsFromPCH = 1, displayDiagnostics = 1
|
|
* Idx = clang_createIndex(1, 1);
|
|
*
|
|
* // IndexTest.pch was produced with the following command:
|
|
* // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
|
|
* TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
|
|
*
|
|
* // This will load all the symbols from 'IndexTest.pch'
|
|
* clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
|
|
* clang_disposeTranslationUnit(TU);
|
|
*
|
|
* // This will load all the symbols from 'IndexTest.c', excluding symbols
|
|
* // from 'IndexTest.pch'.
|
|
* char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 };
|
|
* TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args);
|
|
* clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
|
|
* clang_disposeTranslationUnit(TU);
|
|
*
|
|
* This process of creating the 'pch', loading it separately, and using it (via
|
|
* -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
|
|
* (which gives the indexer the same performance benefit as the compiler).
|
|
*/
|
|
CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
|
|
int displayDiagnostics);
|
|
CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
|
|
CINDEX_LINKAGE CXString
|
|
clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
|
|
|
|
/*
|
|
* \brief Request that AST's be generated external for API calls which parse
|
|
* source code on the fly, e.g. \see createTranslationUnitFromSourceFile.
|
|
*
|
|
* Note: This is for debugging purposes only, and may be removed at a later
|
|
* date.
|
|
*
|
|
* \param index - The index to update.
|
|
* \param value - The new flag value.
|
|
*/
|
|
CINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index,
|
|
int value);
|
|
|
|
/*
|
|
* \brief Create a translation unit from an AST file (-emit-ast).
|
|
*/
|
|
CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(
|
|
CXIndex, const char *ast_filename
|
|
);
|
|
|
|
/**
|
|
* \brief Destroy the specified CXTranslationUnit object.
|
|
*/
|
|
CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
|
|
|
|
/**
|
|
* \brief Return the CXTranslationUnit for a given source file and the provided
|
|
* command line arguments one would pass to the compiler.
|
|
*
|
|
* Note: The 'source_filename' argument is optional. If the caller provides a
|
|
* NULL pointer, the name of the source file is expected to reside in the
|
|
* specified command line arguments.
|
|
*
|
|
* Note: When encountered in 'clang_command_line_args', the following options
|
|
* are ignored:
|
|
*
|
|
* '-c'
|
|
* '-emit-ast'
|
|
* '-fsyntax-only'
|
|
* '-o <output file>' (both '-o' and '<output file>' are ignored)
|
|
*
|
|
*
|
|
* \param source_filename - The name of the source file to load, or NULL if the
|
|
* source file is included in clang_command_line_args.
|
|
*/
|
|
CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
|
|
CXIndex CIdx,
|
|
const char *source_filename,
|
|
int num_clang_command_line_args,
|
|
const char **clang_command_line_args
|
|
);
|
|
|
|
/*
|
|
Usage: clang_loadTranslationUnit(). Will load the toplevel declarations
|
|
within a translation unit, issuing a 'callback' for each one.
|
|
|
|
void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) {
|
|
if (clang_getCursorKind(C) == Cursor_Declaration) {
|
|
CXDecl D = clang_getCursorDecl(C);
|
|
if (clang_getDeclKind(D) == CXDecl_ObjC_interface)
|
|
printf("@interface %s in file %s on line %d column %d\n",
|
|
clang_getDeclSpelling(D), clang_getCursorSource(C),
|
|
clang_getCursorLine(C), clang_getCursorColumn(C));
|
|
}
|
|
}
|
|
static void usage {
|
|
clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames);
|
|
}
|
|
*/
|
|
typedef void *CXClientData;
|
|
typedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor,
|
|
CXClientData);
|
|
CINDEX_LINKAGE void clang_loadTranslationUnit(CXTranslationUnit,
|
|
CXTranslationUnitIterator,
|
|
CXClientData);
|
|
|
|
/*
|
|
Usage: clang_loadDeclaration(). Will load the declaration, issuing a
|
|
'callback' for each declaration/reference within the respective declaration.
|
|
|
|
For interface declarations, this will index the super class, protocols,
|
|
ivars, methods, etc. For structure declarations, this will index the fields.
|
|
For functions, this will index the parameters (and body, for function
|
|
definitions), local declarations/references.
|
|
|
|
void getInterfaceDetails(CXDecl X, CXCursor C) {
|
|
switch (clang_getCursorKind(C)) {
|
|
case Cursor_ObjC_ClassRef:
|
|
CXDecl SuperClass = clang_getCursorDecl(C);
|
|
case Cursor_ObjC_ProtocolRef:
|
|
CXDecl AdoptsProtocol = clang_getCursorDecl(C);
|
|
case Cursor_Declaration:
|
|
CXDecl AnIvarOrMethod = clang_getCursorDecl(C);
|
|
}
|
|
}
|
|
static void usage() {
|
|
if (clang_getDeclKind(D) == CXDecl_ObjC_interface) {
|
|
clang_loadDeclaration(D, getInterfaceDetails);
|
|
}
|
|
}
|
|
*/
|
|
typedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData);
|
|
|
|
CINDEX_LINKAGE void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData);
|
|
|
|
/*
|
|
* CXFile Operations.
|
|
*/
|
|
CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile);
|
|
CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
|
|
|
|
/*
|
|
* CXEntity Operations.
|
|
*/
|
|
CINDEX_LINKAGE const char *clang_getDeclarationName(CXEntity);
|
|
CINDEX_LINKAGE const char *clang_getURI(CXEntity);
|
|
CINDEX_LINKAGE CXEntity clang_getEntity(const char *URI);
|
|
/*
|
|
* CXDecl Operations.
|
|
*/
|
|
CINDEX_LINKAGE CXCursor clang_getCursorFromDecl(CXDecl);
|
|
CINDEX_LINKAGE CXEntity clang_getEntityFromDecl(CXDecl);
|
|
CINDEX_LINKAGE CXString clang_getDeclSpelling(CXDecl);
|
|
CINDEX_LINKAGE unsigned clang_getDeclLine(CXDecl);
|
|
CINDEX_LINKAGE unsigned clang_getDeclColumn(CXDecl);
|
|
CINDEX_LINKAGE const char *clang_getDeclSource(CXDecl); /* deprecate */
|
|
CINDEX_LINKAGE CXFile clang_getDeclSourceFile(CXDecl);
|
|
|
|
/*
|
|
* CXCursor Operations.
|
|
*/
|
|
/**
|
|
Usage: clang_getCursor() will translate a source/line/column position
|
|
into an AST cursor (to derive semantic information from the source code).
|
|
*/
|
|
CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit,
|
|
const char *source_name,
|
|
unsigned line, unsigned column);
|
|
|
|
CINDEX_LINKAGE CXCursor clang_getNullCursor(void);
|
|
|
|
CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
|
|
CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
|
|
CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
|
|
CINDEX_LINKAGE unsigned clang_isDefinition(enum CXCursorKind);
|
|
CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
|
|
|
|
CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor);
|
|
|
|
CINDEX_LINKAGE unsigned clang_getCursorLine(CXCursor);
|
|
CINDEX_LINKAGE unsigned clang_getCursorColumn(CXCursor);
|
|
CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
|
|
CINDEX_LINKAGE const char *clang_getCursorSource(CXCursor); /* deprecate */
|
|
CINDEX_LINKAGE CXFile clang_getCursorSourceFile(CXCursor);
|
|
|
|
/* for debug/testing */
|
|
CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind);
|
|
CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor,
|
|
const char **startBuf,
|
|
const char **endBuf,
|
|
unsigned *startLine,
|
|
unsigned *startColumn,
|
|
unsigned *endLine,
|
|
unsigned *endColumn);
|
|
|
|
/*
|
|
* If CXCursorKind == Cursor_Reference, then this will return the referenced
|
|
* declaration.
|
|
* If CXCursorKind == Cursor_Declaration, then this will return the declaration.
|
|
*/
|
|
CINDEX_LINKAGE CXDecl clang_getCursorDecl(CXCursor);
|
|
|
|
/**
|
|
* \brief A semantic string that describes a code-completion result.
|
|
*
|
|
* A semantic string that describes the formatting of a code-completion
|
|
* result as a single "template" of text that should be inserted into the
|
|
* source buffer when a particular code-completion result is selected.
|
|
* Each semantic string is made up of some number of "chunks", each of which
|
|
* contains some text along with a description of what that text means, e.g.,
|
|
* the name of the entity being referenced, whether the text chunk is part of
|
|
* the template, or whether it is a "placeholder" that the user should replace
|
|
* with actual code,of a specific kind. See \c CXCompletionChunkKind for a
|
|
* description of the different kinds of chunks.
|
|
*/
|
|
typedef void *CXCompletionString;
|
|
|
|
/**
|
|
* \brief A single result of code completion.
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
* \brief The kind of entity that this completion refers to.
|
|
*
|
|
* The cursor kind will be a macro, keyword, or a declaration (one of the
|
|
* *Decl cursor kinds), describing the entity that the completion is
|
|
* referring to.
|
|
*
|
|
* \todo In the future, we would like to provide a full cursor, to allow
|
|
* the client to extract additional information from declaration.
|
|
*/
|
|
enum CXCursorKind CursorKind;
|
|
|
|
/**
|
|
* \brief The code-completion string that describes how to insert this
|
|
* code-completion result into the editing buffer.
|
|
*/
|
|
CXCompletionString CompletionString;
|
|
} CXCompletionResult;
|
|
|
|
/**
|
|
* \brief Describes a single piece of text within a code-completion string.
|
|
*
|
|
* Each "chunk" within a code-completion string (\c CXCompletionString) is
|
|
* either a piece of text with a specific "kind" that describes how that text
|
|
* should be interpreted by the client or is another completion string.
|
|
*/
|
|
enum CXCompletionChunkKind {
|
|
/**
|
|
* \brief A code-completion string that describes "optional" text that
|
|
* could be a part of the template (but is not required).
|
|
*
|
|
* The Optional chunk is the only kind of chunk that has a code-completion
|
|
* string for its representation, which is accessible via
|
|
* \c clang_getCompletionChunkCompletionString(). The code-completion string
|
|
* describes an additional part of the template that is completely optional.
|
|
* For example, optional chunks can be used to describe the placeholders for
|
|
* arguments that match up with defaulted function parameters, e.g. given:
|
|
*
|
|
* \code
|
|
* void f(int x, float y = 3.14, double z = 2.71828);
|
|
* \endcode
|
|
*
|
|
* The code-completion string for this function would contain:
|
|
* - a TypedText chunk for "f".
|
|
* - a LeftParen chunk for "(".
|
|
* - a Placeholder chunk for "int x"
|
|
* - an Optional chunk containing the remaining defaulted arguments, e.g.,
|
|
* - a Comma chunk for ","
|
|
* - a Placeholder chunk for "float x"
|
|
* - an Optional chunk containing the last defaulted argument:
|
|
* - a Comma chunk for ","
|
|
* - a Placeholder chunk for "double z"
|
|
* - a RightParen chunk for ")"
|
|
*
|
|
* There are many ways two handle Optional chunks. Two simple approaches are:
|
|
* - Completely ignore optional chunks, in which case the template for the
|
|
* function "f" would only include the first parameter ("int x").
|
|
* - Fully expand all optional chunks, in which case the template for the
|
|
* function "f" would have all of the parameters.
|
|
*/
|
|
CXCompletionChunk_Optional,
|
|
/**
|
|
* \brief Text that a user would be expected to type to get this
|
|
* code-completion result.
|
|
*
|
|
* There will be exactly one "typed text" chunk in a semantic string, which
|
|
* will typically provide the spelling of a keyword or the name of a
|
|
* declaration that could be used at the current code point. Clients are
|
|
* expected to filter the code-completion results based on the text in this
|
|
* chunk.
|
|
*/
|
|
CXCompletionChunk_TypedText,
|
|
/**
|
|
* \brief Text that should be inserted as part of a code-completion result.
|
|
*
|
|
* A "text" chunk represents text that is part of the template to be
|
|
* inserted into user code should this particular code-completion result
|
|
* be selected.
|
|
*/
|
|
CXCompletionChunk_Text,
|
|
/**
|
|
* \brief Placeholder text that should be replaced by the user.
|
|
*
|
|
* A "placeholder" chunk marks a place where the user should insert text
|
|
* into the code-completion template. For example, placeholders might mark
|
|
* the function parameters for a function declaration, to indicate that the
|
|
* user should provide arguments for each of those parameters. The actual
|
|
* text in a placeholder is a suggestion for the text to display before
|
|
* the user replaces the placeholder with real code.
|
|
*/
|
|
CXCompletionChunk_Placeholder,
|
|
/**
|
|
* \brief Informative text that should be displayed but never inserted as
|
|
* part of the template.
|
|
*
|
|
* An "informative" chunk contains annotations that can be displayed to
|
|
* help the user decide whether a particular code-completion result is the
|
|
* right option, but which is not part of the actual template to be inserted
|
|
* by code completion.
|
|
*/
|
|
CXCompletionChunk_Informative,
|
|
/**
|
|
* \brief Text that describes the current parameter when code-completion is
|
|
* referring to function call, message send, or template specialization.
|
|
*
|
|
* A "current parameter" chunk occurs when code-completion is providing
|
|
* information about a parameter corresponding to the argument at the
|
|
* code-completion point. For example, given a function
|
|
*
|
|
* \code
|
|
* int add(int x, int y);
|
|
* \endcode
|
|
*
|
|
* and the source code \c add(, where the code-completion point is after the
|
|
* "(", the code-completion string will contain a "current parameter" chunk
|
|
* for "int x", indicating that the current argument will initialize that
|
|
* parameter. After typing further, to \c add(17, (where the code-completion
|
|
* point is after the ","), the code-completion string will contain a
|
|
* "current paremeter" chunk to "int y".
|
|
*/
|
|
CXCompletionChunk_CurrentParameter,
|
|
/**
|
|
* \brief A left parenthesis ('('), used to initiate a function call or
|
|
* signal the beginning of a function parameter list.
|
|
*/
|
|
CXCompletionChunk_LeftParen,
|
|
/**
|
|
* \brief A right parenthesis (')'), used to finish a function call or
|
|
* signal the end of a function parameter list.
|
|
*/
|
|
CXCompletionChunk_RightParen,
|
|
/**
|
|
* \brief A left bracket ('[').
|
|
*/
|
|
CXCompletionChunk_LeftBracket,
|
|
/**
|
|
* \brief A right bracket (']').
|
|
*/
|
|
CXCompletionChunk_RightBracket,
|
|
/**
|
|
* \brief A left brace ('{').
|
|
*/
|
|
CXCompletionChunk_LeftBrace,
|
|
/**
|
|
* \brief A right brace ('}').
|
|
*/
|
|
CXCompletionChunk_RightBrace,
|
|
/**
|
|
* \brief A left angle bracket ('<').
|
|
*/
|
|
CXCompletionChunk_LeftAngle,
|
|
/**
|
|
* \brief A right angle bracket ('>').
|
|
*/
|
|
CXCompletionChunk_RightAngle,
|
|
/**
|
|
* \brief A comma separator (',').
|
|
*/
|
|
CXCompletionChunk_Comma,
|
|
/**
|
|
* \brief Text that specifies the result type of a given result.
|
|
*
|
|
* This special kind of informative chunk is not meant to be inserted into
|
|
* the text buffer. Rather, it is meant to illustrate the type that an
|
|
* expression using the given completion string would have.
|
|
*/
|
|
CXCompletionChunk_ResultType
|
|
};
|
|
|
|
/**
|
|
* \brief Determine the kind of a particular chunk within a completion string.
|
|
*
|
|
* \param completion_string the completion string to query.
|
|
*
|
|
* \param chunk_number the 0-based index of the chunk in the completion string.
|
|
*
|
|
* \returns the kind of the chunk at the index \c chunk_number.
|
|
*/
|
|
CINDEX_LINKAGE enum CXCompletionChunkKind
|
|
clang_getCompletionChunkKind(CXCompletionString completion_string,
|
|
unsigned chunk_number);
|
|
|
|
/**
|
|
* \brief Retrieve the text associated with a particular chunk within a
|
|
* completion string.
|
|
*
|
|
* \param completion_string the completion string to query.
|
|
*
|
|
* \param chunk_number the 0-based index of the chunk in the completion string.
|
|
*
|
|
* \returns the text associated with the chunk at index \c chunk_number.
|
|
*/
|
|
CINDEX_LINKAGE const char *
|
|
clang_getCompletionChunkText(CXCompletionString completion_string,
|
|
unsigned chunk_number);
|
|
|
|
/**
|
|
* \brief Retrieve the completion string associated with a particular chunk
|
|
* within a completion string.
|
|
*
|
|
* \param completion_string the completion string to query.
|
|
*
|
|
* \param chunk_number the 0-based index of the chunk in the completion string.
|
|
*
|
|
* \returns the completion string associated with the chunk at index
|
|
* \c chunk_number, or NULL if that chunk is not represented by a completion
|
|
* string.
|
|
*/
|
|
CINDEX_LINKAGE CXCompletionString
|
|
clang_getCompletionChunkCompletionString(CXCompletionString completion_string,
|
|
unsigned chunk_number);
|
|
|
|
/**
|
|
* \brief Retrieve the number of chunks in the given code-completion string.
|
|
*/
|
|
CINDEX_LINKAGE unsigned
|
|
clang_getNumCompletionChunks(CXCompletionString completion_string);
|
|
|
|
/**
|
|
* \brief Contains the results of code-completion.
|
|
*
|
|
* This data structure contains the results of code completion, as
|
|
* produced by \c clang_codeComplete. Its contents must be freed by
|
|
* \c clang_disposeCodeCompleteResults.
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
* \brief The code-completion results.
|
|
*/
|
|
CXCompletionResult *Results;
|
|
|
|
/**
|
|
* \brief The number of code-completion results stored in the
|
|
* \c Results array.
|
|
*/
|
|
unsigned NumResults;
|
|
} CXCodeCompleteResults;
|
|
|
|
/**
|
|
* \brief Perform code completion at a given location in a source file.
|
|
*
|
|
* This function performs code completion at a particular file, line, and
|
|
* column within source code, providing results that suggest potential
|
|
* code snippets based on the context of the completion. The basic model
|
|
* for code completion is that Clang will parse a complete source file,
|
|
* performing syntax checking up to the location where code-completion has
|
|
* been requested. At that point, a special code-completion token is passed
|
|
* to the parser, which recognizes this token and determines, based on the
|
|
* current location in the C/Objective-C/C++ grammar and the state of
|
|
* semantic analysis, what completions to provide. These completions are
|
|
* returned via a new \c CXCodeCompleteResults structure.
|
|
*
|
|
* Code completion itself is meant to be triggered by the client when the
|
|
* user types punctuation characters or whitespace, at which point the
|
|
* code-completion location will coincide with the cursor. For example, if \c p
|
|
* is a pointer, code-completion might be triggered after the "-" and then
|
|
* after the ">" in \c p->. When the code-completion location is afer the ">",
|
|
* the completion results will provide, e.g., the members of the struct that
|
|
* "p" points to. The client is responsible for placing the cursor at the
|
|
* beginning of the token currently being typed, then filtering the results
|
|
* based on the contents of the token. For example, when code-completing for
|
|
* the expression \c p->get, the client should provide the location just after
|
|
* the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
|
|
* client can filter the results based on the current token text ("get"), only
|
|
* showing those results that start with "get". The intent of this interface
|
|
* is to separate the relatively high-latency acquisition of code-completion
|
|
* results from the filtering of results on a per-character basis, which must
|
|
* have a lower latency.
|
|
*
|
|
* \param CIdx the \c CXIndex instance that will be used to perform code
|
|
* completion.
|
|
*
|
|
* \param source_filename the name of the source file that should be parsed to
|
|
* perform code-completion. This source file must be the same as or include the
|
|
* filename described by \p complete_filename, or no code-completion results
|
|
* will be produced. NOTE: One can also specify NULL for this argument if the
|
|
* source file is included in command_line_args.
|
|
*
|
|
* \param num_command_line_args the number of command-line arguments stored in
|
|
* \p command_line_args.
|
|
*
|
|
* \param command_line_args the command-line arguments to pass to the Clang
|
|
* compiler to build the given source file. This should include all of the
|
|
* necessary include paths, language-dialect switches, precompiled header
|
|
* includes, etc., but should not include any information specific to
|
|
* code completion.
|
|
*
|
|
* \param num_unsaved_files the number of unsaved file entries in \p
|
|
* unsaved_files.
|
|
*
|
|
* \param unsaved_files the files that have not yet been saved to disk
|
|
* but may be required for code completion, including the contents of
|
|
* those files.
|
|
*
|
|
* \param complete_filename the name of the source file where code completion
|
|
* should be performed. In many cases, this name will be the same as the
|
|
* source filename. However, the completion filename may also be a file
|
|
* included by the source file, which is required when producing
|
|
* code-completion results for a header.
|
|
*
|
|
* \param complete_line the line at which code-completion should occur.
|
|
*
|
|
* \param complete_column the column at which code-completion should occur.
|
|
* Note that the column should point just after the syntactic construct that
|
|
* initiated code completion, and not in the middle of a lexical token.
|
|
*
|
|
* \returns if successful, a new CXCodeCompleteResults structure
|
|
* containing code-completion results, which should eventually be
|
|
* freed with \c clang_disposeCodeCompleteResults(). If code
|
|
* completion fails, returns NULL.
|
|
*/
|
|
CINDEX_LINKAGE
|
|
CXCodeCompleteResults *clang_codeComplete(CXIndex CIdx,
|
|
const char *source_filename,
|
|
int num_command_line_args,
|
|
const char **command_line_args,
|
|
unsigned num_unsaved_files,
|
|
struct CXUnsavedFile *unsaved_files,
|
|
const char *complete_filename,
|
|
unsigned complete_line,
|
|
unsigned complete_column);
|
|
|
|
/**
|
|
* \brief Free the given set of code-completion results.
|
|
*/
|
|
CINDEX_LINKAGE
|
|
void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
#endif
|
|
|