clang 19.0.0git
CXDiagnostic.h
Go to the documentation of this file.
1/*===-- clang-c/CXDiagnostic.h - C Index Diagnostics --------------*- C -*-===*\
2|* *|
3|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
4|* Exceptions. *|
5|* See https://llvm.org/LICENSE.txt for license information. *|
6|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
7|* *|
8|*===----------------------------------------------------------------------===*|
9|* *|
10|* This header provides the interface to C Index diagnostics. *|
11|* *|
12\*===----------------------------------------------------------------------===*/
13
14#ifndef LLVM_CLANG_C_CXDIAGNOSTIC_H
15#define LLVM_CLANG_C_CXDIAGNOSTIC_H
16
18#include "clang-c/CXString.h"
19#include "clang-c/ExternC.h"
20#include "clang-c/Platform.h"
21
23
24/**
25 * \defgroup CINDEX_DIAG Diagnostic reporting
26 *
27 * @{
28 */
29
30/**
31 * Describes the severity of a particular diagnostic.
32 */
34 /**
35 * A diagnostic that has been suppressed, e.g., by a command-line
36 * option.
37 */
39
40 /**
41 * This diagnostic is a note that should be attached to the
42 * previous (non-note) diagnostic.
43 */
45
46 /**
47 * This diagnostic indicates suspicious code that may not be
48 * wrong.
49 */
51
52 /**
53 * This diagnostic indicates that the code is ill-formed.
54 */
56
57 /**
58 * This diagnostic indicates that the code is ill-formed such
59 * that future parser recovery is unlikely to produce useful
60 * results.
61 */
63};
64
65/**
66 * A single diagnostic, containing the diagnostic's severity,
67 * location, text, source ranges, and fix-it hints.
68 */
69typedef void *CXDiagnostic;
70
71/**
72 * A group of CXDiagnostics.
73 */
74typedef void *CXDiagnosticSet;
75
76/**
77 * Determine the number of diagnostics in a CXDiagnosticSet.
78 */
80
81/**
82 * Retrieve a diagnostic associated with the given CXDiagnosticSet.
83 *
84 * \param Diags the CXDiagnosticSet to query.
85 * \param Index the zero-based diagnostic number to retrieve.
86 *
87 * \returns the requested diagnostic. This diagnostic must be freed
88 * via a call to \c clang_disposeDiagnostic().
89 */
91 unsigned Index);
92
93/**
94 * Describes the kind of error that occurred (if any) in a call to
95 * \c clang_loadDiagnostics.
96 */
98 /**
99 * Indicates that no error occurred.
100 */
102
103 /**
104 * Indicates that an unknown error occurred while attempting to
105 * deserialize diagnostics.
106 */
108
109 /**
110 * Indicates that the file containing the serialized diagnostics
111 * could not be opened.
112 */
114
115 /**
116 * Indicates that the serialized diagnostics file is invalid or
117 * corrupt.
118 */
121
122/**
123 * Deserialize a set of diagnostics from a Clang diagnostics bitcode
124 * file.
125 *
126 * \param file The name of the file to deserialize.
127 * \param error A pointer to a enum value recording if there was a problem
128 * deserializing the diagnostics.
129 * \param errorString A pointer to a CXString for recording the error string
130 * if the file was not successfully loaded.
131 *
132 * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These
133 * diagnostics should be released using clang_disposeDiagnosticSet().
134 */
136 const char *file, enum CXLoadDiag_Error *error, CXString *errorString);
137
138/**
139 * Release a CXDiagnosticSet and all of its contained diagnostics.
140 */
142
143/**
144 * Retrieve the child diagnostics of a CXDiagnostic.
145 *
146 * This CXDiagnosticSet does not need to be released by
147 * clang_disposeDiagnosticSet.
148 */
150
151/**
152 * Destroy a diagnostic.
153 */
155
156/**
157 * Options to control the display of diagnostics.
158 *
159 * The values in this enum are meant to be combined to customize the
160 * behavior of \c clang_formatDiagnostic().
161 */
163 /**
164 * Display the source-location information where the
165 * diagnostic was located.
166 *
167 * When set, diagnostics will be prefixed by the file, line, and
168 * (optionally) column to which the diagnostic refers. For example,
169 *
170 * \code
171 * test.c:28: warning: extra tokens at end of #endif directive
172 * \endcode
173 *
174 * This option corresponds to the clang flag \c -fshow-source-location.
175 */
177
178 /**
179 * If displaying the source-location information of the
180 * diagnostic, also include the column number.
181 *
182 * This option corresponds to the clang flag \c -fshow-column.
183 */
185
186 /**
187 * If displaying the source-location information of the
188 * diagnostic, also include information about source ranges in a
189 * machine-parsable format.
190 *
191 * This option corresponds to the clang flag
192 * \c -fdiagnostics-print-source-range-info.
193 */
195
196 /**
197 * Display the option name associated with this diagnostic, if any.
198 *
199 * The option name displayed (e.g., -Wconversion) will be placed in brackets
200 * after the diagnostic text. This option corresponds to the clang flag
201 * \c -fdiagnostics-show-option.
202 */
204
205 /**
206 * Display the category number associated with this diagnostic, if any.
207 *
208 * The category number is displayed within brackets after the diagnostic text.
209 * This option corresponds to the clang flag
210 * \c -fdiagnostics-show-category=id.
211 */
213
214 /**
215 * Display the category name associated with this diagnostic, if any.
216 *
217 * The category name is displayed within brackets after the diagnostic text.
218 * This option corresponds to the clang flag
219 * \c -fdiagnostics-show-category=name.
220 */
223
224/**
225 * Format the given diagnostic in a manner that is suitable for display.
226 *
227 * This routine will format the given diagnostic to a string, rendering
228 * the diagnostic according to the various options given. The
229 * \c clang_defaultDiagnosticDisplayOptions() function returns the set of
230 * options that most closely mimics the behavior of the clang compiler.
231 *
232 * \param Diagnostic The diagnostic to print.
233 *
234 * \param Options A set of options that control the diagnostic display,
235 * created by combining \c CXDiagnosticDisplayOptions values.
236 *
237 * \returns A new string containing for formatted diagnostic.
238 */
240 unsigned Options);
241
242/**
243 * Retrieve the set of display options most similar to the
244 * default behavior of the clang compiler.
245 *
246 * \returns A set of display options suitable for use with \c
247 * clang_formatDiagnostic().
248 */
250
251/**
252 * Determine the severity of the given diagnostic.
253 */
256
257/**
258 * Retrieve the source location of the given diagnostic.
259 *
260 * This location is where Clang would print the caret ('^') when
261 * displaying the diagnostic on the command line.
262 */
264
265/**
266 * Retrieve the text of the given diagnostic.
267 */
269
270/**
271 * Retrieve the name of the command-line option that enabled this
272 * diagnostic.
273 *
274 * \param Diag The diagnostic to be queried.
275 *
276 * \param Disable If non-NULL, will be set to the option that disables this
277 * diagnostic (if any).
278 *
279 * \returns A string that contains the command-line option used to enable this
280 * warning, such as "-Wconversion" or "-pedantic".
281 */
283 CXString *Disable);
284
285/**
286 * Retrieve the category number for this diagnostic.
287 *
288 * Diagnostics can be categorized into groups along with other, related
289 * diagnostics (e.g., diagnostics under the same warning flag). This routine
290 * retrieves the category number for the given diagnostic.
291 *
292 * \returns The number of the category that contains this diagnostic, or zero
293 * if this diagnostic is uncategorized.
294 */
296
297/**
298 * Retrieve the name of a particular diagnostic category. This
299 * is now deprecated. Use clang_getDiagnosticCategoryText()
300 * instead.
301 *
302 * \param Category A diagnostic category number, as returned by
303 * \c clang_getDiagnosticCategory().
304 *
305 * \returns The name of the given diagnostic category.
306 */
309
310/**
311 * Retrieve the diagnostic category text for a given diagnostic.
312 *
313 * \returns The text of the given diagnostic category.
314 */
316
317/**
318 * Determine the number of source ranges associated with the given
319 * diagnostic.
320 */
322
323/**
324 * Retrieve a source range associated with the diagnostic.
325 *
326 * A diagnostic's source ranges highlight important elements in the source
327 * code. On the command line, Clang displays source ranges by
328 * underlining them with '~' characters.
329 *
330 * \param Diagnostic the diagnostic whose range is being extracted.
331 *
332 * \param Range the zero-based index specifying which range to
333 *
334 * \returns the requested source range.
335 */
337 unsigned Range);
338
339/**
340 * Determine the number of fix-it hints associated with the
341 * given diagnostic.
342 */
344
345/**
346 * Retrieve the replacement information for a given fix-it.
347 *
348 * Fix-its are described in terms of a source range whose contents
349 * should be replaced by a string. This approach generalizes over
350 * three kinds of operations: removal of source code (the range covers
351 * the code to be removed and the replacement string is empty),
352 * replacement of source code (the range covers the code to be
353 * replaced and the replacement string provides the new code), and
354 * insertion (both the start and end of the range point at the
355 * insertion location, and the replacement string provides the text to
356 * insert).
357 *
358 * \param Diagnostic The diagnostic whose fix-its are being queried.
359 *
360 * \param FixIt The zero-based index of the fix-it.
361 *
362 * \param ReplacementRange The source range whose contents will be
363 * replaced with the returned replacement string. Note that source
364 * ranges are half-open ranges [a, b), so the source code should be
365 * replaced from a and up to (but not including) b.
366 *
367 * \returns A string containing text that should be replace the source
368 * code indicated by the \c ReplacementRange.
369 */
371 CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange);
372
373/**
374 * @}
375 */
376
378
379#endif
#define LLVM_CLANG_C_EXTERN_C_END
Definition: ExternC.h:36
#define LLVM_CLANG_C_EXTERN_C_BEGIN
Definition: ExternC.h:35
int Category
Definition: Format.cpp:2978
static DiagnosticBuilder Diag(DiagnosticsEngine *Diags, const LangOptions &Features, FullSourceLoc TokLoc, const char *TokBegin, const char *TokRangeBegin, const char *TokRangeEnd, unsigned DiagID)
Produce a diagnostic highlighting some portion of a literal.
#define CINDEX_DEPRECATED
Definition: Platform.h:47
#define CINDEX_LINKAGE
Definition: Platform.h:38
SourceRange Range
Definition: SemaObjC.cpp:754
CXDiagnosticDisplayOptions
Options to control the display of diagnostics.
Definition: CXDiagnostic.h:162
CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic)
Destroy a diagnostic.
CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic)
Retrieve the category number for this diagnostic.
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 CXString clang_getDiagnosticSpelling(CXDiagnostic)
Retrieve the text of the given diagnostic.
void * CXDiagnosticSet
A group of CXDiagnostics.
Definition: CXDiagnostic.h:74
void * CXDiagnostic
A single diagnostic, containing the diagnostic's severity, location, text, source ranges,...
Definition: CXDiagnostic.h:69
CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags)
Determine the number of diagnostics in a CXDiagnosticSet.
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 CXString clang_getDiagnosticCategoryText(CXDiagnostic)
Retrieve the diagnostic category text for a 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_getDiagnosticNumRanges(CXDiagnostic)
Determine the number of source ranges associated with the given diagnostic.
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 CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, unsigned Range)
Retrieve a source range associated with the diagnostic.
CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic)
Retrieve the source location of the given diagnostic.
CXDiagnosticSeverity
Describes the severity of a particular diagnostic.
Definition: CXDiagnostic.h:33
CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange)
Retrieve the replacement information for a given fix-it.
CINDEX_DEPRECATED CINDEX_LINKAGE CXString clang_getDiagnosticCategoryName(unsigned Category)
Retrieve the name of a particular diagnostic category.
CXLoadDiag_Error
Describes the kind of error that occurred (if any) in a call to clang_loadDiagnostics.
Definition: CXDiagnostic.h:97
CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic)
Determine the number of fix-it hints associated with the given diagnostic.
CINDEX_LINKAGE enum CXDiagnosticSeverity clang_getDiagnosticSeverity(CXDiagnostic)
Determine the severity of the given diagnostic.
@ CXDiagnostic_DisplayColumn
If displaying the source-location information of the diagnostic, also include the column number.
Definition: CXDiagnostic.h:184
@ CXDiagnostic_DisplaySourceLocation
Display the source-location information where the diagnostic was located.
Definition: CXDiagnostic.h:176
@ CXDiagnostic_DisplayOption
Display the option name associated with this diagnostic, if any.
Definition: CXDiagnostic.h:203
@ CXDiagnostic_DisplayCategoryId
Display the category number associated with this diagnostic, if any.
Definition: CXDiagnostic.h:212
@ CXDiagnostic_DisplayCategoryName
Display the category name associated with this diagnostic, if any.
Definition: CXDiagnostic.h:221
@ CXDiagnostic_DisplaySourceRanges
If displaying the source-location information of the diagnostic, also include information about sourc...
Definition: CXDiagnostic.h:194
@ CXDiagnostic_Fatal
This diagnostic indicates that the code is ill-formed such that future parser recovery is unlikely to...
Definition: CXDiagnostic.h:62
@ CXDiagnostic_Ignored
A diagnostic that has been suppressed, e.g., by a command-line option.
Definition: CXDiagnostic.h:38
@ CXDiagnostic_Note
This diagnostic is a note that should be attached to the previous (non-note) diagnostic.
Definition: CXDiagnostic.h:44
@ CXDiagnostic_Error
This diagnostic indicates that the code is ill-formed.
Definition: CXDiagnostic.h:55
@ CXDiagnostic_Warning
This diagnostic indicates suspicious code that may not be wrong.
Definition: CXDiagnostic.h:50
@ CXLoadDiag_None
Indicates that no error occurred.
Definition: CXDiagnostic.h:101
@ CXLoadDiag_Unknown
Indicates that an unknown error occurred while attempting to deserialize diagnostics.
Definition: CXDiagnostic.h:107
@ CXLoadDiag_CannotLoad
Indicates that the file containing the serialized diagnostics could not be opened.
Definition: CXDiagnostic.h:113
@ CXLoadDiag_InvalidFile
Indicates that the serialized diagnostics file is invalid or corrupt.
Definition: CXDiagnostic.h:119
Identifies a specific source location within a translation unit.
Identifies a half-open character range in the source code.
A character string.
Definition: CXString.h:37