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