diff options
Diffstat (limited to 'clang/include/clang-c/Index.h')
| -rw-r--r-- | clang/include/clang-c/Index.h | 125 |
1 files changed, 100 insertions, 25 deletions
diff --git a/clang/include/clang-c/Index.h b/clang/include/clang-c/Index.h index 0f152169002..ca34a8190a3 100644 --- a/clang/include/clang-c/Index.h +++ b/clang/include/clang-c/Index.h @@ -30,7 +30,7 @@ * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable. */ #define CINDEX_VERSION_MAJOR 0 -#define CINDEX_VERSION_MINOR 22 +#define CINDEX_VERSION_MINOR 23 #define CINDEX_VERSION_ENCODE(major, minor) ( \ ((major) * 10000) \ @@ -73,6 +73,43 @@ extern "C" { */ /** + * \brief Error codes returned by libclang routines. + * + * Zero (\c CXError_Success) is the only error code indicating success. Other + * error codes, including not yet assigned non-zero values, indicate errors. + */ +enum CXErrorCode { + /** + * \brief No error. + */ + CXError_Success = 0, + + /** + * \brief A generic error code, no further details are available. + * + * Errors of this kind can get their own specific error codes in future + * libclang versions. + */ + CXError_Failure = 1, + + /** + * \brief libclang crashed while performing the requested operation. + */ + CXError_Crashed = 2, + + /** + * \brief The function detected that the arguments violate the function + * contract. + */ + CXError_InvalidArguments = 3, + + /** + * \brief An AST deserialization error has occurred. + */ + CXError_ASTReadError = 4 +}; + +/** * \brief An "index" that consists of a set of translation units that would * typically be linked together into an executable or library. */ @@ -1076,10 +1113,27 @@ CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( struct CXUnsavedFile *unsaved_files); /** - * \brief Create a translation unit from an AST file (-emit-ast). + * \brief Same as \c clang_createTranslationUnit2, but returns + * the \c CXTranslationUnit instead of an error code. In case of an error this + * routine returns a \c NULL \c CXTranslationUnit, without further detailed + * error codes. */ -CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, - const char *ast_filename); +CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( + CXIndex CIdx, + const char *ast_filename); + +/** + * \brief Create a translation unit from an AST file (\c -emit-ast). + * + * \param[out] out_TU A non-NULL pointer to store the created + * \c CXTranslationUnit. + * + * \returns Zero on success, otherwise returns an error code. + */ +CINDEX_LINKAGE enum CXErrorCode clang_createTranslationUnit2( + CXIndex CIdx, + const char *ast_filename, + CXTranslationUnit *out_TU); /** * \brief Flags that control the creation of translation units. @@ -1193,7 +1247,22 @@ enum CXTranslationUnit_Flags { * set of optimizations enabled may change from one version to the next. */ CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); - + +/** + * \brief Same as \c clang_parseTranslationUnit2, but returns + * the \c CXTranslationUnit instead of an error code. In case of an error this + * routine returns a \c NULL \c CXTranslationUnit, without further detailed + * error codes. + */ +CINDEX_LINKAGE CXTranslationUnit +clang_parseTranslationUnit(CXIndex CIdx, + const char *source_filename, + const char *const *command_line_args, + int num_command_line_args, + struct CXUnsavedFile *unsaved_files, + unsigned num_unsaved_files, + unsigned options); + /** * \brief Parse the given source file and the translation unit corresponding * to that file. @@ -1208,7 +1277,7 @@ CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); * associated. * * \param source_filename The name of the source file to load, or NULL if the - * source file is included in \p command_line_args. + * source file is included in \c command_line_args. * * \param command_line_args The command-line arguments that would be * passed to the \c clang executable if it were being invoked out-of-process. @@ -1217,7 +1286,7 @@ CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'. * * \param num_command_line_args The number of command-line arguments in - * \p command_line_args. + * \c command_line_args. * * \param unsaved_files the files that have not yet been saved to disk * but may be required for parsing, including the contents of @@ -1232,18 +1301,22 @@ CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); * is managed but not its compilation. This should be a bitwise OR of the * CXTranslationUnit_XXX flags. * - * \returns A new translation unit describing the parsed code and containing - * any diagnostics produced by the compiler. If there is a failure from which - * the compiler cannot recover, returns NULL. + * \param[out] out_TU A non-NULL pointer to store the created + * \c CXTranslationUnit, describing the parsed code and containing any + * diagnostics produced by the compiler. + * + * \returns Zero on success, otherwise returns an error code. */ -CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx, - const char *source_filename, - const char * const *command_line_args, - int num_command_line_args, - struct CXUnsavedFile *unsaved_files, - unsigned num_unsaved_files, - unsigned options); - +CINDEX_LINKAGE enum CXErrorCode +clang_parseTranslationUnit2(CXIndex CIdx, + const char *source_filename, + const char *const *command_line_args, + int num_command_line_args, + struct CXUnsavedFile *unsaved_files, + unsigned num_unsaved_files, + unsigned options, + CXTranslationUnit *out_TU); + /** * \brief Flags that control how translation units are saved. * @@ -1395,10 +1468,11 @@ CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU); * The function \c clang_defaultReparseOptions() produces a default set of * options recommended for most uses, based on the translation unit. * - * \returns 0 if the sources could be reparsed. A non-zero value will be + * \returns 0 if the sources could be reparsed. A non-zero error code will be * returned if reparsing was impossible, such that the translation unit is - * invalid. In such cases, the only valid call for \p TU is - * \c clang_disposeTranslationUnit(TU). + * invalid. In such cases, the only valid call for \c TU is + * \c clang_disposeTranslationUnit(TU). The error codes returned by this + * routine are described by the \c CXErrorCode enum. */ CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU, unsigned num_unsaved_files, @@ -5789,11 +5863,12 @@ typedef enum { * \param index_options A bitmask of options that affects how indexing is * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags. * - * \param out_TU [out] pointer to store a CXTranslationUnit that can be reused - * after indexing is finished. Set to NULL if you do not require it. + * \param[out] out_TU pointer to store a \c CXTranslationUnit that can be + * reused after indexing is finished. Set to \c NULL if you do not require it. * - * \returns If there is a failure from which the there is no recovery, returns - * non-zero, otherwise returns 0. + * \returns 0 on success or if there were errors from which the compiler could + * recover. If there is a failure from which the there is no recovery, returns + * a non-zero \c CXErrorCode. * * The rest of the parameters are the same as #clang_parseTranslationUnit. */ |
