Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

/*===-- clang-c/CXDiagnostic.h - C Index Diagnostics --------------*- C -*-===*\

|*                                                                            *|

|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|

|* Exceptions.                                                                *|

|* See https://llvm.org/LICENSE.txt for license information.                  *|

|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|

|*                                                                            *|

|*===----------------------------------------------------------------------===*|

|*                                                                            *|

|* This header provides the interface to C Index diagnostics.                 *|

|*                                                                            *|

\*===----------------------------------------------------------------------===*/

#ifndef LLVM_CLANG_C_CXDIAGNOSTIC_H

#define LLVM_CLANG_C_CXDIAGNOSTIC_H

#include "clang-c/CXSourceLocation.h"

#include "clang-c/CXString.h"

#include "clang-c/ExternC.h"

#include "clang-c/Platform.h"

LLVM_CLANG_C_EXTERN_C_BEGIN

/**

 * \defgroup CINDEX_DIAG Diagnostic reporting

 *

 * @{

 */

/**

 * Describes the severity of a particular diagnostic.

 */

enum CXDiagnosticSeverity {

  /**

   * A diagnostic that has been suppressed, e.g., by a command-line

   * option.

   */

  CXDiagnostic_Ignored = 0,

  /**

   * This diagnostic is a note that should be attached to the

   * previous (non-note) diagnostic.

   */

  CXDiagnostic_Note = 1,

  /**

   * This diagnostic indicates suspicious code that may not be

   * wrong.

   */

  CXDiagnostic_Warning = 2,

  /**

   * This diagnostic indicates that the code is ill-formed.

   */

  CXDiagnostic_Error = 3,

  /**

   * This diagnostic indicates that the code is ill-formed such

   * that future parser recovery is unlikely to produce useful

   * results.

   */

  CXDiagnostic_Fatal = 4

};

/**

 * A single diagnostic, containing the diagnostic's severity,

 * location, text, source ranges, and fix-it hints.

 */

typedef void *CXDiagnostic;

/**

 * A group of CXDiagnostics.

 */

typedef void *CXDiagnosticSet;

/**

 * Determine the number of diagnostics in a CXDiagnosticSet.

 */

CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags);

/**

 * Retrieve a diagnostic associated with the given CXDiagnosticSet.

 *

 * \param Diags the CXDiagnosticSet to query.

 * \param Index the zero-based diagnostic number to retrieve.

 *

 * \returns the requested diagnostic. This diagnostic must be freed

 * via a call to \c clang_disposeDiagnostic().

 */

CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,

                                                     unsigned Index);

/**

 * Describes the kind of error that occurred (if any) in a call to

 * \c clang_loadDiagnostics.

 */

enum CXLoadDiag_Error {

  /**

   * Indicates that no error occurred.

   */

  CXLoadDiag_None = 0,

  /**

   * Indicates that an unknown error occurred while attempting to

   * deserialize diagnostics.

   */

  CXLoadDiag_Unknown = 1,

  /**

   * Indicates that the file containing the serialized diagnostics

   * could not be opened.

   */

  CXLoadDiag_CannotLoad = 2,

  /**

   * Indicates that the serialized diagnostics file is invalid or

   * corrupt.

   */

  CXLoadDiag_InvalidFile = 3

};

/**

 * Deserialize a set of diagnostics from a Clang diagnostics bitcode

 * file.

 *

 * \param file The name of the file to deserialize.

 * \param error A pointer to a enum value recording if there was a problem

 *        deserializing the diagnostics.

 * \param errorString A pointer to a CXString for recording the error string

 *        if the file was not successfully loaded.

 *

 * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise.  These

 * diagnostics should be released using clang_disposeDiagnosticSet().

 */

CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(

    const char *file, enum CXLoadDiag_Error *error, CXString *errorString);

/**

 * Release a CXDiagnosticSet and all of its contained diagnostics.

 */

CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags);

/**

 * Retrieve the child diagnostics of a CXDiagnostic.

 *

 * This CXDiagnosticSet does not need to be released by

 * clang_disposeDiagnosticSet.

 */

CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D);

/**

 * Destroy a diagnostic.

 */

CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);

/**

 * Options to control the display of diagnostics.

 *

 * The values in this enum are meant to be combined to customize the

 * behavior of \c clang_formatDiagnostic().

 */

enum CXDiagnosticDisplayOptions {

  /**

   * Display the source-location information where the

   * diagnostic was located.

   *

   * When set, diagnostics will be prefixed by the file, line, and

   * (optionally) column to which the diagnostic refers. For example,

   *

   * \code

   * test.c:28: warning: extra tokens at end of #endif directive

   * \endcode

   *

   * This option corresponds to the clang flag \c -fshow-source-location.

   */

  CXDiagnostic_DisplaySourceLocation = 0x01,

  /**

   * If displaying the source-location information of the

   * diagnostic, also include the column number.

   *

   * This option corresponds to the clang flag \c -fshow-column.

   */

  CXDiagnostic_DisplayColumn = 0x02,

  /**

   * If displaying the source-location information of the

   * diagnostic, also include information about source ranges in a

   * machine-parsable format.

   *

   * This option corresponds to the clang flag

   * \c -fdiagnostics-print-source-range-info.

   */

  CXDiagnostic_DisplaySourceRanges = 0x04,

  /**

   * Display the option name associated with this diagnostic, if any.

   *

   * The option name displayed (e.g., -Wconversion) will be placed in brackets

   * after the diagnostic text. This option corresponds to the clang flag

   * \c -fdiagnostics-show-option.

   */

  CXDiagnostic_DisplayOption = 0x08,

  /**

   * Display the category number associated with this diagnostic, if any.

   *

   * The category number is displayed within brackets after the diagnostic text.

   * This option corresponds to the clang flag

   * \c -fdiagnostics-show-category=id.

   */

  CXDiagnostic_DisplayCategoryId = 0x10,

  /**

   * Display the category name associated with this diagnostic, if any.

   *

   * The category name is displayed within brackets after the diagnostic text.

   * This option corresponds to the clang flag

   * \c -fdiagnostics-show-category=name.

   */

  CXDiagnostic_DisplayCategoryName = 0x20

};

/**

 * Format the given diagnostic in a manner that is suitable for display.

 *

 * This routine will format the given diagnostic to a string, rendering

 * the diagnostic according to the various options given. The

 * \c clang_defaultDiagnosticDisplayOptions() function returns the set of

 * options that most closely mimics the behavior of the clang compiler.

 *

 * \param Diagnostic The diagnostic to print.

 *

 * \param Options A set of options that control the diagnostic display,

 * created by combining \c CXDiagnosticDisplayOptions values.

 *

 * \returns A new string containing for formatted diagnostic.

 */

CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,

                                               unsigned Options);

/**

 * Retrieve the set of display options most similar to the

 * default behavior of the clang compiler.

 *

 * \returns A set of display options suitable for use with \c

 * clang_formatDiagnostic().

 */

CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void);

/**

 * Determine the severity of the given diagnostic.

 */

CINDEX_LINKAGE enum CXDiagnosticSeverity

    clang_getDiagnosticSeverity(CXDiagnostic);

/**

 * Retrieve the source location of the given diagnostic.

 *

 * This location is where Clang would print the caret ('^') when

 * displaying the diagnostic on the command line.

 */

CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);

/**

 * Retrieve the text of the given diagnostic.

 */

CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);

/**

 * Retrieve the name of the command-line option that enabled this

 * diagnostic.

 *

 * \param Diag The diagnostic to be queried.

 *

 * \param Disable If non-NULL, will be set to the option that disables this

 * diagnostic (if any).

 *

 * \returns A string that contains the command-line option used to enable this

 * warning, such as "-Wconversion" or "-pedantic".

 */

CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag,

                                                  CXString *Disable);

/**

 * Retrieve the category number for this diagnostic.

 *

 * Diagnostics can be categorized into groups along with other, related

 * diagnostics (e.g., diagnostics under the same warning flag). This routine

 * retrieves the category number for the given diagnostic.

 *

 * \returns The number of the category that contains this diagnostic, or zero

 * if this diagnostic is uncategorized.

 */

CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);

/**

 * Retrieve the name of a particular diagnostic category.  This

 *  is now deprecated.  Use clang_getDiagnosticCategoryText()

 *  instead.

 *

 * \param Category A diagnostic category number, as returned by

 * \c clang_getDiagnosticCategory().

 *

 * \returns The name of the given diagnostic category.

 */

CINDEX_DEPRECATED CINDEX_LINKAGE CXString

clang_getDiagnosticCategoryName(unsigned Category);

/**

 * Retrieve the diagnostic category text for a given diagnostic.

 *

 * \returns The text of the given diagnostic category.

 */

CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic);

/**

 * Determine the number of source ranges associated with the given

 * diagnostic.

 */

CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);

/**

 * Retrieve a source range associated with the diagnostic.

 *

 * A diagnostic's source ranges highlight important elements in the source

 * code. On the command line, Clang displays source ranges by

 * underlining them with '~' characters.

 *

 * \param Diagnostic the diagnostic whose range is being extracted.

 *

 * \param Range the zero-based index specifying which range to

 *

 * \returns the requested source range.

 */

CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,

                                                      unsigned Range);

/**

 * Determine the number of fix-it hints associated with the

 * given diagnostic.

 */

CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);

/**

 * Retrieve the replacement information for a given fix-it.

 *

 * Fix-its are described in terms of a source range whose contents

 * should be replaced by a string. This approach generalizes over

 * three kinds of operations: removal of source code (the range covers

 * the code to be removed and the replacement string is empty),

 * replacement of source code (the range covers the code to be

 * replaced and the replacement string provides the new code), and

 * insertion (both the start and end of the range point at the

 * insertion location, and the replacement string provides the text to

 * insert).

 *

 * \param Diagnostic The diagnostic whose fix-its are being queried.

 *

 * \param FixIt The zero-based index of the fix-it.

 *

 * \param ReplacementRange The source range whose contents will be

 * replaced with the returned replacement string. Note that source

 * ranges are half-open ranges [a, b), so the source code should be

 * replaced from a and up to (but not including) b.

 *

 * \returns A string containing text that should be replace the source

 * code indicated by the \c ReplacementRange.

 */

CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(

    CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange);

/**

 * @}

 */

LLVM_CLANG_C_EXTERN_C_END

#endif