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