Index.h revision deb06bd3566e18f677e76bc435d478b033fe328b 
1/*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
2|*                                                                            *|
3|*                     The LLVM Compiler Infrastructure                       *|
4|*                                                                            *|
5|* This file is distributed under the University of Illinois Open Source      *|
6|* License. See LICENSE.TXT for details.                                      *|
7|*                                                                            *|
8|*===----------------------------------------------------------------------===*|
9|*                                                                            *|
10|* This header provides a public inferface to a Clang library for extracting  *|
11|* high-level symbol information from source files without exposing the full  *|
12|* Clang C++ API.                                                             *|
13|*                                                                            *|
14\*===----------------------------------------------------------------------===*/
15
16#ifndef CLANG_C_INDEX_H
17#define CLANG_C_INDEX_H
18
19#include <sys/stat.h>
20#include <time.h>
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26/* MSVC DLL import/export. */
27#ifdef _MSC_VER
28  #ifdef _CINDEX_LIB_
29    #define CINDEX_LINKAGE __declspec(dllexport)
30  #else
31    #define CINDEX_LINKAGE __declspec(dllimport)
32  #endif
33#else
34  #define CINDEX_LINKAGE
35#endif
36
37/*
38   Clang indeX abstractions. The backing store for the following API's will be
39   clangs AST file (currently based on PCH). AST files are created as follows:
40
41   "clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>".
42
43   Naming Conventions: To avoid namespace pollution, data types are prefixed
44   with "CX" and functions are prefixed with "clang_".
45*/
46typedef void *CXIndex;            /* An indexing instance. */
47
48typedef void *CXTranslationUnit;  /* A translation unit instance. */
49
50typedef void *CXFile;    /* A source file */
51typedef void *CXDecl;    /* A specific declaration within a translation unit. */
52typedef void *CXStmt;    /* A specific statement within a function/method */
53
54/* Cursors represent declarations, definitions, and references. */
55enum CXCursorKind {
56 /* Declarations */
57 CXCursor_FirstDecl                     = 1,
58 CXCursor_TypedefDecl                   = 1,
59 CXCursor_StructDecl                    = 2,
60 CXCursor_UnionDecl                     = 3,
61 CXCursor_ClassDecl                     = 4,
62 CXCursor_EnumDecl                      = 5,
63 CXCursor_FieldDecl                     = 6,
64 CXCursor_EnumConstantDecl              = 7,
65 CXCursor_FunctionDecl                  = 8,
66 CXCursor_VarDecl                       = 9,
67 CXCursor_ParmDecl                      = 10,
68 CXCursor_ObjCInterfaceDecl             = 11,
69 CXCursor_ObjCCategoryDecl              = 12,
70 CXCursor_ObjCProtocolDecl              = 13,
71 CXCursor_ObjCPropertyDecl              = 14,
72 CXCursor_ObjCIvarDecl                  = 15,
73 CXCursor_ObjCInstanceMethodDecl        = 16,
74 CXCursor_ObjCClassMethodDecl           = 17,
75 CXCursor_LastDecl                      = 17,
76
77 /* Definitions */
78 CXCursor_FirstDefn                     = 32,
79 CXCursor_FunctionDefn                  = 32,
80 CXCursor_ObjCClassDefn                 = 33,
81 CXCursor_ObjCCategoryDefn              = 34,
82 CXCursor_ObjCInstanceMethodDefn        = 35,
83 CXCursor_ObjCClassMethodDefn           = 36,
84 CXCursor_LastDefn                      = 36,
85
86 /* References */
87 CXCursor_FirstRef                      = 40, /* Decl references */
88 CXCursor_ObjCSuperClassRef             = 40,
89 CXCursor_ObjCProtocolRef               = 41,
90 CXCursor_ObjCClassRef                  = 42,
91
92 CXCursor_ObjCSelectorRef               = 43, /* Expression references */
93 CXCursor_ObjCIvarRef                   = 44,
94 CXCursor_VarRef                        = 45,
95 CXCursor_FunctionRef                   = 46,
96 CXCursor_EnumConstantRef               = 47,
97 CXCursor_MemberRef                     = 48,
98 CXCursor_LastRef                       = 48,
99
100 /* Error conditions */
101 CXCursor_FirstInvalid                  = 70,
102 CXCursor_InvalidFile                   = 70,
103 CXCursor_NoDeclFound                   = 71,
104 CXCursor_NotImplemented                = 72,
105 CXCursor_LastInvalid                   = 72
106};
107
108/**
109 * \brief Provides the contents of a file that has not yet been saved to disk.
110 *
111 * Each CXUnsavedFile instance provides the name of a file on the
112 * system along with the current contents of that file that have not
113 * yet been saved to disk.
114 */
115struct CXUnsavedFile {
116  /**
117   * \brief The file whose contents have not yet been saved.
118   *
119   * This file must already exist in the file system.
120   */
121  const char *Filename;
122
123  /**
124   * \brief A null-terminated buffer containing the unsaved contents
125   * of this file.
126   */
127  const char *Contents;
128
129  /**
130   * \brief The length of the unsaved contents of this buffer, not
131   * counting the NULL at the end of the buffer.
132   */
133  unsigned long Length;
134};
135
136/* A cursor into the CXTranslationUnit. */
137
138typedef struct {
139  enum CXCursorKind kind;
140  void *data[3];
141} CXCursor;
142
143/* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */
144typedef struct {
145  CXIndex index;
146  void *data;
147} CXEntity;
148
149/**
150 * For functions returning a string that might or might not need
151 * to be internally allocated and freed.
152 * Use clang_getCString to access the C string value.
153 * Use clang_disposeString to free the value.
154 * Treat it as an opaque type.
155 */
156typedef struct {
157  const char *Spelling;
158  /* A 1 value indicates the clang_ indexing API needed to allocate the string
159     (and it must be freed by clang_disposeString()). */
160  int MustFreeString;
161} CXString;
162
163/* Get C string pointer from a CXString. */
164CINDEX_LINKAGE const char *clang_getCString(CXString string);
165
166/* Free CXString. */
167CINDEX_LINKAGE void clang_disposeString(CXString string);
168
169/**
170 * \brief clang_createIndex() provides a shared context for creating
171 * translation units. It provides two options:
172 *
173 * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
174 * declarations (when loading any new translation units). A "local" declaration
175 * is one that belongs in the translation unit itself and not in a precompiled
176 * header that was used by the translation unit. If zero, all declarations
177 * will be enumerated.
178 *
179 * - displayDiagnostics: when non-zero, diagnostics will be output. If zero,
180 * diagnostics will be ignored.
181 *
182 * Here is an example:
183 *
184 *   // excludeDeclsFromPCH = 1, displayDiagnostics = 1
185 *   Idx = clang_createIndex(1, 1);
186 *
187 *   // IndexTest.pch was produced with the following command:
188 *   // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
189 *   TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
190 *
191 *   // This will load all the symbols from 'IndexTest.pch'
192 *   clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
193 *   clang_disposeTranslationUnit(TU);
194 *
195 *   // This will load all the symbols from 'IndexTest.c', excluding symbols
196 *   // from 'IndexTest.pch'.
197 *   char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 };
198 *   TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args);
199 *   clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
200 *   clang_disposeTranslationUnit(TU);
201 *
202 * This process of creating the 'pch', loading it separately, and using it (via
203 * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
204 * (which gives the indexer the same performance benefit as the compiler).
205 */
206CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
207                          int displayDiagnostics);
208CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
209CINDEX_LINKAGE CXString
210clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
211
212/*
213 * \brief Request that AST's be generated external for API calls which parse
214 * source code on the fly, e.g. \see createTranslationUnitFromSourceFile.
215 *
216 * Note: This is for debugging purposes only, and may be removed at a later
217 * date.
218 *
219 * \param index - The index to update.
220 * \param value - The new flag value.
221 */
222CINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index,
223                                                      int value);
224
225/*
226 * \brief Create a translation unit from an AST file (-emit-ast).
227 */
228CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(
229  CXIndex, const char *ast_filename
230);
231
232/**
233 * \brief Destroy the specified CXTranslationUnit object.
234 */
235CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
236
237/**
238 * \brief Return the CXTranslationUnit for a given source file and the provided
239 * command line arguments one would pass to the compiler.
240 *
241 * Note: The 'source_filename' argument is optional.  If the caller provides a
242 * NULL pointer, the name of the source file is expected to reside in the
243 * specified command line arguments.
244 *
245 * Note: When encountered in 'clang_command_line_args', the following options
246 * are ignored:
247 *
248 *   '-c'
249 *   '-emit-ast'
250 *   '-fsyntax-only'
251 *   '-o <output file>'  (both '-o' and '<output file>' are ignored)
252 *
253 *
254 * \param source_filename - The name of the source file to load, or NULL if the
255 * source file is included in clang_command_line_args.
256 */
257CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
258  CXIndex CIdx,
259  const char *source_filename,
260  int num_clang_command_line_args,
261  const char **clang_command_line_args
262);
263
264/*
265   Usage: clang_loadTranslationUnit(). Will load the toplevel declarations
266   within a translation unit, issuing a 'callback' for each one.
267
268   void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) {
269     if (clang_getCursorKind(C) == Cursor_Declaration) {
270       CXDecl D = clang_getCursorDecl(C);
271       if (clang_getDeclKind(D) == CXDecl_ObjC_interface)
272         printf("@interface %s in file %s on line %d column %d\n",
273                clang_getDeclSpelling(D), clang_getCursorSource(C),
274                clang_getCursorLine(C), clang_getCursorColumn(C));
275     }
276   }
277   static void usage {
278     clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames);
279  }
280*/
281typedef void *CXClientData;
282typedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor,
283                                          CXClientData);
284CINDEX_LINKAGE void clang_loadTranslationUnit(CXTranslationUnit,
285                                              CXTranslationUnitIterator,
286                                              CXClientData);
287
288/*
289   Usage: clang_loadDeclaration(). Will load the declaration, issuing a
290   'callback' for each declaration/reference within the respective declaration.
291
292   For interface declarations, this will index the super class, protocols,
293   ivars, methods, etc. For structure declarations, this will index the fields.
294   For functions, this will index the parameters (and body, for function
295   definitions), local declarations/references.
296
297   void getInterfaceDetails(CXDecl X, CXCursor C) {
298     switch (clang_getCursorKind(C)) {
299       case Cursor_ObjC_ClassRef:
300         CXDecl SuperClass = clang_getCursorDecl(C);
301       case Cursor_ObjC_ProtocolRef:
302         CXDecl AdoptsProtocol = clang_getCursorDecl(C);
303       case Cursor_Declaration:
304         CXDecl AnIvarOrMethod = clang_getCursorDecl(C);
305     }
306   }
307   static void usage() {
308     if (clang_getDeclKind(D) == CXDecl_ObjC_interface) {
309       clang_loadDeclaration(D, getInterfaceDetails);
310     }
311   }
312*/
313typedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData);
314
315CINDEX_LINKAGE void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData);
316
317/*
318 * CXFile Operations.
319 */
320CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile);
321CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
322
323/*
324 * CXEntity Operations.
325 */
326
327/* clang_getDeclaration() maps from a CXEntity to the matching CXDecl (if any)
328 *  in a specified translation unit. */
329CINDEX_LINKAGE CXDecl clang_getDeclaration(CXEntity, CXTranslationUnit);
330
331/*
332 * CXDecl Operations.
333 */
334CINDEX_LINKAGE CXCursor clang_getCursorFromDecl(CXDecl);
335CINDEX_LINKAGE CXEntity clang_getEntityFromDecl(CXIndex, CXDecl);
336CINDEX_LINKAGE CXString clang_getDeclSpelling(CXDecl);
337CINDEX_LINKAGE unsigned clang_getDeclLine(CXDecl);
338CINDEX_LINKAGE unsigned clang_getDeclColumn(CXDecl);
339CINDEX_LINKAGE CXString clang_getDeclUSR(CXDecl);
340CINDEX_LINKAGE const char *clang_getDeclSource(CXDecl); /* deprecate */
341CINDEX_LINKAGE CXFile clang_getDeclSourceFile(CXDecl);
342
343typedef struct CXSourceLineColumn {
344  unsigned line;
345  unsigned column;
346} CXSourceLineColumn;
347
348typedef struct CXDeclExtent {
349  CXSourceLineColumn begin;
350  CXSourceLineColumn end;
351} CXSourceExtent;
352
353/* clang_getDeclExtent() returns the physical extent of a declaration.  The
354 * beginning line/column pair points to the start of the first token in the
355 * declaration, and the ending line/column pair points to the last character in
356 * the last token of the declaration.
357 */
358CINDEX_LINKAGE CXSourceExtent clang_getDeclExtent(CXDecl);
359
360/*
361 * CXCursor Operations.
362 */
363/**
364   Usage: clang_getCursor() will translate a source/line/column position
365   into an AST cursor (to derive semantic information from the source code).
366 */
367CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit,
368                                        const char *source_name,
369                                        unsigned line, unsigned column);
370
371CINDEX_LINKAGE CXCursor clang_getNullCursor(void);
372
373CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
374CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
375CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
376CINDEX_LINKAGE unsigned clang_isDefinition(enum CXCursorKind);
377CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
378
379CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor);
380
381CINDEX_LINKAGE unsigned clang_getCursorLine(CXCursor);
382CINDEX_LINKAGE unsigned clang_getCursorColumn(CXCursor);
383CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
384CINDEX_LINKAGE const char *clang_getCursorSource(CXCursor); /* deprecate */
385CINDEX_LINKAGE CXFile clang_getCursorSourceFile(CXCursor);
386
387/* for debug/testing */
388CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind);
389CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor,
390                                          const char **startBuf,
391                                          const char **endBuf,
392                                          unsigned *startLine,
393                                          unsigned *startColumn,
394                                          unsigned *endLine,
395                                          unsigned *endColumn);
396
397/*
398 * If CXCursorKind == Cursor_Reference, then this will return the referenced
399 * declaration.
400 * If CXCursorKind == Cursor_Declaration, then this will return the declaration.
401 */
402CINDEX_LINKAGE CXDecl clang_getCursorDecl(CXCursor);
403
404/**
405 * \brief A semantic string that describes a code-completion result.
406 *
407 * A semantic string that describes the formatting of a code-completion
408 * result as a single "template" of text that should be inserted into the
409 * source buffer when a particular code-completion result is selected.
410 * Each semantic string is made up of some number of "chunks", each of which
411 * contains some text along with a description of what that text means, e.g.,
412 * the name of the entity being referenced, whether the text chunk is part of
413 * the template, or whether it is a "placeholder" that the user should replace
414 * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
415 * description of the different kinds of chunks.
416 */
417typedef void *CXCompletionString;
418
419/**
420 * \brief A single result of code completion.
421 */
422typedef struct {
423  /**
424   * \brief The kind of entity that this completion refers to.
425   *
426   * The cursor kind will be a macro, keyword, or a declaration (one of the
427   * *Decl cursor kinds), describing the entity that the completion is
428   * referring to.
429   *
430   * \todo In the future, we would like to provide a full cursor, to allow
431   * the client to extract additional information from declaration.
432   */
433  enum CXCursorKind CursorKind;
434
435  /**
436   * \brief The code-completion string that describes how to insert this
437   * code-completion result into the editing buffer.
438   */
439  CXCompletionString CompletionString;
440} CXCompletionResult;
441
442/**
443 * \brief Describes a single piece of text within a code-completion string.
444 *
445 * Each "chunk" within a code-completion string (\c CXCompletionString) is
446 * either a piece of text with a specific "kind" that describes how that text
447 * should be interpreted by the client or is another completion string.
448 */
449enum CXCompletionChunkKind {
450  /**
451   * \brief A code-completion string that describes "optional" text that
452   * could be a part of the template (but is not required).
453   *
454   * The Optional chunk is the only kind of chunk that has a code-completion
455   * string for its representation, which is accessible via
456   * \c clang_getCompletionChunkCompletionString(). The code-completion string
457   * describes an additional part of the template that is completely optional.
458   * For example, optional chunks can be used to describe the placeholders for
459   * arguments that match up with defaulted function parameters, e.g. given:
460   *
461   * \code
462   * void f(int x, float y = 3.14, double z = 2.71828);
463   * \endcode
464   *
465   * The code-completion string for this function would contain:
466   *   - a TypedText chunk for "f".
467   *   - a LeftParen chunk for "(".
468   *   - a Placeholder chunk for "int x"
469   *   - an Optional chunk containing the remaining defaulted arguments, e.g.,
470   *       - a Comma chunk for ","
471   *       - a Placeholder chunk for "float x"
472   *       - an Optional chunk containing the last defaulted argument:
473   *           - a Comma chunk for ","
474   *           - a Placeholder chunk for "double z"
475   *   - a RightParen chunk for ")"
476   *
477   * There are many ways two handle Optional chunks. Two simple approaches are:
478   *   - Completely ignore optional chunks, in which case the template for the
479   *     function "f" would only include the first parameter ("int x").
480   *   - Fully expand all optional chunks, in which case the template for the
481   *     function "f" would have all of the parameters.
482   */
483  CXCompletionChunk_Optional,
484  /**
485   * \brief Text that a user would be expected to type to get this
486   * code-completion result.
487   *
488   * There will be exactly one "typed text" chunk in a semantic string, which
489   * will typically provide the spelling of a keyword or the name of a
490   * declaration that could be used at the current code point. Clients are
491   * expected to filter the code-completion results based on the text in this
492   * chunk.
493   */
494  CXCompletionChunk_TypedText,
495  /**
496   * \brief Text that should be inserted as part of a code-completion result.
497   *
498   * A "text" chunk represents text that is part of the template to be
499   * inserted into user code should this particular code-completion result
500   * be selected.
501   */
502  CXCompletionChunk_Text,
503  /**
504   * \brief Placeholder text that should be replaced by the user.
505   *
506   * A "placeholder" chunk marks a place where the user should insert text
507   * into the code-completion template. For example, placeholders might mark
508   * the function parameters for a function declaration, to indicate that the
509   * user should provide arguments for each of those parameters. The actual
510   * text in a placeholder is a suggestion for the text to display before
511   * the user replaces the placeholder with real code.
512   */
513  CXCompletionChunk_Placeholder,
514  /**
515   * \brief Informative text that should be displayed but never inserted as
516   * part of the template.
517   *
518   * An "informative" chunk contains annotations that can be displayed to
519   * help the user decide whether a particular code-completion result is the
520   * right option, but which is not part of the actual template to be inserted
521   * by code completion.
522   */
523  CXCompletionChunk_Informative,
524  /**
525   * \brief Text that describes the current parameter when code-completion is
526   * referring to function call, message send, or template specialization.
527   *
528   * A "current parameter" chunk occurs when code-completion is providing
529   * information about a parameter corresponding to the argument at the
530   * code-completion point. For example, given a function
531   *
532   * \code
533   * int add(int x, int y);
534   * \endcode
535   *
536   * and the source code \c add(, where the code-completion point is after the
537   * "(", the code-completion string will contain a "current parameter" chunk
538   * for "int x", indicating that the current argument will initialize that
539   * parameter. After typing further, to \c add(17, (where the code-completion
540   * point is after the ","), the code-completion string will contain a
541   * "current paremeter" chunk to "int y".
542   */
543  CXCompletionChunk_CurrentParameter,
544  /**
545   * \brief A left parenthesis ('('), used to initiate a function call or
546   * signal the beginning of a function parameter list.
547   */
548  CXCompletionChunk_LeftParen,
549  /**
550   * \brief A right parenthesis (')'), used to finish a function call or
551   * signal the end of a function parameter list.
552   */
553  CXCompletionChunk_RightParen,
554  /**
555   * \brief A left bracket ('[').
556   */
557  CXCompletionChunk_LeftBracket,
558  /**
559   * \brief A right bracket (']').
560   */
561  CXCompletionChunk_RightBracket,
562  /**
563   * \brief A left brace ('{').
564   */
565  CXCompletionChunk_LeftBrace,
566  /**
567   * \brief A right brace ('}').
568   */
569  CXCompletionChunk_RightBrace,
570  /**
571   * \brief A left angle bracket ('<').
572   */
573  CXCompletionChunk_LeftAngle,
574  /**
575   * \brief A right angle bracket ('>').
576   */
577  CXCompletionChunk_RightAngle,
578  /**
579   * \brief A comma separator (',').
580   */
581  CXCompletionChunk_Comma,
582  /**
583   * \brief Text that specifies the result type of a given result.
584   *
585   * This special kind of informative chunk is not meant to be inserted into
586   * the text buffer. Rather, it is meant to illustrate the type that an
587   * expression using the given completion string would have.
588   */
589  CXCompletionChunk_ResultType,
590  /**
591   * \brief A colon (':').
592   */
593  CXCompletionChunk_Colon,
594  /**
595   * \brief A semicolon (';').
596   */
597  CXCompletionChunk_SemiColon,
598  /**
599   * \brief An '=' sign.
600   */
601  CXCompletionChunk_Equal,
602  /**
603   * Horizontal space (' ').
604   */
605  CXCompletionChunk_HorizontalSpace,
606  /**
607   * Vertical space ('\n'), after which it is generally a good idea to
608   * perform indentation.
609   */
610  CXCompletionChunk_VerticalSpace
611};
612
613/**
614 * \brief Determine the kind of a particular chunk within a completion string.
615 *
616 * \param completion_string the completion string to query.
617 *
618 * \param chunk_number the 0-based index of the chunk in the completion string.
619 *
620 * \returns the kind of the chunk at the index \c chunk_number.
621 */
622CINDEX_LINKAGE enum CXCompletionChunkKind
623clang_getCompletionChunkKind(CXCompletionString completion_string,
624                             unsigned chunk_number);
625
626/**
627 * \brief Retrieve the text associated with a particular chunk within a
628 * completion string.
629 *
630 * \param completion_string the completion string to query.
631 *
632 * \param chunk_number the 0-based index of the chunk in the completion string.
633 *
634 * \returns the text associated with the chunk at index \c chunk_number.
635 */
636CINDEX_LINKAGE const char *
637clang_getCompletionChunkText(CXCompletionString completion_string,
638                             unsigned chunk_number);
639
640/**
641 * \brief Retrieve the completion string associated with a particular chunk
642 * within a completion string.
643 *
644 * \param completion_string the completion string to query.
645 *
646 * \param chunk_number the 0-based index of the chunk in the completion string.
647 *
648 * \returns the completion string associated with the chunk at index
649 * \c chunk_number, or NULL if that chunk is not represented by a completion
650 * string.
651 */
652CINDEX_LINKAGE CXCompletionString
653clang_getCompletionChunkCompletionString(CXCompletionString completion_string,
654                                         unsigned chunk_number);
655
656/**
657 * \brief Retrieve the number of chunks in the given code-completion string.
658 */
659CINDEX_LINKAGE unsigned
660clang_getNumCompletionChunks(CXCompletionString completion_string);
661
662/**
663 * \brief Contains the results of code-completion.
664 *
665 * This data structure contains the results of code completion, as
666 * produced by \c clang_codeComplete. Its contents must be freed by
667 * \c clang_disposeCodeCompleteResults.
668 */
669typedef struct {
670  /**
671   * \brief The code-completion results.
672   */
673  CXCompletionResult *Results;
674
675  /**
676   * \brief The number of code-completion results stored in the
677   * \c Results array.
678   */
679  unsigned NumResults;
680} CXCodeCompleteResults;
681
682/**
683 * \brief Perform code completion at a given location in a source file.
684 *
685 * This function performs code completion at a particular file, line, and
686 * column within source code, providing results that suggest potential
687 * code snippets based on the context of the completion. The basic model
688 * for code completion is that Clang will parse a complete source file,
689 * performing syntax checking up to the location where code-completion has
690 * been requested. At that point, a special code-completion token is passed
691 * to the parser, which recognizes this token and determines, based on the
692 * current location in the C/Objective-C/C++ grammar and the state of
693 * semantic analysis, what completions to provide. These completions are
694 * returned via a new \c CXCodeCompleteResults structure.
695 *
696 * Code completion itself is meant to be triggered by the client when the
697 * user types punctuation characters or whitespace, at which point the
698 * code-completion location will coincide with the cursor. For example, if \c p
699 * is a pointer, code-completion might be triggered after the "-" and then
700 * after the ">" in \c p->. When the code-completion location is afer the ">",
701 * the completion results will provide, e.g., the members of the struct that
702 * "p" points to. The client is responsible for placing the cursor at the
703 * beginning of the token currently being typed, then filtering the results
704 * based on the contents of the token. For example, when code-completing for
705 * the expression \c p->get, the client should provide the location just after
706 * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
707 * client can filter the results based on the current token text ("get"), only
708 * showing those results that start with "get". The intent of this interface
709 * is to separate the relatively high-latency acquisition of code-completion
710 * results from the filtering of results on a per-character basis, which must
711 * have a lower latency.
712 *
713 * \param CIdx the \c CXIndex instance that will be used to perform code
714 * completion.
715 *
716 * \param source_filename the name of the source file that should be parsed to
717 * perform code-completion. This source file must be the same as or include the
718 * filename described by \p complete_filename, or no code-completion results
719 * will be produced.  NOTE: One can also specify NULL for this argument if the
720 * source file is included in command_line_args.
721 *
722 * \param num_command_line_args the number of command-line arguments stored in
723 * \p command_line_args.
724 *
725 * \param command_line_args the command-line arguments to pass to the Clang
726 * compiler to build the given source file. This should include all of the
727 * necessary include paths, language-dialect switches, precompiled header
728 * includes, etc., but should not include any information specific to
729 * code completion.
730 *
731 * \param num_unsaved_files the number of unsaved file entries in \p
732 * unsaved_files.
733 *
734 * \param unsaved_files the files that have not yet been saved to disk
735 * but may be required for code completion, including the contents of
736 * those files.
737 *
738 * \param complete_filename the name of the source file where code completion
739 * should be performed. In many cases, this name will be the same as the
740 * source filename. However, the completion filename may also be a file
741 * included by the source file, which is required when producing
742 * code-completion results for a header.
743 *
744 * \param complete_line the line at which code-completion should occur.
745 *
746 * \param complete_column the column at which code-completion should occur.
747 * Note that the column should point just after the syntactic construct that
748 * initiated code completion, and not in the middle of a lexical token.
749 *
750 * \returns if successful, a new CXCodeCompleteResults structure
751 * containing code-completion results, which should eventually be
752 * freed with \c clang_disposeCodeCompleteResults(). If code
753 * completion fails, returns NULL.
754 */
755CINDEX_LINKAGE
756CXCodeCompleteResults *clang_codeComplete(CXIndex CIdx,
757                                          const char *source_filename,
758                                          int num_command_line_args,
759                                          const char **command_line_args,
760                                          unsigned num_unsaved_files,
761                                          struct CXUnsavedFile *unsaved_files,
762                                          const char *complete_filename,
763                                          unsigned complete_line,
764                                          unsigned complete_column);
765
766/**
767 * \brief Free the given set of code-completion results.
768 */
769CINDEX_LINKAGE
770void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results);
771
772#ifdef __cplusplus
773}
774#endif
775#endif
776
777