1 /* Various declarations for language-independent pretty-print subroutines.
2 Copyright (C) 2002-2024 Free Software Foundation, Inc.
3 Contributed by Gabriel Dos Reis <gdr@integrable-solutions.net>
5 This file is part of GCC.
7 GCC is free software; you can redistribute it and/or modify it under
8 the terms of the GNU General Public License as published by the Free
9 Software Foundation; either version 3, or (at your option) any later
12 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 You should have received a copy of the GNU General Public License
18 along with GCC; see the file COPYING3. If not see
19 <http://www.gnu.org/licenses/>. */
21 #ifndef GCC_PRETTY_PRINT_H
22 #define GCC_PRETTY_PRINT_H
25 #include "rich-location.h"
26 #include "diagnostic-url.h"
28 /* Maximum number of format string arguments. */
29 #define PP_NL_ARGMAX 30
31 /* The type of a text to be formatted according a format specification
32 along with a list of things. */
35 text_info () = default;
36 text_info (const char *format_spec
,
39 void **data
= nullptr,
40 rich_location
*rich_loc
= nullptr)
41 : m_format_spec (format_spec
),
42 m_args_ptr (args_ptr
),
49 void set_location (unsigned int idx
, location_t loc
,
50 enum range_display_kind range_display_kind
);
51 location_t
get_location (unsigned int index_of_location
) const;
53 const char *m_format_spec
;
55 int m_err_no
; /* for %m */
57 rich_location
*m_richloc
;
60 /* How often diagnostics are prefixed by their locations:
61 o DIAGNOSTICS_SHOW_PREFIX_NEVER: never - not yet supported;
62 o DIAGNOSTICS_SHOW_PREFIX_ONCE: emit only once;
63 o DIAGNOSTICS_SHOW_PREFIX_EVERY_LINE: emit each time a physical
65 enum diagnostic_prefixing_rule_t
67 DIAGNOSTICS_SHOW_PREFIX_ONCE
= 0x0,
68 DIAGNOSTICS_SHOW_PREFIX_NEVER
= 0x1,
69 DIAGNOSTICS_SHOW_PREFIX_EVERY_LINE
= 0x2
76 /* The chunk_info data structure forms a stack of the results from the
77 first phase of formatting (pp_format) which have not yet been
78 output (pp_output_formatted_text). A stack is necessary because
79 the diagnostic starter may decide to generate its own output by way
83 friend class pretty_printer
;
86 const char * const *get_args () const { return m_args
; }
87 quoting_info
*get_quoting_info () const { return m_quotes
; }
89 void append_formatted_chunk (const char *content
);
91 void pop_from_output_buffer (output_buffer
&buf
);
94 void on_begin_quote (const output_buffer
&buf
,
96 const urlifier
*urlifier
);
98 void on_end_quote (pretty_printer
*pp
,
101 const urlifier
*urlifier
);
103 /* Pointer to previous chunk on the stack. */
106 /* Array of chunks to output. Each chunk is a NUL-terminated string.
107 In the first phase of formatting, even-numbered chunks are
108 to be output verbatim, odd-numbered chunks are format specifiers.
109 The second phase replaces all odd-numbered chunks with formatted
110 text, and the third phase simply emits all the chunks in sequence
111 with appropriate line-wrapping. */
112 const char *m_args
[PP_NL_ARGMAX
* 2];
114 /* If non-null, information on quoted text runs within the chunks
115 for use by a urlifier. */
116 quoting_info
*m_quotes
;
119 /* The output buffer datatype. This is best seen as an abstract datatype
120 whose fields should not be accessed directly by clients. */
127 /* Obstack where the text is built up. */
128 struct obstack formatted_obstack
;
130 /* Obstack containing a chunked representation of the format
131 specification plus arguments. */
132 struct obstack chunk_obstack
;
134 /* Currently active obstack: one of the above two. This is used so
135 that the text formatters don't need to know which phase we're in. */
136 struct obstack
*obstack
;
138 /* Stack of chunk arrays. These come from the chunk_obstack. */
139 chunk_info
*cur_chunk_array
;
141 /* Where to output formatted text. */
144 /* The amount of characters output so far. */
147 /* This must be large enough to hold any printed integer or
148 floating-point value. */
149 char digit_buffer
[128];
151 /* Nonzero means that text should be flushed when
152 appropriate. Otherwise, text is buffered until either
153 pp_really_flush or pp_clear_output_area are called. */
157 /* Finishes constructing a NULL-terminated character string representing
158 the buffered text. */
160 output_buffer_formatted_text (output_buffer
*buff
)
162 obstack_1grow (buff
->obstack
, '\0');
163 return (const char *) obstack_base (buff
->obstack
);
166 /* Append to the output buffer a string specified by its
167 STARTing character and LENGTH. */
169 output_buffer_append_r (output_buffer
*buff
, const char *start
, int length
)
171 gcc_checking_assert (start
);
172 obstack_grow (buff
->obstack
, start
, length
);
173 for (int i
= 0; i
< length
; i
++)
174 if (start
[i
] == '\n')
175 buff
->line_length
= 0;
180 /* Return a pointer to the last character emitted in the
181 output_buffer. A NULL pointer means no character available. */
183 output_buffer_last_position_in_text (const output_buffer
*buff
)
185 const char *p
= NULL
;
186 struct obstack
*text
= buff
->obstack
;
188 if (obstack_base (text
) != obstack_next_free (text
))
189 p
= ((const char *) obstack_next_free (text
)) - 1;
194 /* The type of pretty-printer flags passed to clients. */
195 typedef unsigned int pp_flags
;
199 pp_none
, pp_before
, pp_after
202 /* Structure for switching in and out of verbatim mode in a convenient
204 struct pp_wrapping_mode_t
206 /* Current prefixing rule. */
207 diagnostic_prefixing_rule_t rule
;
209 /* The ideal upper bound of number of characters per line, as suggested
214 /* The type of a hook that formats client-specific data onto a pretty_printer.
215 A client-supplied formatter returns true if everything goes well,
216 otherwise it returns false. */
217 typedef bool (*printer_fn
) (pretty_printer
*, text_info
*, const char *,
218 int, bool, bool, bool, bool *, const char **);
220 /* Base class for an optional client-supplied object for doing additional
221 processing between stages 2 and 3 of formatted printing. */
222 class format_postprocessor
225 virtual ~format_postprocessor () {}
226 virtual format_postprocessor
*clone() const = 0;
227 virtual void handle (pretty_printer
*) = 0;
230 inline bool & pp_needs_newline (pretty_printer
*pp
);
232 /* True if PRETTY-PRINTER is in line-wrapping mode. */
233 #define pp_is_wrapping_line(PP) (pp_line_cutoff (PP) > 0)
235 inline output_buffer
*&pp_buffer (pretty_printer
*pp
);
236 inline output_buffer
*pp_buffer (const pretty_printer
*pp
);
237 inline const char *pp_get_prefix (const pretty_printer
*pp
);
238 extern char *pp_take_prefix (pretty_printer
*);
239 extern void pp_destroy_prefix (pretty_printer
*);
240 inline int &pp_line_cutoff (pretty_printer
*pp
);
241 inline diagnostic_prefixing_rule_t
&pp_prefixing_rule (pretty_printer
*pp
);
242 inline pp_wrapping_mode_t
&pp_wrapping_mode (pretty_printer
*pp
);
243 inline int & pp_indentation (pretty_printer
*pp
);
244 inline bool & pp_translate_identifiers (pretty_printer
*pp
);
245 inline bool & pp_show_color (pretty_printer
*pp
);
246 inline printer_fn
&pp_format_decoder (pretty_printer
*pp
);
247 inline format_postprocessor
*& pp_format_postprocessor (pretty_printer
*pp
);
251 /* The data structure that contains the bare minimum required to do
252 proper pretty-printing. Clients may derive from this structure
253 and add additional fields they need. */
257 friend inline output_buffer
*&pp_buffer (pretty_printer
*pp
);
258 friend inline output_buffer
*pp_buffer (const pretty_printer
*pp
);
259 friend inline const char *pp_get_prefix (const pretty_printer
*pp
);
260 friend char *pp_take_prefix (pretty_printer
*);
261 friend void pp_destroy_prefix (pretty_printer
*);
262 friend inline int &pp_line_cutoff (pretty_printer
*pp
);
263 friend inline diagnostic_prefixing_rule_t
&
264 pp_prefixing_rule (pretty_printer
*pp
);
265 friend inline const diagnostic_prefixing_rule_t
&
266 pp_prefixing_rule (const pretty_printer
*pp
);
267 friend inline pp_wrapping_mode_t
&pp_wrapping_mode (pretty_printer
*pp
);
268 friend bool & pp_needs_newline (pretty_printer
*pp
);
269 friend int & pp_indentation (pretty_printer
*pp
);
270 friend bool & pp_translate_identifiers (pretty_printer
*pp
);
271 friend bool & pp_show_color (pretty_printer
*pp
);
272 friend printer_fn
&pp_format_decoder (pretty_printer
*pp
);
273 friend format_postprocessor
*& pp_format_postprocessor (pretty_printer
*pp
);
275 /* Default construct a pretty printer with specified
276 maximum line length cut off limit. */
277 explicit pretty_printer (int = 0);
278 explicit pretty_printer (const pretty_printer
&other
);
280 virtual ~pretty_printer ();
282 virtual pretty_printer
*clone () const;
284 void set_output_stream (FILE *outfile
)
286 m_buffer
->stream
= outfile
;
289 void set_prefix (char *prefix
);
293 void format (text_info
*text
,
294 const urlifier
*urlifier
);
298 bool supports_urls_p () const { return m_url_format
!= URL_FORMAT_NONE
; }
299 diagnostic_url_format
get_url_format () const { return m_url_format
; }
300 void set_url_format (diagnostic_url_format url_format
)
302 m_url_format
= url_format
;
305 void begin_url (const char *url
);
308 /* Switch into verbatim mode and return the old mode. */
310 set_verbatim_wrapping ()
312 const pp_wrapping_mode_t oldmode
= pp_wrapping_mode (this);
313 pp_line_cutoff (this) = 0;
314 pp_prefixing_rule (this) = DIAGNOSTICS_SHOW_PREFIX_NEVER
;
318 void set_padding (pp_padding padding
) { m_padding
= padding
; }
319 pp_padding
get_padding () const { return m_padding
; }
322 void set_real_maximum_length ();
323 int remaining_character_count_for_line ();
326 /* Where we print external representation of ENTITY. */
327 output_buffer
*m_buffer
;
329 /* The prefix for each new line. If non-NULL, this is "owned" by the
330 pretty_printer, and will eventually be free-ed. */
333 /* Where to put whitespace around the entity being formatted. */
334 pp_padding m_padding
;
336 /* The real upper bound of number of characters per line, taking into
337 account the case of a very very looong prefix. */
338 int m_maximum_length
;
340 /* Indentation count. */
343 /* Current wrapping mode. */
344 pp_wrapping_mode_t m_wrapping
;
346 /* If non-NULL, this function formats a TEXT into the BUFFER. When called,
347 TEXT->format_spec points to a format code. FORMAT_DECODER should call
348 pp_string (and related functions) to add data to the BUFFER.
349 FORMAT_DECODER can read arguments from *TEXT->args_pts using VA_ARG.
350 If the BUFFER needs additional characters from the format string, it
351 should advance the TEXT->format_spec as it goes. When FORMAT_DECODER
352 returns, TEXT->format_spec should point to the last character processed.
353 The QUOTE and BUFFER_PTR are passed in, to allow for deferring-handling
354 of format codes (e.g. %H and %I in the C++ frontend). */
355 printer_fn m_format_decoder
;
357 /* If non-NULL, this is called by pp_format once after all format codes
358 have been processed, to allow for client-specific postprocessing.
359 This is used by the C++ frontend for handling the %H and %I
360 format codes (which interract with each other). */
361 format_postprocessor
*m_format_postprocessor
;
363 /* Nonzero if current PREFIX was emitted at least once. */
364 bool m_emitted_prefix
;
366 /* Nonzero means one should emit a newline before outputting anything. */
369 /* Nonzero means identifiers are translated to the locale character
371 bool m_translate_identifiers
;
373 /* Nonzero means that text should be colorized. */
376 /* Whether URLs should be emitted, and which terminator to use. */
377 diagnostic_url_format m_url_format
;
379 /* If true, then we've had a begin_url (nullptr), and so the
380 next end_url should be a no-op. */
381 bool m_skipping_null_url
;
384 inline output_buffer
*&
385 pp_buffer (pretty_printer
*pp
)
390 inline output_buffer
*
391 pp_buffer (const pretty_printer
*pp
)
397 pp_get_prefix (const pretty_printer
*pp
)
402 /* TRUE if a newline character needs to be added before further
405 pp_needs_newline (pretty_printer
*pp
)
407 return pp
->m_need_newline
;
410 /* The amount of whitespace to be emitted when starting a new line. */
412 pp_indentation (pretty_printer
*pp
)
414 return pp
->m_indent_skip
;
417 /* True if identifiers are translated to the locale character set on
420 pp_translate_identifiers (pretty_printer
*pp
)
422 return pp
->m_translate_identifiers
;
425 /* True if colors should be shown. */
427 pp_show_color (pretty_printer
*pp
)
429 return pp
->m_show_color
;
433 pp_format_decoder (pretty_printer
*pp
)
435 return pp
->m_format_decoder
;
438 inline format_postprocessor
*&
439 pp_format_postprocessor (pretty_printer
*pp
)
441 return pp
->m_format_postprocessor
;
444 /* Maximum characters per line in automatic line wrapping mode.
445 Zero means don't wrap lines. */
447 pp_line_cutoff (pretty_printer
*pp
)
449 return pp
->m_wrapping
.line_cutoff
;
452 /* Prefixing rule used in formatting a diagnostic message. */
453 inline diagnostic_prefixing_rule_t
&
454 pp_prefixing_rule (pretty_printer
*pp
)
456 return pp
->m_wrapping
.rule
;
458 inline const diagnostic_prefixing_rule_t
&
459 pp_prefixing_rule (const pretty_printer
*pp
)
461 return pp
->m_wrapping
.rule
;
464 /* Get or set the wrapping mode as a single entity. */
465 inline pp_wrapping_mode_t
&
466 pp_wrapping_mode (pretty_printer
*pp
)
468 return pp
->m_wrapping
;
471 #define pp_space(PP) pp_character (PP, ' ')
472 #define pp_left_paren(PP) pp_character (PP, '(')
473 #define pp_right_paren(PP) pp_character (PP, ')')
474 #define pp_left_bracket(PP) pp_character (PP, '[')
475 #define pp_right_bracket(PP) pp_character (PP, ']')
476 #define pp_left_brace(PP) pp_character (PP, '{')
477 #define pp_right_brace(PP) pp_character (PP, '}')
478 #define pp_semicolon(PP) pp_character (PP, ';')
479 #define pp_comma(PP) pp_character (PP, ',')
480 #define pp_dot(PP) pp_character (PP, '.')
481 #define pp_colon(PP) pp_character (PP, ':')
482 #define pp_colon_colon(PP) pp_string (PP, "::")
483 #define pp_arrow(PP) pp_string (PP, "->")
484 #define pp_equal(PP) pp_character (PP, '=')
485 #define pp_question(PP) pp_character (PP, '?')
486 #define pp_bar(PP) pp_character (PP, '|')
487 #define pp_bar_bar(PP) pp_string (PP, "||")
488 #define pp_carret(PP) pp_character (PP, '^')
489 #define pp_ampersand(PP) pp_character (PP, '&')
490 #define pp_ampersand_ampersand(PP) pp_string (PP, "&&")
491 #define pp_less(PP) pp_character (PP, '<')
492 #define pp_less_equal(PP) pp_string (PP, "<=")
493 #define pp_greater(PP) pp_character (PP, '>')
494 #define pp_greater_equal(PP) pp_string (PP, ">=")
495 #define pp_plus(PP) pp_character (PP, '+')
496 #define pp_minus(PP) pp_character (PP, '-')
497 #define pp_star(PP) pp_character (PP, '*')
498 #define pp_slash(PP) pp_character (PP, '/')
499 #define pp_modulo(PP) pp_character (PP, '%')
500 #define pp_exclamation(PP) pp_character (PP, '!')
501 #define pp_complement(PP) pp_character (PP, '~')
502 #define pp_quote(PP) pp_character (PP, '\'')
503 #define pp_backquote(PP) pp_character (PP, '`')
504 #define pp_doublequote(PP) pp_character (PP, '"')
505 #define pp_underscore(PP) pp_character (PP, '_')
506 #define pp_maybe_newline_and_indent(PP, N) \
507 if (pp_needs_newline (PP)) pp_newline_and_indent (PP, N)
508 #define pp_scalar(PP, FORMAT, SCALAR) \
511 sprintf (pp_buffer (PP)->digit_buffer, FORMAT, SCALAR); \
512 pp_string (PP, pp_buffer (PP)->digit_buffer); \
515 #define pp_decimal_int(PP, I) pp_scalar (PP, "%d", I)
516 #define pp_unsigned_wide_integer(PP, I) \
517 pp_scalar (PP, HOST_WIDE_INT_PRINT_UNSIGNED, (unsigned HOST_WIDE_INT) I)
518 #define pp_vrange(PP, R) \
521 vrange_printer vrange_pp (PP); \
522 (R)->accept (vrange_pp); \
525 #define pp_double(PP, F) pp_scalar (PP, "%f", F)
526 #define pp_pointer(PP, P) pp_scalar (PP, "%p", P)
528 #define pp_identifier(PP, ID) pp_string (PP, (pp_translate_identifiers (PP) \
529 ? identifier_to_locale (ID) \
533 extern void pp_set_line_maximum_length (pretty_printer
*, int);
534 inline void pp_set_prefix (pretty_printer
*pp
, char *prefix
)
536 pp
->set_prefix (prefix
);
538 extern void pp_clear_output_area (pretty_printer
*);
539 extern const char *pp_formatted_text (pretty_printer
*);
540 extern const char *pp_last_position_in_text (const pretty_printer
*);
541 inline void pp_emit_prefix (pretty_printer
*pp
)
545 extern void pp_append_text (pretty_printer
*, const char *, const char *);
546 extern void pp_newline_and_flush (pretty_printer
*);
547 extern void pp_newline_and_indent (pretty_printer
*, int);
548 extern void pp_separate_with (pretty_printer
*, char);
550 /* If we haven't already defined a front-end-specific diagnostics
551 style, use the generic one. */
552 #ifdef GCC_DIAG_STYLE
553 #define GCC_PPDIAG_STYLE GCC_DIAG_STYLE
555 #define GCC_PPDIAG_STYLE __gcc_diag__
558 /* This header may be included before diagnostics-core.h, hence the duplicate
559 definitions to allow for GCC-specific formats. */
560 #if GCC_VERSION >= 3005
561 #define ATTRIBUTE_GCC_PPDIAG(m, n) __attribute__ ((__format__ (GCC_PPDIAG_STYLE, m ,n))) ATTRIBUTE_NONNULL(m)
563 #define ATTRIBUTE_GCC_PPDIAG(m, n) ATTRIBUTE_NONNULL(m)
565 extern void pp_printf (pretty_printer
*, const char *, ...)
566 ATTRIBUTE_GCC_PPDIAG(2,3);
568 extern void pp_verbatim (pretty_printer
*, const char *, ...)
569 ATTRIBUTE_GCC_PPDIAG(2,3);
570 extern void pp_flush (pretty_printer
*);
571 extern void pp_really_flush (pretty_printer
*);
572 inline void pp_format (pretty_printer
*pp
, text_info
*text
,
573 const urlifier
*urlifier
= nullptr)
575 pp
->format (text
, urlifier
);
577 extern void pp_output_formatted_text (pretty_printer
*,
578 const urlifier
* = nullptr);
579 extern void pp_format_verbatim (pretty_printer
*, text_info
*);
581 extern void pp_indent (pretty_printer
*);
582 extern void pp_newline (pretty_printer
*);
583 extern void pp_character (pretty_printer
*, int);
584 extern void pp_string (pretty_printer
*, const char *);
585 extern void pp_unicode_character (pretty_printer
*, unsigned);
587 extern void pp_write_text_to_stream (pretty_printer
*);
588 extern void pp_write_text_as_dot_label_to_stream (pretty_printer
*, bool);
589 extern void pp_write_text_as_html_like_dot_to_stream (pretty_printer
*pp
);
591 inline void pp_maybe_space (pretty_printer
*pp
)
596 extern void pp_begin_quote (pretty_printer
*, bool);
597 extern void pp_end_quote (pretty_printer
*, bool);
600 pp_begin_url (pretty_printer
*pp
, const char *url
)
606 pp_end_url (pretty_printer
*pp
)
611 /* Switch into verbatim mode and return the old mode. */
612 inline pp_wrapping_mode_t
613 pp_set_verbatim_wrapping (pretty_printer
*pp
)
615 return pp
->set_verbatim_wrapping ();
618 extern const char *identifier_to_locale (const char *);
619 extern void *(*identifier_to_locale_alloc
) (size_t);
620 extern void (*identifier_to_locale_free
) (void *);
622 /* Print I to PP in decimal. */
625 pp_wide_integer (pretty_printer
*pp
, HOST_WIDE_INT i
)
627 pp_scalar (pp
, HOST_WIDE_INT_PRINT_DEC
, i
);
631 pp_wide_int (pretty_printer
*pp
, const wide_int_ref
&w
, signop sgn
)
634 print_dec_buf_size (w
, sgn
, &len
);
635 if (UNLIKELY (len
> sizeof (pp_buffer (pp
)->digit_buffer
)))
636 pp_wide_int_large (pp
, w
, sgn
);
639 print_dec (w
, pp_buffer (pp
)->digit_buffer
, sgn
);
640 pp_string (pp
, pp_buffer (pp
)->digit_buffer
);
644 template<unsigned int N
, typename T
>
645 void pp_wide_integer (pretty_printer
*pp
, const poly_int
<N
, T
> &);
647 #endif /* GCC_PRETTY_PRINT_H */