blob: a8b123c650479b3445acbc7e65cb73edbb3d7140 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
.. Copyright (C) 2024-2025 Free Software Foundation, Inc.
Originally contributed by David Malcolm <dmalcolm@redhat.com>
This is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see
<https://www.gnu.org/licenses/>.
.. default-domain:: c
Tutorial part 4: adding notes
=============================
Let's further extend the previous example to add a "note" to it.
We want to generate output like this::
test-with-note.c:17:11: error: can't find 'foo.h'
17 | #include <foo.h>
| ^~~~~
test-with-note.c:17:11: note: have you looked behind the couch?
The "error" and "note" are both instances of :type:`diagnostic`.
We want to let libgdiagnostics know that they are grouped together.
The way to do this is to use :func:`diagnostic_manager_begin_group`
and :func:`diagnostic_manager_end_group` around the "finish" calls
to the diagnostics.
.. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-error-with-note.c
:language: c
:start-after: /* begin quoted source */
:end-before: /* end quoted source */
On compiling and running the program, we should get the desired output::
test-with-note.c:17:11: error: can't find 'foo.h'
17 | #include <foo.h>
| ^~~~~
test-with-note.c:17:11: note: have you looked behind the couch?
The grouping doesn't affect text output sinks, but a
:doc:`SARIF sink <../topics/sarif>` will group the note within the error
(via the ``relatedLocations`` property of ``result`` objects; see SARIF v2.1.0
`ยง3.27.22 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790910>`_).
In the above, the note had the same physical location as the error
(``loc_range``). This can be useful for splitting up a message into two
parts to make localization easier, but they could have different locations, such
as in::
test.xml:10:2: error: 'foo' is not valid here
test.xml:5:1: note: within element 'bar'
where each :type:`diagnostic` had its own :type:`diagnostic_physical_location`.
In :doc:`the next tutorial <05-warnings>` we'll look at issuing warnings,
rather than errors.
|
