| 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. |