GCC Middle and Back End API Reference
markup.h
Go to the documentation of this file.
1/* A tree-like representation for use when building diagnostic messages.
2 Copyright (C) 2026 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
8under the terms of the GNU General Public License as published by
9the Free Software Foundation; either version 3, or (at your option)
10any later version.
11
12GCC is distributed in the hope that it will be useful, but
13WITHOUT ANY WARRANTY; without even the implied warranty of
14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15General Public License for 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_MARKUP_H
22#define GCC_DIAGNOSTICS_MARKUP_H
23
24#include "selftest.h"
26
27namespace diagnostics {
28namespace markup {
29
30struct lowering_options;
31
32/* Indentation shows inheritance hierarchy. */
33class node;
34 class text;
35 class unary_node;
36 namespace math { class negation; }
37 class binary_node;
38 namespace math { class subtraction; }
39 namespace code { class element_expr; }
40 namespace code { class field_expr; }
41 namespace code { class infix_binary_op; }
42 class compound_node;
43 namespace math { class associative_op; }
44 namespace math { class sum; }
45 namespace math { class product; }
46 class inline_code;
47
64
65/* Abstract base class for representing text we might want to put
66 in a diagnostic as an AST.
67
68 Ideally eventually we could lower this in sink-specific ways
69 e.g. text, markdown for SARIF, HTML, etc,
70 but that's overkill for now.
71
72 For now, all we need is enough for labels in the analyzer's access diagrams
73 to work. */
74
75class node
76{
77public:
78 virtual ~node () = default;
79
80 virtual const char *
81 get_class_name () const = 0;
82
83 virtual kind
84 get_kind () const = 0;
85
86 virtual void
87 print_to_pp (pretty_printer *pp) const = 0;
88
89 void
90 dump () const;
91
92 virtual std::unique_ptr<text_art::tree_widget>
94
95 virtual const text *
96 dyn_cast_text () const { return nullptr; }
97
98 virtual const compound_node *
99 dyn_cast_compound_node () const { return nullptr; }
100
101 virtual const math::associative_op *
102 dyn_cast_math_associative_op () const { return nullptr; }
103
104 virtual math::negation *
105 dyn_cast_math_negation () { return nullptr; }
106
107 virtual std::unique_ptr<node>
108 lower (const lowering_options &opts) const = 0;
109};
110
111/* Concrete node subclass for a fully-lowered text string. */
112
113class text : public node
114{
115public:
116 text (std::string str) : m_str (std::move (str))
117 {
118 }
119
120 const char *
121 get_class_name () const final override { return "text"; }
122
123 kind
124 get_kind () const final override { return kind::text; }
125
126 void
127 print_to_pp (pretty_printer *pp) const final override;
128
129 std::unique_ptr<text_art::tree_widget>
130 make_dump_widget (text_art::dump_widget_info &dwi) const final override;
131
132 const text *
133 dyn_cast_text () const final override { return this; }
134
135 std::unique_ptr<node>
136 lower (const lowering_options &opts) const final override;
137
138 const std::string &
139 get_string () const { return m_str; }
140
141private:
142 std::string m_str;
143};
144
145
146/* Abstract subclass for nodes that have a single child. */
147
148class unary_node : public node
149{
150public:
151 void
152 print_to_pp (pretty_printer *pp) const final override;
153
154 std::unique_ptr<text_art::tree_widget>
155 make_dump_widget (text_art::dump_widget_info &dwi) const final override;
156
157 const node &
158 get_operand () const
159 {
160 return *m_operand;
161 }
162
163 std::unique_ptr<node>
165 {
166 return std::move (m_operand);
167 }
168
169protected:
170 unary_node (std::unique_ptr<node> operand)
171 : m_operand (std::move (operand))
172 {
174 }
175
176private:
177 std::unique_ptr<node> m_operand;
178};
179
180/* Abstract subclass for nodes that have two children. */
181
182class binary_node : public node
183{
184public:
185 void
186 print_to_pp (pretty_printer *pp) const final override;
187
188 std::unique_ptr<text_art::tree_widget>
189 make_dump_widget (text_art::dump_widget_info &dwi) const final override;
190
191 const node &
193 {
194 return *m_op0;
195 }
196
197 const node &
199 {
200 return *m_op1;
201 }
202
203protected:
204 binary_node (std::unique_ptr<node> op0,
205 std::unique_ptr<node> op1)
206 : m_op0 (std::move (op0)),
207 m_op1 (std::move (op1))
208 {
209 }
210
211private:
212 std::unique_ptr<node> m_op0;
213 std::unique_ptr<node> m_op1;
214};
215
216/* Concrete subclass for nodes that have an arbitrary number of children. */
217
218class compound_node : public node
219{
220public:
222
223 compound_node (std::vector<std::unique_ptr<node>> children)
224 : m_children (std::move (children))
225 {
226 }
227
228 const char *
229 get_class_name () const { return "compound_node"; }
230
231 kind
232 get_kind () const override { return kind::compound; }
233
234 void
235 print_to_pp (pretty_printer *pp) const override;
236
237 std::unique_ptr<text_art::tree_widget>
238 make_dump_widget (text_art::dump_widget_info &dwi) const final override;
239
240 const compound_node *
241 dyn_cast_compound_node () const final override { return this; }
242
243 std::unique_ptr<node>
244 lower (const lowering_options &opts) const override;
245
246 void
247 add_child (std::unique_ptr<node> child)
248 {
249 gcc_assert (child);
250 m_children.push_back (std::move (child));
251 }
252
253 void
254 add_child (std::string str);
255
256 size_t
257 get_num_children () const { return m_children.size (); }
258
259 const node &
260 get_child (size_t idx) const { return *m_children[idx]; }
261
262private:
263 std::vector<std::unique_ptr<node>> m_children;
264};
265
266namespace math {
267
268/* Abstract subclass for nodes that represent an associative sequence
269 of infix binary operations. */
270
272{
273public:
274 const associative_op *
275 dyn_cast_math_associative_op () const final override { return this; }
276
277 std::unique_ptr<node>
278 lower (const lowering_options &opts) const final override;
279
280 virtual const char *
281 get_symbol (bool use_unicode) const = 0;
282
283protected:
285 : compound_node ()
286 {
287 }
288
289 associative_op (std::vector<std::unique_ptr<node>> operands)
290 : compound_node (std::move (operands))
291 {
292 }
293};
294
295/* Concrete node subclass for a mathematical sum.
296 The children are the addends; there can be more than 2. */
297
298class sum : public associative_op
299{
300public:
302
303 sum (std::vector<std::unique_ptr<node>> addends)
304 : associative_op (std::move (addends))
305 {
306 }
307
308 const char *
309 get_class_name () const final override
310 {
311 return "math::sum";
312 }
313
314 kind
315 get_kind () const final override { return kind::math_sum; }
316
317 const char *
318 get_symbol (bool use_unicode) const final override;
319};
320
321/* Concrete node subclass for a mathematical product.
322 The children are the multiplicands; there can be more than 2. */
323
325{
326public:
328
329 product (std::vector<std::unique_ptr<node>> multiplicands)
330 : associative_op (std::move (multiplicands))
331 {
332 }
333
334 const char *
335 get_class_name () const final override
336 {
337 return "math::product";
338 }
339
340 kind
341 get_kind () const final override { return kind::math_product; }
342
343 const char *
344 get_symbol (bool use_unicode) const final override;
345};
346
347/* Concrete node subclass for mathematical unary negation. */
348
349class negation : public unary_node
350{
351public:
352 negation (std::unique_ptr<node> operand) : unary_node (std::move (operand)) {}
353
354 negation *
355 dyn_cast_math_negation () final override { return this; }
356
357 const char *
358 get_class_name () const final override
359 {
360 return "math::negation";
361 }
362
363 kind
364 get_kind () const final override { return kind::math_negation; }
365
366 std::unique_ptr<node>
367 lower (const lowering_options &opts) const final override;
368};
369
370/* Concrete node subclass for mathematical subtraction. */
371
373{
374public:
375 subtraction (std::unique_ptr<node> op0,
376 std::unique_ptr<node> op1)
377 : binary_node (std::move (op0),
378 std::move (op1))
379 {
380 }
381
382 const char *
383 get_class_name () const { return "math::subtraction"; }
384
385 kind
386 get_kind () const final override { return kind::math_subtraction; }
387
388 std::unique_ptr<node>
389 lower (const lowering_options &opts) const final override;
390};
391
392/* Concrete node subclass for a half-open interval
393 of the form [start, end). */
394
396{
397public:
398 half_open_interval (std::unique_ptr<node> start,
399 std::unique_ptr<node> next)
400 : binary_node (std::move (start),
401 std::move (next))
402 {
403 }
404
405 const char *
406 get_class_name () const final override
407 {
408 return "math::half_open_interval";
409 }
410
411 kind
412 get_kind () const final override { return kind::math_half_open_interval; }
413
414 std::unique_ptr<node>
415 lower (const lowering_options &opts) const final override;
416};
417
418} // namespace diagnostics::markup::math
419
420namespace code {
421
423{
424public:
425 element_expr (std::unique_ptr<node> array_node,
426 std::unique_ptr<node> index_node)
427 : binary_node (std::move (array_node), std::move (index_node))
428 {
429 }
430
431 const char *
432 get_class_name () const final override
433 {
434 return "code::element_expr";
435 }
436
437 kind
438 get_kind () const final override { return kind::code_element_expr; }
439
440 std::unique_ptr<node>
441 lower (const lowering_options &opts) const final override;
442};
443
445{
446public:
447 field_expr (std::unique_ptr<node> struct_or_union_node,
448 std::unique_ptr<node> field_node)
449 : binary_node (std::move (struct_or_union_node), std::move (field_node))
450 {
451 }
452
453 const char *
454 get_class_name () const final override
455 {
456 return "code::field_expr";
457 }
458
459 kind
460 get_kind () const final override { return kind::code_field_expr; }
461
462 std::unique_ptr<node>
463 lower (const lowering_options &opts) const final override;
464};
465
467{
468public:
469 infix_binary_op (std::unique_ptr<node> op0,
470 const char *symbol,
471 std::unique_ptr<node> op1)
472 : binary_node (std::move (op0), std::move (op1)),
473 m_symbol (symbol)
474 {
475 }
476
477 const char *
478 get_class_name () const final override
479 {
480 return "code::infix_binary_op";
481 }
482
483 kind
484 get_kind () const final override { return kind::code_infix_binary_op; }
485
486 std::unique_ptr<node>
487 lower (const lowering_options &opts) const final override;
488
489private:
490 const char *m_symbol;
491};
492
493} // namespace diagnostics::markup::code
494
495/* Concrete subclass for a run of inline code within text.
496 Adds quotes around its children when printed. */
497
499{
500public:
502
503 inline_code (std::unique_ptr<node> child)
504 : compound_node {}
505 {
506 add_child (std::move (child));
507 }
508
509 const char *
510 get_class_name () const final override
511 {
512 return "inline_code";
513 }
514
515 kind
516 get_kind () const final override { return kind::inline_code; }
517
518 void
519 print_to_pp (pretty_printer *pp) const override;
520
521 std::unique_ptr<node>
522 lower (const lowering_options &opts) const final override;
523};
524
525/* Helpers for making nodes. */
526
527inline std::unique_ptr<text>
528make_text_node (std::string str)
529{
530 return std::make_unique<text> (std::move (str));
531}
532
533/* Lowering. */
534
544
545} // namespace diagnostics::markup
546
547#if CHECKING_P
548
549namespace selftest {
550
551/* Implementation detail of ASSERT_SYMBOL_MARKUP_TEXT_EQ. */
552
553void
554assert_markup_text_eq (const ::selftest::location &loc,
555 const markup::node &,
557 const char *expected_str);
558
559/* Assert that MARKUP_NODE lowered to plain text is EXPECTED_STR. */
560
561#define ASSERT_MARKUP_TEXT_EQ_AT(LOC, MARKUP_NODE, LOWERING_OPTS, EXPECTED_STR) \
562 SELFTEST_BEGIN_STMT \
563 ::diagnostics::selftest::assert_markup_text_eq \
564 (LOC, (MARKUP_NODE), \
565 (LOWERING_OPTS), (EXPECTED_STR)); \
566 SELFTEST_END_STMT
567
568#define ASSERT_MARKUP_TEXT_EQ(MARKUP_NODE, LOWERING_OPTS, EXPECTED_STR) \
569 SELFTEST_BEGIN_STMT \
570 ::diagnostics::selftest::assert_markup_text_eq \
571 (SELFTEST_LOCATION, (MARKUP_NODE), \
572 (LOWERING_OPTS), (EXPECTED_STR)); \
573 SELFTEST_END_STMT
574
576get_ascii_markup_opts ();
577
579get_unicode_markup_opts ();
580
581} // namespace diagnostics::selftest
582
583#endif /* #if CHECKING_P */
584
585} // namespace diagnostics
586
587/* Various string literals for unicode symbols. */
588
589/* "−": U+2212: MINUS SIGN. */
590#define MARKUP_UNICODE_SYMBOL_UNARY_NEGATION "\u2212"
591#define MARKUP_UNICODE_SYMBOL_SUBTRACTION "\u2212"
592
593/* "×: U+00D7 MULTIPLICATION SIGN. */
594#define MARKUP_UNICODE_SYMBOL_MULTIPLICATION "\u00D7"
595
596#endif /* GCC_DIAGNOSTICS_MARKUP_H */
Definition markup.h:183
binary_node(std::unique_ptr< node > op0, std::unique_ptr< node > op1)
Definition markup.h:204
const node & get_operand_1() const
Definition markup.h:198
std::unique_ptr< text_art::tree_widget > make_dump_widget(text_art::dump_widget_info &dwi) const final override
Definition markup.cc:222
std::unique_ptr< node > m_op1
Definition markup.h:213
void print_to_pp(pretty_printer *pp) const final override
Definition markup.cc:211
std::unique_ptr< node > m_op0
Definition markup.h:212
const node & get_operand_0() const
Definition markup.h:192
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:331
const char * get_class_name() const final override
Definition markup.h:432
kind get_kind() const final override
Definition markup.h:438
element_expr(std::unique_ptr< node > array_node, std::unique_ptr< node > index_node)
Definition markup.h:425
kind get_kind() const final override
Definition markup.h:460
const char * get_class_name() const final override
Definition markup.h:454
field_expr(std::unique_ptr< node > struct_or_union_node, std::unique_ptr< node > field_node)
Definition markup.h:447
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:344
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:356
infix_binary_op(std::unique_ptr< node > op0, const char *symbol, std::unique_ptr< node > op1)
Definition markup.h:469
kind get_kind() const final override
Definition markup.h:484
const char * get_class_name() const final override
Definition markup.h:478
const char * m_symbol
Definition markup.h:490
Definition markup.h:219
void print_to_pp(pretty_printer *pp) const override
Definition markup.cc:147
size_t get_num_children() const
Definition markup.h:257
std::vector< std::unique_ptr< node > > m_children
Definition markup.h:263
std::unique_ptr< text_art::tree_widget > make_dump_widget(text_art::dump_widget_info &dwi) const final override
Definition markup.cc:154
const node & get_child(size_t idx) const
Definition markup.h:260
const compound_node * dyn_cast_compound_node() const final override
Definition markup.h:241
void add_child(std::unique_ptr< node > child)
Definition markup.h:247
const char * get_class_name() const
Definition markup.h:229
std::unique_ptr< node > lower(const lowering_options &opts) const override
Definition markup.cc:168
compound_node()
Definition markup.h:221
kind get_kind() const override
Definition markup.h:232
compound_node(std::vector< std::unique_ptr< node > > children)
Definition markup.h:223
Definition markup.h:499
const char * get_class_name() const final override
Definition markup.h:510
void print_to_pp(pretty_printer *pp) const override
Definition markup.cc:371
inline_code()
Definition markup.h:501
inline_code(std::unique_ptr< node > child)
Definition markup.h:503
kind get_kind() const final override
Definition markup.h:516
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:379
virtual const char * get_symbol(bool use_unicode) const =0
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:238
associative_op(std::vector< std::unique_ptr< node > > operands)
Definition markup.h:289
const associative_op * dyn_cast_math_associative_op() const final override
Definition markup.h:275
associative_op()
Definition markup.h:284
const char * get_class_name() const final override
Definition markup.h:406
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:316
half_open_interval(std::unique_ptr< node > start, std::unique_ptr< node > next)
Definition markup.h:398
kind get_kind() const final override
Definition markup.h:412
kind get_kind() const final override
Definition markup.h:364
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:283
const char * get_class_name() const final override
Definition markup.h:358
negation * dyn_cast_math_negation() final override
Definition markup.h:355
negation(std::unique_ptr< node > operand)
Definition markup.h:352
Definition markup.h:325
product()
Definition markup.h:327
kind get_kind() const final override
Definition markup.h:341
const char * get_symbol(bool use_unicode) const final override
Definition markup.cc:272
const char * get_class_name() const final override
Definition markup.h:335
product(std::vector< std::unique_ptr< node > > multiplicands)
Definition markup.h:329
kind get_kind() const final override
Definition markup.h:386
subtraction(std::unique_ptr< node > op0, std::unique_ptr< node > op1)
Definition markup.h:375
const char * get_class_name() const
Definition markup.h:383
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:297
Definition markup.h:299
kind get_kind() const final override
Definition markup.h:315
const char * get_symbol(bool use_unicode) const final override
Definition markup.cc:264
sum()
Definition markup.h:301
sum(std::vector< std::unique_ptr< node > > addends)
Definition markup.h:303
const char * get_class_name() const final override
Definition markup.h:309
Definition markup.h:76
virtual const math::associative_op * dyn_cast_math_associative_op() const
Definition markup.h:102
virtual const text * dyn_cast_text() const
Definition markup.h:96
virtual std::unique_ptr< node > lower(const lowering_options &opts) const =0
virtual void print_to_pp(pretty_printer *pp) const =0
virtual std::unique_ptr< text_art::tree_widget > make_dump_widget(text_art::dump_widget_info &dwi) const =0
virtual kind get_kind() const =0
void dump() const
Definition markup.cc:114
virtual const compound_node * dyn_cast_compound_node() const
Definition markup.h:99
virtual math::negation * dyn_cast_math_negation()
Definition markup.h:105
virtual const char * get_class_name() const =0
virtual ~node()=default
Definition markup.h:114
void print_to_pp(pretty_printer *pp) const final override
Definition markup.cc:126
std::unique_ptr< text_art::tree_widget > make_dump_widget(text_art::dump_widget_info &dwi) const final override
Definition markup.cc:132
const std::string & get_string() const
Definition markup.h:139
kind get_kind() const final override
Definition markup.h:124
text(std::string str)
Definition markup.h:116
std::unique_ptr< node > lower(const lowering_options &opts) const final override
Definition markup.cc:139
std::string m_str
Definition markup.h:142
const char * get_class_name() const final override
Definition markup.h:121
const text * dyn_cast_text() const final override
Definition markup.h:133
Definition markup.h:149
std::unique_ptr< text_art::tree_widget > make_dump_widget(text_art::dump_widget_info &dwi) const final override
Definition markup.cc:196
void print_to_pp(pretty_printer *pp) const final override
Definition markup.cc:187
const node & get_operand() const
Definition markup.h:158
std::unique_ptr< node > m_operand
Definition markup.h:177
std::unique_ptr< node > take_operand()
Definition markup.h:164
unary_node(std::unique_ptr< node > operand)
Definition markup.h:170
Definition genmatch.cc:1599
Definition pretty-print.h:241
void final(rtx_insn *first, FILE *file, int optimize_p)
Definition final.cc:2004
Definition custom-sarif-properties/state-graphs.h:33
Definition markup.h:39
Definition markup.h:36
Definition common.h:50
std::unique_ptr< text > make_text_node(std::string str)
Definition markup.h:528
kind
Definition markup.h:48
@ text
Definition markup.h:49
@ inline_code
Definition markup.h:62
@ math_sum
Definition markup.h:56
@ code_field_expr
Definition markup.h:59
@ math_half_open_interval
Definition markup.h:52
@ code_infix_binary_op
Definition markup.h:60
@ compound
Definition markup.h:50
@ math_negation
Definition markup.h:53
@ code_element_expr
Definition markup.h:58
@ math_product
Definition markup.h:54
@ math_subtraction
Definition markup.h:55
Definition cfghooks.h:26
Definition dump-context.h:31
lowering_options()
Definition markup.h:537
bool m_use_unicode_symbols
Definition markup.h:542
Definition ira-emit.cc:158
Definition dump-widget-info.h:31
#define gcc_assert(EXPR)
Definition system.h:772
#define false
Definition system.h:846