Debian Codegraph @

gcc/doc/libgdiagnostics/topics/logical-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 Logical locations
21 =================
22
23 A "logical" location is a location expressed in terms of
24 construct in a programming language, such as ``within function 'foo'``
25 (as opposed to a :doc:`"physical" location <physical-locations>`, which
26 refers to a specific file, and line(s) and/or column(s))
27
28 Creating location information
29 *****************************
30
31 .. type:: diagnostic_logical_location
32
33 A :type:`diagnostic_logical_location` is an opaque type describing a "logical"
34 source location
35
36 .. function:: const diagnostic_logical_location * diagnostic_manager_new_logical_location (diagnostic_manager *diag_mgr, \
37 enum diagnostic_logical_location_kind_t kind, \
38 const diagnostic_logical_location *parent, \
39 const char *short_name, \
40 const char *fully_qualified_name, \
41 const char *decorated_name)
42
43 Create a :type:`diagnostic_logical_location`.
44
45 ``diag_mgr`` must be non-NULL.
46
47 ``kind`` describes the kind of logical location:
48
49 .. enum:: diagnostic_logical_location_kind_t
50
51 This roughly corresponds to the ``kind`` property in SARIF v2.1.0
52 (`§3.33.7 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790976>`_).
53
54 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_FUNCTION
55
56 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_MEMBER
57
58 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_MODULE
59
60 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_NAMESPACE
61
62 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_TYPE
63
64 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_RETURN_TYPE
65
66 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_PARAMETER
67
68 .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_VARIABLE
69
70 ``parent`` can be NULL; if non-NULL it can be used to express tree-like
71 nesting of logical locations, such as in::
72
73 namespace foo { namespace bar { class baz { baz (); }; } }
74
75 where a diagnostic within ``baz``'s constructor could be reported
76 as being within ``foo::bar::baz::baz`` where the logical locations
77 are two namespaces, a type, and a member, respectively.
78
79 ``short_name`` can be NULL, or else a string suitable for use by
80 the SARIF logicalLocation ``name`` property
81 (SARIF v2.1.0 `§3.33.4 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790973>`_).
82
83 ``fully_qualified_name`` can be NULL or else a string suitable for use by
84 the SARIF logicalLocation ``fullyQualifiedName`` property
85 (SARIF v2.1.0 `§3.33.5 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790974>`_).
86
87 ``decorated_name`` can be NULL or else a string suitable for use by
88 the SARIF logicalLocation ``decoratedName`` property
89 (SARIF v2.1.0 `§3.33.6 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790975>`_).
90
91 Repeated calls to :func:`diagnostic_manager_new_logical_location` with
92 "equal" input values on the same :type:`diagnostic_manager` will return
93 the same instance of :type:`diagnostic_logical_location`. "Equal" here
94 includes different string buffers that compare as equal with
95 :func:``strcmp`.
96
97 .. function:: void diagnostic_manager_debug_dump_logical_location (const diagnostic_manager *diag_mgr, \
98 const diagnostic_logical_location *loc, \
99 FILE *out)
100
101 Write a representation of ``file`` to ``out``, for debugging.
102 Both ``diag_mgr`` and ``out`` must be non-NULL.
103 ``file`` may be NULL.
104
105 TODO: example of output
106
107 Associating diagnostics with locations
108 **************************************
109
110 .. function:: void diagnostic_set_logical_location (diagnostic *diag, \
111 const diagnostic_logical_location *logical_loc)
112
113 Set the logical location of ``diag``.
114
115 ``diag`` must be non-NULL; ``logical_loc`` can be NULL.