GCC Middle and Back End API Reference
logical-locations.h
Go to the documentation of this file.
1/* Logical location support, without knowledge of "tree".
2 Copyright (C) 2022-2025 Free Software Foundation, Inc.
3 Contributed by David Malcolm <dmalcolm@redhat.com>.
4
5This file is part of GCC.
6
7GCC is free software; you can redistribute it and/or modify it under
8the terms of the GNU General Public License as published by the Free
9Software Foundation; either version 3, or (at your option) any later
10version.
11
12GCC is distributed in the hope that it will be useful, but WITHOUT ANY
13WARRANTY; without even the implied warranty of MERCHANTABILITY or
14FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15for more details.
16
17You should have received a copy of the GNU General Public License
18along with GCC; see the file COPYING3. If not see
19<http://www.gnu.org/licenses/>. */
20
21#ifndef GCC_DIAGNOSTICS_LOGICAL_LOCATIONS_H
22#define GCC_DIAGNOSTICS_LOGICAL_LOCATIONS_H
23
24#include "label-text.h"
25
26namespace diagnostics {
27namespace logical_locations {
28
29/* An enum for discriminating between different kinds of logical location
30 for a diagnostic.
31
32 Roughly corresponds to logicalLocation's "kind" property in SARIF v2.1.0
33 (section 3.33.7). */
34
35enum class kind
36{
38
39 /* Kinds within executable code. */
48
49 /* Kinds within XML or HTML documents. */
57
58 /* Kinds within JSON documents. */
63};
64
65/* We want to efficiently support passing around logical locations in the
66 diagnostics subsystem, such as:
67 - "within function 'foo'", or
68 - "within method 'bar'"
69
70 However we want to do this *without* requiring knowledge of trees (or of
71 libgdiagnostics internals), and without requiring heap allocation of an
72 interface class when emitting a diagnostic.
73
74 To do this, we split the implementation into logical_locations::key, which is
75 a wrapper around a (const void *), and logical_locations::manager which
76 is provided by the client and has vfunc hooks for interpreting
77 key instances.
78
79 Every logical_locations::key is associated with a logical_locations::manager
80 and only has meaning in relation to that manager.
81
82 A "nullptr" within a key means "no logical location".
83
84 See tree-logical-location.h for concrete subclasses relating to trees,
85 where the pointer is a const_tree.
86
87 See diagnostics/selftest-logical-locations.h for a concrete subclass for
88 selftests. */
89
90/* Extrinsic state for identifying a specific logical location.
91 This will be our logical location type.
92 This only makes sense with respect to a specific manager.
93 e.g. for a tree-based one it's a wrapper around "tree".
94
95 "nullptr" means "no logical location".
96
97 Note that there is no integration with GCC's garbage collector and thus
98 keys can't be long-lived. */
99
100class key
101{
102public:
103 key () : m_ptr (nullptr) {}
104
105 static key from_ptr (const void *ptr)
106 {
107 return key (ptr);
108 }
109
110 operator bool () const
111 {
112 return m_ptr != nullptr;
113 }
114
115 template <typename T>
116 T cast_to () const { return static_cast<T> (m_ptr); }
117
118 bool
119 operator== (const key &other) const
120 {
121 return m_ptr == other.m_ptr;
122 }
123
124 bool
125 operator!= (const key &other) const
126 {
127 return m_ptr != other.m_ptr;
128 }
129
130 bool
131 operator< (const key &other) const
132 {
133 return m_ptr < other.m_ptr;
134 }
135
136private:
137 explicit key (const void *ptr) : m_ptr (ptr) {}
138
139 const void *m_ptr;
140};
141
142/* Abstract base class for giving meaning to keys.
143 Typically there will just be one client-provided instance, of a
144 client-specific subclass. */
145
147{
148public:
149 virtual ~manager () {}
150
151 /* vfuncs for interpreting keys. */
152
153 /* Get a string (or NULL) for K suitable for use by the SARIF logicalLocation
154 "name" property (SARIF v2.1.0 section 3.33.4). */
155 virtual const char *get_short_name (key k) const = 0;
156
157 /* Get a string (or NULL) for K suitable for use by the SARIF logicalLocation
158 "fullyQualifiedName" property (SARIF v2.1.0 section 3.33.5). */
159 virtual const char *get_name_with_scope (key k) const = 0;
160
161 /* Get a string (or NULL) for K suitable for use by the SARIF logicalLocation
162 "decoratedName" property (SARIF v2.1.0 section 3.33.6). */
163 virtual const char *get_internal_name (key k) const = 0;
164
165 /* Get what kind of SARIF logicalLocation K is (if any). */
166 virtual enum kind get_kind (key k) const = 0;
167
168 /* Get a string for location K in a form suitable for path output. */
169 virtual label_text get_name_for_path_output (key k) const = 0;
170
171 /* Get the parent logical_logical of K, if any, or nullptr. */
172 virtual key get_parent (key k) const = 0;
173
174 bool function_p (key k) const;
175};
176
177} // namespace diagnostics::logical_locations
178} // namespace diagnostics
179
180#endif /* GCC_DIAGNOSTICS_LOGICAL_LOCATIONS_H. */
Definition logical-locations.h:101
T cast_to() const
Definition logical-locations.h:116
bool operator==(const key &other) const
Definition logical-locations.h:119
bool operator!=(const key &other) const
Definition logical-locations.h:125
key()
Definition logical-locations.h:103
const void * m_ptr
Definition logical-locations.h:139
static key from_ptr(const void *ptr)
Definition logical-locations.h:105
key(const void *ptr)
Definition logical-locations.h:137
bool operator<(const key &other) const
Definition logical-locations.h:131
Definition logical-locations.h:147
virtual label_text get_name_for_path_output(key k) const =0
virtual const char * get_short_name(key k) const =0
virtual const char * get_internal_name(key k) const =0
virtual const char * get_name_with_scope(key k) const =0
bool function_p(key k) const
Definition diagnostics/context.cc:1081
virtual enum kind get_kind(key k) const =0
virtual ~manager()
Definition logical-locations.h:149
virtual key get_parent(key k) const =0
static struct token T
Definition gengtype-parse.cc:45
Definition diagnostics/context.h:41
kind
Definition logical-locations.h:36
@ parameter
Definition logical-locations.h:46
@ comment
Definition logical-locations.h:53
@ property
Definition logical-locations.h:61
@ declaration
Definition logical-locations.h:56
@ text
Definition logical-locations.h:52
@ value
Definition logical-locations.h:62
@ module_
Definition logical-locations.h:42
@ return_type
Definition logical-locations.h:45
@ processing_instruction
Definition logical-locations.h:54
@ type
Definition logical-locations.h:44
@ dtd
Definition logical-locations.h:55
@ element
Definition logical-locations.h:50
@ namespace_
Definition logical-locations.h:43
@ object
Definition logical-locations.h:59
@ member
Definition logical-locations.h:41
@ unknown
Definition logical-locations.h:37
@ function
Definition logical-locations.h:40
@ attribute
Definition logical-locations.h:51
@ variable
Definition logical-locations.h:47
@ array
Definition logical-locations.h:60
Definition coretypes.h:167
#define bool
Definition system.h:886