| 1 |
.. Copyright (C) 2024-2025 Free Software Foundation, Inc. |
| 2 |
Originally contributed by David Malcolm <[email protected]> |
| 3 |
|
| 4 |
This is free software: you can redistribute it and/or modify it |
| 5 |
under the terms of the GNU General Public License as published by |
| 6 |
the Free Software Foundation, either version 3 of the License, or |
| 7 |
(at your option) any later version. |
| 8 |
|
| 9 |
This program is distributed in the hope that it will be useful, but |
| 10 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 12 |
General Public License for more details. |
| 13 |
|
| 14 |
You should have received a copy of the GNU General Public License |
| 15 |
along with this program. If not, see |
| 16 |
<https://www.gnu.org/licenses/>. |
| 17 |
|
| 18 |
.. default-domain:: c |
| 19 |
|
| 20 |
Physical locations |
| 21 |
================== |
| 22 |
|
| 23 |
A "physical" source location is a location expressed in terms of |
| 24 |
a specific file, and line(s) and column(s) (as opposed to a |
| 25 |
:doc:`"logical" location <logical-locations>`, |
| 26 |
which refers to semantic constructs in a programming language). |
| 27 |
|
| 28 |
Creating location information |
| 29 |
***************************** |
| 30 |
|
| 31 |
The :type:`diagnostic_manager` manages various objects relating to |
| 32 |
locations. |
| 33 |
|
| 34 |
.. type:: diagnostic_file |
| 35 |
|
| 36 |
A :type:`diagnostic_file` is an opaque type describing a particular input file. |
| 37 |
|
| 38 |
.. function:: diagnostic_file * diagnostic_manager_new_file (diagnostic_manager *diag_mgr, \ |
| 39 |
const char *name, \ |
| 40 |
const char *sarif_source_language) |
| 41 |
|
| 42 |
Create a new :type:`diagnostic_file` for file ``name``. Repeated calls |
| 43 |
with strings that match ``name`` will return the same object. |
| 44 |
|
| 45 |
Both ``diag_mgr`` and ``name`` must be non-NULL. |
| 46 |
|
| 47 |
If ``sarif_source_language`` is non-NULL, it specifies a |
| 48 |
``sourceLanguage`` value for the file for use when writing |
| 49 |
:doc:`SARIF <sarif>` |
| 50 |
(`SARIF v2.1.0 ยง3.24.10 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790871>`_). |
| 51 |
See |
| 52 |
`SARIF v2.1.0 Appendix J <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141791197>`_ |
| 53 |
for suggested values for various programmming languages. |
| 54 |
|
| 55 |
For example, this creates a :type:`diagnostic_file` for ``foo.c`` |
| 56 |
and identifies it as C source code:: |
| 57 |
|
| 58 |
foo_c = diagnostic_manager_new_file (diag_mgr, |
| 59 |
"foo.c", |
| 60 |
"c" /* source_language */); |
| 61 |
|
| 62 |
.. function:: void diagnostic_manager_debug_dump_file (diagnostic_manager *diag_mgr, \ |
| 63 |
const diagnostic_file *file, \ |
| 64 |
FILE *out) |
| 65 |
|
| 66 |
Write a representation of ``file`` to ``out``, for debugging. |
| 67 |
Both ``diag_mgr`` and ``out`` must be non-NULL. |
| 68 |
`file`` may be NULL. |
| 69 |
|
| 70 |
For example:: |
| 71 |
|
| 72 |
diagnostic_manager_debug_dump_file (diag_mgr, foo_c, stderr); |
| 73 |
|
| 74 |
might lead to this output:: |
| 75 |
|
| 76 |
file(name="foo.c", sarif_source_language="c") |
| 77 |
|
| 78 |
.. type:: diagnostic_line_num_t |
| 79 |
|
| 80 |
A :type:`diagnostic_line_num_t` is used for representing line numbers |
| 81 |
within text files. libgdiagnostics treats the first line of a text file |
| 82 |
as line 1. |
| 83 |
|
| 84 |
.. type:: diagnostic_column_num_t |
| 85 |
|
| 86 |
A :type:`diagnostic_column_num_t` is used for representing column numbers |
| 87 |
within text files. libgdiagnostics treats the first column of a text line |
| 88 |
as column 1, **not** column 0. |
| 89 |
|
| 90 |
.. note:: |
| 91 |
|
| 92 |
Both libgdiagnostics and Emacs number source *lines* starting at 1, but |
| 93 |
they have differing conventions for *columns*. |
| 94 |
|
| 95 |
libgdiagnostics uses a 1-based convention for source columns, |
| 96 |
whereas Emacs's ``M-x column-number-mode`` uses a 0-based convention. |
| 97 |
|
| 98 |
For example, an error in the initial, left-hand |
| 99 |
column of source line 3 is reported by libgdiagnostics as:: |
| 100 |
|
| 101 |
some-file.c:3:1: error: ...etc... |
| 102 |
|
| 103 |
On navigating to the location of that error in Emacs |
| 104 |
(e.g. via ``next-error``), |
| 105 |
the locus is reported in the Mode Line |
| 106 |
(assuming ``M-x column-number-mode``) as:: |
| 107 |
|
| 108 |
some-file.c 10% (3, 0) |
| 109 |
|
| 110 |
i.e. ``3:1:`` in libgdiagnostics corresponds to ``(3, 0)`` in Emacs. |
| 111 |
|
| 112 |
.. type:: diagnostic_physical_location |
| 113 |
|
| 114 |
A :type:`diagnostic_physical_location` is an opaque type representing a |
| 115 |
key into a database of source locations within a :type:`diagnostic_manager`. |
| 116 |
|
| 117 |
:type:`diagnostic_physical_location` instances are created by various API |
| 118 |
calls into the :type:`diagnostic_manager` expressing source code points |
| 119 |
and ranges. |
| 120 |
|
| 121 |
They persist until the :type:`diagnostic_manager` is released, which |
| 122 |
cleans them up. |
| 123 |
|
| 124 |
A ``NULL`` value means "unknown", and can be returned by the |
| 125 |
:type:`diagnostic_manager` as a fallback when a problem occurs |
| 126 |
(e.g. too many locations). |
| 127 |
|
| 128 |
A :type:`diagnostic_physical_location` can be a single point within the |
| 129 |
source code, such as here (at the the '"' at the start of the string literal):: |
| 130 |
|
| 131 |
int i = "foo"; |
| 132 |
^ |
| 133 |
|
| 134 |
or be a range with a start and finish, and a "caret" location:: |
| 135 |
|
| 136 |
a = (foo && bar) |
| 137 |
~~~~~^~~~~~~ |
| 138 |
|
| 139 |
where the caret here is at the first "&", and the start and finish |
| 140 |
are at the parentheses. |
| 141 |
|
| 142 |
.. function:: const diagnostic_physical_location *diagnostic_manager_new_location_from_file_and_line (diagnostic_manager *diag_mgr, \ |
| 143 |
const diagnostic_file *file, \ |
| 144 |
diagnostic_line_num_t line_num) |
| 145 |
|
| 146 |
Attempt to create a :type:`diagnostic_physical_location` representing |
| 147 |
``FILENAME:LINE_NUM``, with no column information (thus representing |
| 148 |
the whole of the given line. |
| 149 |
|
| 150 |
Both ``diag_mgr`` and ``file`` must be non-NULL. |
| 151 |
|
| 152 |
.. function:: const diagnostic_physical_location * diagnostic_manager_new_location_from_file_line_column (diagnostic_manager *diag_mgr, \ |
| 153 |
const diagnostic_file *file, \ |
| 154 |
diagnostic_line_num_t line_num, \ |
| 155 |
diagnostic_column_num_t column_num) |
| 156 |
|
| 157 |
Attempt to create a :type:`diagnostic_physical_location` for |
| 158 |
``FILENAME:LINE_NUM:COLUMN_NUM`` representing a particular point |
| 159 |
in the source file. |
| 160 |
|
| 161 |
Both ``diag_mgr`` and ``file`` must be non-NULL. |
| 162 |
|
| 163 |
.. function:: const diagnostic_physical_location *diagnostic_manager_new_location_from_range (diagnostic_manager *diag_mgr,\ |
| 164 |
const diagnostic_physical_location *loc_caret,\ |
| 165 |
const diagnostic_physical_location *loc_start,\ |
| 166 |
const diagnostic_physical_location *loc_end) |
| 167 |
|
| 168 |
Attempt to create a diagnostic_physical_location representing a |
| 169 |
range within a source file, with a highlighted "caret" location. |
| 170 |
|
| 171 |
All must be within the same file, but they can be on different lines. |
| 172 |
|
| 173 |
For example, consider the location of the binary expression below:: |
| 174 |
|
| 175 |
...|__________1111111112222222 |
| 176 |
...|12345678901234567890123456 |
| 177 |
...| |
| 178 |
521|int sum (int foo, int bar) |
| 179 |
522|{ |
| 180 |
523| return foo + bar; |
| 181 |
...| ~~~~^~~~~ |
| 182 |
524|} |
| 183 |
|
| 184 |
The location's caret is at the "+", line 523 column 15, but starts |
| 185 |
earlier, at the "f" of "foo" at column 11. The finish is at the "r" |
| 186 |
of "bar" at column 19. |
| 187 |
|
| 188 |
``diag_mgr`` must be non-NULL. |
| 189 |
|
| 190 |
.. function:: void diagnostic_manager_debug_dump_location (const diagnostic_manager *diag_mgr,\ |
| 191 |
const diagnostic_physical_location *loc, \ |
| 192 |
FILE *out) |
| 193 |
|
| 194 |
Write a representation of ``loc`` to ``out``, for debugging. |
| 195 |
|
| 196 |
Both ``diag_mgr`` and ``out`` must be non-NULL. |
| 197 |
`loc`` may be NULL. |
| 198 |
|
| 199 |
TODO: example of output |
| 200 |
|
| 201 |
.. function:: diagnostic_file *diagnostic_physical_location_get_file (const diagnostic_physical_location *physical_loc) |
| 202 |
|
| 203 |
Get the :type:`diagnostic_file` associated with a given physical location. |
| 204 |
|
| 205 |
|
| 206 |
Associating diagnostics with locations |
| 207 |
************************************** |
| 208 |
|
| 209 |
A :type:`diagnostic` has an optional primary physical location |
| 210 |
and zero or more secondary physical locations. For example:: |
| 211 |
|
| 212 |
a = (foo && bar) |
| 213 |
~~~~~^~~~~~~ |
| 214 |
|
| 215 |
This diagnostic has a single :type:`diagnostic_physical_location`, |
| 216 |
with the caret at the first "&", and the start/finish at the parentheses. |
| 217 |
|
| 218 |
Contrast with:: |
| 219 |
|
| 220 |
a = (foo && bar) |
| 221 |
~~~ ^~ ~~~ |
| 222 |
|
| 223 |
This diagnostic has three locations |
| 224 |
|
| 225 |
* The primary location (at "&&") has its caret and start location at |
| 226 |
the first "&" and end at the second "&. |
| 227 |
|
| 228 |
* The secondary location for "foo" has its start and finish at the "f" |
| 229 |
and "o" of "foo"; the caret is not displayed, but is perhaps at |
| 230 |
the "f" of "foo". |
| 231 |
|
| 232 |
* Similarly, the other secondary location (for "bar") has its start and |
| 233 |
finish at the "b" and "r" of "bar"; the caret is not displayed, but |
| 234 |
is perhaps at the"b" of "bar". |
| 235 |
|
| 236 |
.. function:: void diagnostic_set_location (diagnostic *diag, \ |
| 237 |
const diagnostic_physical_location * loc) |
| 238 |
|
| 239 |
Set the primary location of ``diag``. |
| 240 |
|
| 241 |
``diag`` must be non-NULL; ``loc`` can be NULL. |
| 242 |
|
| 243 |
.. function:: void diagnostic_set_location_with_label (diagnostic *diag, \ |
| 244 |
const diagnostic_physical_location *loc, \ |
| 245 |
const char *fmt, ...) |
| 246 |
|
| 247 |
Set the primary location of ``diag``, with a label. The label is |
| 248 |
formatted as per the rules FIXME |
| 249 |
|
| 250 |
``diag`` and ``fmt`` must be non-NULL; ``loc`` can be NULL. |
| 251 |
|
| 252 |
See :doc:`message-formatting` for details of how to use ``fmt``. |
| 253 |
|
| 254 |
TODO: example of use |
| 255 |
|
| 256 |
.. function:: void diagnostic_add_location (diagnostic *diag, \ |
| 257 |
const diagnostic_physical_location * loc) |
| 258 |
|
| 259 |
Add a secondary location to ``diag``. |
| 260 |
|
| 261 |
``diag`` must be non-NULL; ``loc`` can be NULL. |
| 262 |
|
| 263 |
|
| 264 |
.. function:: void diagnostic_add_location_with_label (diagnostic *diag, \ |
| 265 |
const diagnostic_physical_location *loc, \ |
| 266 |
const char *text) |
| 267 |
|
| 268 |
Add a secondary location to ``diag``, with a label. The label is |
| 269 |
formatted as per the rules FIXME |
| 270 |
|
| 271 |
``diag`` and ``fmt`` must be non-NULL; ``loc`` can be NULL. |
| 272 |
|
| 273 |
For example, |
| 274 |
|
| 275 |
.. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-labelled-ranges.c |
| 276 |
:language: c |
| 277 |
:start-after: /* begin quoted source */ |
| 278 |
:end-before: /* end quoted source */ |
| 279 |
|
| 280 |
might give this text output:: |
| 281 |
|
| 282 |
test-labelled-ranges.c:9:6: error: mismatching types: 'int' and 'const char *' |
| 283 |
19 | 42 + "foo" |
| 284 |
| ~~ ^ ~~~~~ |
| 285 |
| | | |
| 286 |
| int const char * |