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

Detailed Description

Typedef Documentation

CXDiagnostic

typedef void* CXDiagnostic

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

Definition at line 69 of file CXDiagnostic.h.

CXDiagnosticSet

typedef void* CXDiagnosticSet

A group of CXDiagnostics.

Definition at line 74 of file CXDiagnostic.h.

Enumeration Type Documentation

CXDiagnosticDisplayOptions

enum CXDiagnosticDisplayOptions

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 162 of file CXDiagnostic.h.

CXDiagnosticSeverity

enum CXDiagnosticSeverity

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 33 of file CXDiagnostic.h.

CXLoadDiag_Error

enum CXLoadDiag_Error

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 97 of file CXDiagnostic.h.

Function Documentation

clang_defaultDiagnosticDisplayOptions()

CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions

(

void

)

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

clang_disposeDiagnostic()

CINDEX_LINKAGE void clang_disposeDiagnostic

(

CXDiagnostic

Diagnostic

)

Destroy a diagnostic.

clang_disposeDiagnosticSet()

CINDEX_LINKAGE void clang_disposeDiagnosticSet

(

CXDiagnosticSet

Diags

)

Release a CXDiagnosticSet and all of its contained diagnostics.

clang_formatDiagnostic()

CINDEX_LINKAGE CXString clang_formatDiagnostic	(	CXDiagnostic	Diagnostic,
		unsigned	Options
	)

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

Diagnostic	The diagnostic to print.
Options	A set of options that control the diagnostic display, created by combining CXDiagnosticDisplayOptions values.

Returns

A new string containing for formatted diagnostic.

clang_getChildDiagnostics()

CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics

(

CXDiagnostic

D

)

Retrieve the child diagnostics of a CXDiagnostic.

This CXDiagnosticSet does not need to be released by clang_disposeDiagnosticSet.

clang_getDiagnosticCategory()

CINDEX_LINKAGE unsigned clang_getDiagnosticCategory

(

CXDiagnostic

)

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.

clang_getDiagnosticCategoryName()

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.

Parameters

Category

A diagnostic category number, as returned by clang_getDiagnosticCategory().

Returns

The name of the given diagnostic category.

clang_getDiagnosticCategoryText()

CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText

(

CXDiagnostic

)

Retrieve the diagnostic category text for a given diagnostic.

Returns

The text of the given diagnostic category.

clang_getDiagnosticFixIt()

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

Diagnostic	The diagnostic whose fix-its are being queried.
FixIt	The zero-based index of the fix-it.
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 ReplacementRange.

clang_getDiagnosticInSet()

CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet	(	CXDiagnosticSet	Diags,
		unsigned	Index
	)

Retrieve a diagnostic associated with the given CXDiagnosticSet.

Parameters

Diags	the CXDiagnosticSet to query.
Index	the zero-based diagnostic number to retrieve.

Returns

the requested diagnostic. This diagnostic must be freed via a call to clang_disposeDiagnostic().

clang_getDiagnosticLocation()

CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation

(

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.

clang_getDiagnosticNumFixIts()

CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts

(

CXDiagnostic

Diagnostic

)

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

clang_getDiagnosticNumRanges()

CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges

(

CXDiagnostic

)

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

clang_getDiagnosticOption()

CINDEX_LINKAGE CXString clang_getDiagnosticOption	(	CXDiagnostic	Diag,
		CXString *	Disable
	)

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

Parameters

Diag	The diagnostic to be queried.
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".

clang_getDiagnosticRange()

CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange	(	CXDiagnostic	Diagnostic,
		unsigned	Range
	)

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

Diagnostic	the diagnostic whose range is being extracted.
Range	the zero-based index specifying which range to

Returns

the requested source range.

clang_getDiagnosticSeverity()

CINDEX_LINKAGE enum CXDiagnosticSeverity clang_getDiagnosticSeverity

(

CXDiagnostic

)

Determine the severity of the given diagnostic.

clang_getDiagnosticSpelling()

CINDEX_LINKAGE CXString clang_getDiagnosticSpelling

(

CXDiagnostic

)

Retrieve the text of the given diagnostic.

clang_getNumDiagnosticsInSet()

CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet

(

CXDiagnosticSet

Diags

)

Determine the number of diagnostics in a CXDiagnosticSet.

clang_loadDiagnostics()

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

file	The name of the file to deserialize.
error	A pointer to a enum value recording if there was a problem deserializing the diagnostics.
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().