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