Debian Codegraph @

gcc/doc/libgdiagnostics/topics/physical-locations.rst

raw
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 *