1 /* Various declarations for language-independent pretty-print subroutines.
2 Copyright (C) 2002-2023 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 "diagnostic-url.h"
27 /* Maximum number of format string arguments. */
28 #define PP_NL_ARGMAX 30
30 /* The type of a text to be formatted according a format specification
31 along with a list of things. */
34 text_info () = default;
35 text_info (const char *format_spec
,
38 void **data
= nullptr,
39 rich_location
*rich_loc
= nullptr)
40 : m_format_spec (format_spec
),
41 m_args_ptr (args_ptr
),
48 void set_location (unsigned int idx
, location_t loc
,
49 enum range_display_kind range_display_kind
);
50 location_t
get_location (unsigned int index_of_location
) const;
52 const char *m_format_spec
;
54 int m_err_no
; /* for %m */
56 rich_location
*m_richloc
;
59 /* How often diagnostics are prefixed by their locations:
60 o DIAGNOSTICS_SHOW_PREFIX_NEVER: never - not yet supported;
61 o DIAGNOSTICS_SHOW_PREFIX_ONCE: emit only once;
62 o DIAGNOSTICS_SHOW_PREFIX_EVERY_LINE: emit each time a physical
64 enum diagnostic_prefixing_rule_t
66 DIAGNOSTICS_SHOW_PREFIX_ONCE
= 0x0,
67 DIAGNOSTICS_SHOW_PREFIX_NEVER
= 0x1,
68 DIAGNOSTICS_SHOW_PREFIX_EVERY_LINE
= 0x2
71 /* The chunk_info data structure forms a stack of the results from the
72 first phase of formatting (pp_format) which have not yet been
73 output (pp_output_formatted_text). A stack is necessary because
74 the diagnostic starter may decide to generate its own output by way
78 /* Pointer to previous chunk on the stack. */
79 struct chunk_info
*prev
;
81 /* Array of chunks to output. Each chunk is a NUL-terminated string.
82 In the first phase of formatting, even-numbered chunks are
83 to be output verbatim, odd-numbered chunks are format specifiers.
84 The second phase replaces all odd-numbered chunks with formatted
85 text, and the third phase simply emits all the chunks in sequence
86 with appropriate line-wrapping. */
87 const char *args
[PP_NL_ARGMAX
* 2];
90 /* The output buffer datatype. This is best seen as an abstract datatype
91 whose fields should not be accessed directly by clients. */
98 /* Obstack where the text is built up. */
99 struct obstack formatted_obstack
;
101 /* Obstack containing a chunked representation of the format
102 specification plus arguments. */
103 struct obstack chunk_obstack
;
105 /* Currently active obstack: one of the above two. This is used so
106 that the text formatters don't need to know which phase we're in. */
107 struct obstack
*obstack
;
109 /* Stack of chunk arrays. These come from the chunk_obstack. */
110 struct chunk_info
*cur_chunk_array
;
112 /* Where to output formatted text. */
115 /* The amount of characters output so far. */
118 /* This must be large enough to hold any printed integer or
119 floating-point value. */
120 char digit_buffer
[128];
122 /* Nonzero means that text should be flushed when
123 appropriate. Otherwise, text is buffered until either
124 pp_really_flush or pp_clear_output_area are called. */
128 /* Finishes constructing a NULL-terminated character string representing
129 the buffered text. */
131 output_buffer_formatted_text (output_buffer
*buff
)
133 obstack_1grow (buff
->obstack
, '\0');
134 return (const char *) obstack_base (buff
->obstack
);
137 /* Append to the output buffer a string specified by its
138 STARTing character and LENGTH. */
140 output_buffer_append_r (output_buffer
*buff
, const char *start
, int length
)
142 gcc_checking_assert (start
);
143 obstack_grow (buff
->obstack
, start
, length
);
144 for (int i
= 0; i
< length
; i
++)
145 if (start
[i
] == '\n')
146 buff
->line_length
= 0;
151 /* Return a pointer to the last character emitted in the
152 output_buffer. A NULL pointer means no character available. */
154 output_buffer_last_position_in_text (const output_buffer
*buff
)
156 const char *p
= NULL
;
157 struct obstack
*text
= buff
->obstack
;
159 if (obstack_base (text
) != obstack_next_free (text
))
160 p
= ((const char *) obstack_next_free (text
)) - 1;
165 /* The type of pretty-printer flags passed to clients. */
166 typedef unsigned int pp_flags
;
170 pp_none
, pp_before
, pp_after
173 /* Structure for switching in and out of verbatim mode in a convenient
175 struct pp_wrapping_mode_t
177 /* Current prefixing rule. */
178 diagnostic_prefixing_rule_t rule
;
180 /* The ideal upper bound of number of characters per line, as suggested
185 /* Maximum characters per line in automatic line wrapping mode.
186 Zero means don't wrap lines. */
187 #define pp_line_cutoff(PP) (PP)->wrapping.line_cutoff
189 /* Prefixing rule used in formatting a diagnostic message. */
190 #define pp_prefixing_rule(PP) (PP)->wrapping.rule
192 /* Get or set the wrapping mode as a single entity. */
193 #define pp_wrapping_mode(PP) (PP)->wrapping
195 /* The type of a hook that formats client-specific data onto a pretty_printer.
196 A client-supplied formatter returns true if everything goes well,
197 otherwise it returns false. */
198 typedef bool (*printer_fn
) (pretty_printer
*, text_info
*, const char *,
199 int, bool, bool, bool, bool *, const char **);
201 /* Client supplied function used to decode formats. */
202 #define pp_format_decoder(PP) (PP)->format_decoder
204 /* Base class for an optional client-supplied object for doing additional
205 processing between stages 2 and 3 of formatted printing. */
206 class format_postprocessor
209 virtual ~format_postprocessor () {}
210 virtual format_postprocessor
*clone() const = 0;
211 virtual void handle (pretty_printer
*) = 0;
214 /* TRUE if a newline character needs to be added before further
216 #define pp_needs_newline(PP) (PP)->need_newline
218 /* True if PRETTY-PRINTER is in line-wrapping mode. */
219 #define pp_is_wrapping_line(PP) (pp_line_cutoff (PP) > 0)
221 /* The amount of whitespace to be emitted when starting a new line. */
222 #define pp_indentation(PP) (PP)->indent_skip
224 /* True if identifiers are translated to the locale character set on
226 #define pp_translate_identifiers(PP) (PP)->translate_identifiers
228 /* True if colors should be shown. */
229 #define pp_show_color(PP) (PP)->show_color
231 /* The data structure that contains the bare minimum required to do
232 proper pretty-printing. Clients may derived from this structure
233 and add additional fields they need. */
237 /* Default construct a pretty printer with specified
238 maximum line length cut off limit. */
239 explicit pretty_printer (int = 0);
240 explicit pretty_printer (const pretty_printer
&other
);
242 virtual ~pretty_printer ();
244 virtual pretty_printer
*clone () const;
246 /* Where we print external representation of ENTITY. */
247 output_buffer
*buffer
;
249 /* The prefix for each new line. If non-NULL, this is "owned" by the
250 pretty_printer, and will eventually be free-ed. */
253 /* Where to put whitespace around the entity being formatted. */
256 /* The real upper bound of number of characters per line, taking into
257 account the case of a very very looong prefix. */
260 /* Indentation count. */
263 /* Current wrapping mode. */
264 pp_wrapping_mode_t wrapping
;
266 /* If non-NULL, this function formats a TEXT into the BUFFER. When called,
267 TEXT->format_spec points to a format code. FORMAT_DECODER should call
268 pp_string (and related functions) to add data to the BUFFER.
269 FORMAT_DECODER can read arguments from *TEXT->args_pts using VA_ARG.
270 If the BUFFER needs additional characters from the format string, it
271 should advance the TEXT->format_spec as it goes. When FORMAT_DECODER
272 returns, TEXT->format_spec should point to the last character processed.
273 The QUOTE and BUFFER_PTR are passed in, to allow for deferring-handling
274 of format codes (e.g. %H and %I in the C++ frontend). */
275 printer_fn format_decoder
;
277 /* If non-NULL, this is called by pp_format once after all format codes
278 have been processed, to allow for client-specific postprocessing.
279 This is used by the C++ frontend for handling the %H and %I
280 format codes (which interract with each other). */
281 format_postprocessor
*m_format_postprocessor
;
283 /* Nonzero if current PREFIX was emitted at least once. */
286 /* Nonzero means one should emit a newline before outputting anything. */
289 /* Nonzero means identifiers are translated to the locale character
291 bool translate_identifiers
;
293 /* Nonzero means that text should be colorized. */
296 /* Whether URLs should be emitted, and which terminator to use. */
297 diagnostic_url_format url_format
;
301 pp_get_prefix (const pretty_printer
*pp
) { return pp
->prefix
; }
303 #define pp_space(PP) pp_character (PP, ' ')
304 #define pp_left_paren(PP) pp_character (PP, '(')
305 #define pp_right_paren(PP) pp_character (PP, ')')
306 #define pp_left_bracket(PP) pp_character (PP, '[')
307 #define pp_right_bracket(PP) pp_character (PP, ']')
308 #define pp_left_brace(PP) pp_character (PP, '{')
309 #define pp_right_brace(PP) pp_character (PP, '}')
310 #define pp_semicolon(PP) pp_character (PP, ';')
311 #define pp_comma(PP) pp_character (PP, ',')
312 #define pp_dot(PP) pp_character (PP, '.')
313 #define pp_colon(PP) pp_character (PP, ':')
314 #define pp_colon_colon(PP) pp_string (PP, "::")
315 #define pp_arrow(PP) pp_string (PP, "->")
316 #define pp_equal(PP) pp_character (PP, '=')
317 #define pp_question(PP) pp_character (PP, '?')
318 #define pp_bar(PP) pp_character (PP, '|')
319 #define pp_bar_bar(PP) pp_string (PP, "||")
320 #define pp_carret(PP) pp_character (PP, '^')
321 #define pp_ampersand(PP) pp_character (PP, '&')
322 #define pp_ampersand_ampersand(PP) pp_string (PP, "&&")
323 #define pp_less(PP) pp_character (PP, '<')
324 #define pp_less_equal(PP) pp_string (PP, "<=")
325 #define pp_greater(PP) pp_character (PP, '>')
326 #define pp_greater_equal(PP) pp_string (PP, ">=")
327 #define pp_plus(PP) pp_character (PP, '+')
328 #define pp_minus(PP) pp_character (PP, '-')
329 #define pp_star(PP) pp_character (PP, '*')
330 #define pp_slash(PP) pp_character (PP, '/')
331 #define pp_modulo(PP) pp_character (PP, '%')
332 #define pp_exclamation(PP) pp_character (PP, '!')
333 #define pp_complement(PP) pp_character (PP, '~')
334 #define pp_quote(PP) pp_character (PP, '\'')
335 #define pp_backquote(PP) pp_character (PP, '`')
336 #define pp_doublequote(PP) pp_character (PP, '"')
337 #define pp_underscore(PP) pp_character (PP, '_')
338 #define pp_maybe_newline_and_indent(PP, N) \
339 if (pp_needs_newline (PP)) pp_newline_and_indent (PP, N)
340 #define pp_scalar(PP, FORMAT, SCALAR) \
343 sprintf (pp_buffer (PP)->digit_buffer, FORMAT, SCALAR); \
344 pp_string (PP, pp_buffer (PP)->digit_buffer); \
347 #define pp_decimal_int(PP, I) pp_scalar (PP, "%d", I)
348 #define pp_unsigned_wide_integer(PP, I) \
349 pp_scalar (PP, HOST_WIDE_INT_PRINT_UNSIGNED, (unsigned HOST_WIDE_INT) I)
350 #define pp_vrange(PP, R) \
353 vrange_printer vrange_pp (PP); \
354 (R)->accept (vrange_pp); \
357 #define pp_double(PP, F) pp_scalar (PP, "%f", F)
358 #define pp_pointer(PP, P) pp_scalar (PP, "%p", P)
360 #define pp_identifier(PP, ID) pp_string (PP, (pp_translate_identifiers (PP) \
361 ? identifier_to_locale (ID) \
365 #define pp_buffer(PP) (PP)->buffer
367 extern void pp_set_line_maximum_length (pretty_printer
*, int);
368 extern void pp_set_prefix (pretty_printer
*, char *);
369 extern char *pp_take_prefix (pretty_printer
*);
370 extern void pp_destroy_prefix (pretty_printer
*);
371 extern int pp_remaining_character_count_for_line (pretty_printer
*);
372 extern void pp_clear_output_area (pretty_printer
*);
373 extern const char *pp_formatted_text (pretty_printer
*);
374 extern const char *pp_last_position_in_text (const pretty_printer
*);
375 extern void pp_emit_prefix (pretty_printer
*);
376 extern void pp_append_text (pretty_printer
*, const char *, const char *);
377 extern void pp_newline_and_flush (pretty_printer
*);
378 extern void pp_newline_and_indent (pretty_printer
*, int);
379 extern void pp_separate_with (pretty_printer
*, char);
381 /* If we haven't already defined a front-end-specific diagnostics
382 style, use the generic one. */
383 #ifdef GCC_DIAG_STYLE
384 #define GCC_PPDIAG_STYLE GCC_DIAG_STYLE
386 #define GCC_PPDIAG_STYLE __gcc_diag__
389 /* This header may be included before diagnostics-core.h, hence the duplicate
390 definitions to allow for GCC-specific formats. */
391 #if GCC_VERSION >= 3005
392 #define ATTRIBUTE_GCC_PPDIAG(m, n) __attribute__ ((__format__ (GCC_PPDIAG_STYLE, m ,n))) ATTRIBUTE_NONNULL(m)
394 #define ATTRIBUTE_GCC_PPDIAG(m, n) ATTRIBUTE_NONNULL(m)
396 extern void pp_printf (pretty_printer
*, const char *, ...)
397 ATTRIBUTE_GCC_PPDIAG(2,3);
399 extern void pp_verbatim (pretty_printer
*, const char *, ...)
400 ATTRIBUTE_GCC_PPDIAG(2,3);
401 extern void pp_flush (pretty_printer
*);
402 extern void pp_really_flush (pretty_printer
*);
403 extern void pp_format (pretty_printer
*, text_info
*);
404 extern void pp_output_formatted_text (pretty_printer
*);
405 extern void pp_format_verbatim (pretty_printer
*, text_info
*);
407 extern void pp_indent (pretty_printer
*);
408 extern void pp_newline (pretty_printer
*);
409 extern void pp_character (pretty_printer
*, int);
410 extern void pp_string (pretty_printer
*, const char *);
411 extern void pp_unicode_character (pretty_printer
*, unsigned);
413 extern void pp_write_text_to_stream (pretty_printer
*);
414 extern void pp_write_text_as_dot_label_to_stream (pretty_printer
*, bool);
415 extern void pp_write_text_as_html_like_dot_to_stream (pretty_printer
*pp
);
417 extern void pp_maybe_space (pretty_printer
*);
419 extern void pp_begin_quote (pretty_printer
*, bool);
420 extern void pp_end_quote (pretty_printer
*, bool);
422 extern void pp_begin_url (pretty_printer
*pp
, const char *url
);
423 extern void pp_end_url (pretty_printer
*pp
);
425 /* Switch into verbatim mode and return the old mode. */
426 inline pp_wrapping_mode_t
427 pp_set_verbatim_wrapping_ (pretty_printer
*pp
)
429 pp_wrapping_mode_t oldmode
= pp_wrapping_mode (pp
);
430 pp_line_cutoff (pp
) = 0;
431 pp_prefixing_rule (pp
) = DIAGNOSTICS_SHOW_PREFIX_NEVER
;
434 #define pp_set_verbatim_wrapping(PP) pp_set_verbatim_wrapping_ (PP)
436 extern const char *identifier_to_locale (const char *);
437 extern void *(*identifier_to_locale_alloc
) (size_t);
438 extern void (*identifier_to_locale_free
) (void *);
440 /* Print I to PP in decimal. */
443 pp_wide_integer (pretty_printer
*pp
, HOST_WIDE_INT i
)
445 pp_scalar (pp
, HOST_WIDE_INT_PRINT_DEC
, i
);
449 pp_wide_int (pretty_printer
*pp
, const wide_int_ref
&w
, signop sgn
)
452 print_dec_buf_size (w
, sgn
, &len
);
453 if (UNLIKELY (len
> sizeof (pp_buffer (pp
)->digit_buffer
)))
454 pp_wide_int_large (pp
, w
, sgn
);
457 print_dec (w
, pp_buffer (pp
)->digit_buffer
, sgn
);
458 pp_string (pp
, pp_buffer (pp
)->digit_buffer
);
462 template<unsigned int N
, typename T
>
463 void pp_wide_integer (pretty_printer
*pp
, const poly_int
<N
, T
> &);
465 #endif /* GCC_PRETTY_PRINT_H */