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