clang API Documentation

Typedefs | Enumerations | Functions
Diagnostic reporting
libclang: C Interface to Clang
Collaboration diagram for Diagnostic reporting:

Typedefs

typedef void * CXDiagnostic
 A single diagnostic, containing the diagnostic's severity, location, text, source ranges, and fix-it hints.
typedef void * CXDiagnosticSet
 A group of CXDiagnostics.

Enumerations

enum  CXDiagnosticSeverity {
  CXDiagnostic_Ignored = 0, CXDiagnostic_Note = 1, CXDiagnostic_Warning = 2, CXDiagnostic_Error = 3,
  CXDiagnostic_Fatal = 4
}
 Describes the severity of a particular diagnostic. More...
enum  CXLoadDiag_Error { CXLoadDiag_None = 0, CXLoadDiag_Unknown = 1, CXLoadDiag_CannotLoad = 2, CXLoadDiag_InvalidFile = 3 }
 Describes the kind of error that occurred (if any) in a call to clang_loadDiagnostics. More...
enum  CXDiagnosticDisplayOptions {
  CXDiagnostic_DisplaySourceLocation = 0x01, CXDiagnostic_DisplayColumn = 0x02, CXDiagnostic_DisplaySourceRanges = 0x04, CXDiagnostic_DisplayOption = 0x08,
  CXDiagnostic_DisplayCategoryId = 0x10, CXDiagnostic_DisplayCategoryName = 0x20
}
 Options to control the display of diagnostics. More...

Functions

CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet (CXDiagnosticSet Diags)
 Determine the number of diagnostics in a CXDiagnosticSet.
CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet (CXDiagnosticSet Diags, unsigned Index)
 Retrieve a diagnostic associated with the given CXDiagnosticSet.
CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics (const char *file, enum CXLoadDiag_Error *error, CXString *errorString)
 Deserialize a set of diagnostics from a Clang diagnostics bitcode file.
CINDEX_LINKAGE void clang_disposeDiagnosticSet (CXDiagnosticSet Diags)
 Release a CXDiagnosticSet and all of its contained diagnostics.
CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics (CXDiagnostic D)
 Retrieve the child diagnostics of a CXDiagnostic.
CINDEX_LINKAGE unsigned clang_getNumDiagnostics (CXTranslationUnit Unit)
 Determine the number of diagnostics produced for the given translation unit.
CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic (CXTranslationUnit Unit, unsigned Index)
 Retrieve a diagnostic associated with the given translation unit.
CINDEX_LINKAGE CXDiagnosticSet clang_getDiagnosticSetFromTU (CXTranslationUnit Unit)
 Retrieve the complete set of diagnostics associated with a translation unit.
CINDEX_LINKAGE void clang_disposeDiagnostic (CXDiagnostic Diagnostic)
 Destroy a diagnostic.
CINDEX_LINKAGE CXString clang_formatDiagnostic (CXDiagnostic Diagnostic, unsigned Options)
 Format the given diagnostic in a manner that is suitable for display.
CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions (void)
 Retrieve the set of display options most similar to the default behavior of the clang compiler.
CINDEX_LINKAGE enum
CXDiagnosticSeverity 
clang_getDiagnosticSeverity (CXDiagnostic)
 Determine the severity of the given diagnostic.
CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation (CXDiagnostic)
 Retrieve the source location of the given diagnostic.
CINDEX_LINKAGE CXString clang_getDiagnosticSpelling (CXDiagnostic)
 Retrieve the text of the given diagnostic.
CINDEX_LINKAGE CXString clang_getDiagnosticOption (CXDiagnostic Diag, CXString *Disable)
 Retrieve the name of the command-line option that enabled this diagnostic.
CINDEX_LINKAGE unsigned clang_getDiagnosticCategory (CXDiagnostic)
 Retrieve the category number for this diagnostic.
CINDEX_DEPRECATED
CINDEX_LINKAGE CXString 
clang_getDiagnosticCategoryName (unsigned Category)
 Retrieve the name of a particular diagnostic category. This is now deprecated. Use clang_getDiagnosticCategoryText() instead.
CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText (CXDiagnostic)
 Retrieve the diagnostic category text for a given diagnostic.
CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges (CXDiagnostic)
 Determine the number of source ranges associated with the given diagnostic.
CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange (CXDiagnostic Diagnostic, unsigned Range)
 Retrieve a source range associated with the diagnostic.
CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts (CXDiagnostic Diagnostic)
 Determine the number of fix-it hints associated with the given diagnostic.
CINDEX_LINKAGE CXString clang_getDiagnosticFixIt (CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange)
 Retrieve the replacement information for a given fix-it.

Typedef Documentation

typedef void* CXDiagnostic

A single diagnostic, containing the diagnostic's severity, location, text, source ranges, and fix-it hints.

Definition at line 678 of file Index.h.

typedef void* CXDiagnosticSet

A group of CXDiagnostics.

Definition at line 683 of file Index.h.


Enumeration Type Documentation

Options to control the display of diagnostics.

The values in this enum are meant to be combined to customize the behavior of clang_formatDiagnostic().

Enumerator:
CXDiagnostic_DisplaySourceLocation 

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,

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

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

CXDiagnostic_DisplayColumn 

If displaying the source-location information of the diagnostic, also include the column number.

This option corresponds to the clang flag -fshow-column.

CXDiagnostic_DisplaySourceRanges 

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 -fdiagnostics-print-source-range-info.

CXDiagnostic_DisplayOption 

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 -fdiagnostics-show-option.

CXDiagnostic_DisplayCategoryId 

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 -fdiagnostics-show-category=id.

CXDiagnostic_DisplayCategoryName 

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 -fdiagnostics-show-category=name.

Definition at line 800 of file Index.h.

Describes the severity of a particular diagnostic.

Enumerator:
CXDiagnostic_Ignored 

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

CXDiagnostic_Note 

This diagnostic is a note that should be attached to the previous (non-note) diagnostic.

CXDiagnostic_Warning 

This diagnostic indicates suspicious code that may not be wrong.

CXDiagnostic_Error 

This diagnostic indicates that the code is ill-formed.

CXDiagnostic_Fatal 

This diagnostic indicates that the code is ill-formed such that future parser recovery is unlikely to produce useful results.

Definition at line 642 of file Index.h.

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

Enumerator:
CXLoadDiag_None 

Indicates that no error occurred.

CXLoadDiag_Unknown 

Indicates that an unknown error occurred while attempting to deserialize diagnostics.

CXLoadDiag_CannotLoad 

Indicates that the file containing the serialized diagnostics could not be opened.

CXLoadDiag_InvalidFile 

Indicates that the serialized diagnostics file is invalid or corrupt.

Definition at line 707 of file Index.h.


Function Documentation

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 clang_formatDiagnostic().

Destroy a diagnostic.

Release a CXDiagnosticSet and all of its contained diagnostics.

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 clang_defaultDiagnosticDisplayOptions() function returns the set of options that most closely mimics the behavior of the clang compiler.

Parameters:
DiagnosticThe diagnostic to print.
OptionsA set of options that control the diagnostic display, created by combining CXDiagnosticDisplayOptions values.
Returns:
A new string containing for formatted diagnostic.

Retrieve the child diagnostics of a CXDiagnostic.

This CXDiagnosticSet does not need to be released by clang_disposeDiagnosticSet.

Retrieve a diagnostic associated with the given translation unit.

Parameters:
Unitthe translation unit to query.
Indexthe zero-based diagnostic number to retrieve.
Returns:
the requested diagnostic. This diagnostic must be freed via a call to clang_disposeDiagnostic().

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.

Retrieve the name of a particular diagnostic category. This is now deprecated. Use clang_getDiagnosticCategoryText() instead.

Parameters:
CategoryA diagnostic category number, as returned by clang_getDiagnosticCategory().
Returns:
The name of the given diagnostic category.

Retrieve the diagnostic category text for a given diagnostic.

Returns:
The text of the given diagnostic category.
CINDEX_LINKAGE CXString clang_getDiagnosticFixIt ( CXDiagnostic  Diagnostic,
unsigned  FixIt,
CXSourceRange ReplacementRange 
)

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).

Parameters:
DiagnosticThe diagnostic whose fix-its are being queried.
FixItThe zero-based index of the fix-it.
ReplacementRangeThe 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 ReplacementRange.

Retrieve a diagnostic associated with the given CXDiagnosticSet.

Parameters:
Diagsthe CXDiagnosticSet to query.
Indexthe zero-based diagnostic number to retrieve.
Returns:
the requested diagnostic. This diagnostic must be freed via a call to clang_disposeDiagnostic().

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.

Determine the number of fix-it hints associated with the given diagnostic.

Determine the number of source ranges associated with the given diagnostic.

Retrieve the name of the command-line option that enabled this diagnostic.

Parameters:
DiagThe diagnostic to be queried.
DisableIf 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".

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.

Parameters:
Diagnosticthe diagnostic whose range is being extracted.
Rangethe zero-based index specifying which range to
Returns:
the requested source range.

Retrieve the complete set of diagnostics associated with a translation unit.

Parameters:
Unitthe translation unit to query.

Determine the severity of the given diagnostic.

Retrieve the text of the given diagnostic.

Determine the number of diagnostics produced for the given translation unit.

Determine the number of diagnostics in a CXDiagnosticSet.

CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics ( const char *  file,
enum CXLoadDiag_Error error,
CXString errorString 
)

Deserialize a set of diagnostics from a Clang diagnostics bitcode file.

Parameters:
fileThe name of the file to deserialize.
errorA pointer to a enum value recording if there was a problem deserializing the diagnostics.
errorStringA 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().