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
17#include "clang-c/CXSourceLocation.h"
18#include "clang-c/CXString.h"
19#include "clang-c/ExternC.h"
20#include "clang-c/Platform.h"
21
22LLVM_CLANG_C_EXTERN_C_BEGIN
23
24/**
25 * \defgroup CINDEX_DIAG Diagnostic reporting
26 *
27 * @{
28 */
29
30/**
31 * Describes the severity of a particular diagnostic.
32 */
33enum CXDiagnosticSeverity {
34 /**
35 * A diagnostic that has been suppressed, e.g., by a command-line
36 * option.
37 */
38 CXDiagnostic_Ignored = 0,
39
40 /**
41 * This diagnostic is a note that should be attached to the
42 * previous (non-note) diagnostic.
43 */
44 CXDiagnostic_Note = 1,
45
46 /**
47 * This diagnostic indicates suspicious code that may not be
48 * wrong.
49 */
50 CXDiagnostic_Warning = 2,
51
52 /**
53 * This diagnostic indicates that the code is ill-formed.
54 */
55 CXDiagnostic_Error = 3,
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 */
62 CXDiagnostic_Fatal = 4
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 */
79CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags);
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 */
90CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,
91 unsigned Index);
92
93/**
94 * Describes the kind of error that occurred (if any) in a call to
95 * \c clang_loadDiagnostics.
96 */
97enum CXLoadDiag_Error {
98 /**
99 * Indicates that no error occurred.
100 */
101 CXLoadDiag_None = 0,
102
103 /**
104 * Indicates that an unknown error occurred while attempting to
105 * deserialize diagnostics.
106 */
107 CXLoadDiag_Unknown = 1,
108
109 /**
110 * Indicates that the file containing the serialized diagnostics
111 * could not be opened.
112 */
113 CXLoadDiag_CannotLoad = 2,
114
115 /**
116 * Indicates that the serialized diagnostics file is invalid or
117 * corrupt.
118 */
119 CXLoadDiag_InvalidFile = 3
120};
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 */
135CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(
136 const char *file, enum CXLoadDiag_Error *error, CXString *errorString);
137
138/**
139 * Release a CXDiagnosticSet and all of its contained diagnostics.
140 */
141CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags);
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 */
149CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D);
150
151/**
152 * Destroy a diagnostic.
153 */
154CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);
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 */
162enum CXDiagnosticDisplayOptions {
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 */
176 CXDiagnostic_DisplaySourceLocation = 0x01,
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 */
184 CXDiagnostic_DisplayColumn = 0x02,
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 */
194 CXDiagnostic_DisplaySourceRanges = 0x04,
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 */
203 CXDiagnostic_DisplayOption = 0x08,
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 */
212 CXDiagnostic_DisplayCategoryId = 0x10,
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 */
221 CXDiagnostic_DisplayCategoryName = 0x20
222};
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 */
239CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,
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 */
249CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void);
250
251/**
252 * Determine the severity of the given diagnostic.
253 */
254CINDEX_LINKAGE enum CXDiagnosticSeverity
255 clang_getDiagnosticSeverity(CXDiagnostic);
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 */
263CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);
264
265/**
266 * Retrieve the text of the given diagnostic.
267 */
268CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);
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 */
282CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag,
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 */
295CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);
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 */
307CINDEX_DEPRECATED CINDEX_LINKAGE CXString
308clang_getDiagnosticCategoryName(unsigned Category);
309
310/**
311 * Retrieve the diagnostic category text for a given diagnostic.
312 *
313 * \returns The text of the given diagnostic category.
314 */
315CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic);
316
317/**
318 * Determine the number of source ranges associated with the given
319 * diagnostic.
320 */
321CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
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 */
336CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,
337 unsigned Range);
338
339/**
340 * Determine the number of fix-it hints associated with the
341 * given diagnostic.
342 */
343CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
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 */
370CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(
371 CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange);
372
373/**
374 * @}
375 */
376
377LLVM_CLANG_C_EXTERN_C_END
378
379#endif
380