GCC Middle and Back End API Reference
dump_pretty_printer Class Reference

#include <dump-context.h>

Inheritance diagram for dump_pretty_printer:
Collaboration diagram for dump_pretty_printer:

Data Structures

class  stashed_item

Public Member Functions

 dump_pretty_printer (dump_context *context, dump_flags_t dump_kind)
void emit_items (optinfo *dest)
virtual pretty_printerclone () const
void set_output_stream (FILE *outfile)
void set_prefix (char *prefix)
void emit_prefix ()
void format (text_info *text, const urlifier *urlifier)
void maybe_space ()
bool supports_urls_p () const
diagnostic_url_format get_url_format () const
void set_url_format (diagnostic_url_format url_format)
void begin_url (const char *url)
void end_url ()
pp_wrapping_mode_t set_verbatim_wrapping ()
void set_padding (pp_padding padding)
pp_padding get_padding () const
void clear_state ()
void set_real_maximum_length ()
int remaining_character_count_for_line ()

Private Member Functions

bool decode_format (text_info *text, const char *spec, const char **buffer_ptr)
void stash_item (const char **buffer_ptr, optinfo_item *item)
void emit_any_pending_textual_chunks (optinfo *dest)
void emit_item (optinfo_item *item, optinfo *dest)

Static Private Member Functions

static bool format_decoder_cb (pretty_printer *pp, text_info *text, const char *spec, int, bool, bool, bool, bool @endverbatim *, const char **buffer_ptr)

Private Attributes

dump_flags_t m_dump_kind
auto_vec< stashed_itemm_stashed_items
char * m_prefix
pp_padding m_padding
int m_maximum_length
int m_indent_skip
pp_wrapping_mode_t m_wrapping
printer_fn m_format_decoder
bool m_emitted_prefix
bool m_need_newline
bool m_translate_identifiers
bool m_show_color
diagnostic_url_format m_url_format
bool m_skipping_null_url

Detailed Description

A subclass of pretty_printer for implementing dump_context::dump_printf_va.
In particular, the formatted chunks are captured as optinfo_item instances,
thus retaining metadata about the entities being dumped (e.g. source
locations), rather than just as plain text.   

Constructor & Destructor Documentation

◆ dump_pretty_printer()

dump_pretty_printer::dump_pretty_printer ( dump_context * context,
dump_flags_t dump_kind )
dump_pretty_printer's ctor.   

References format_decoder_cb(), and pretty_printer::pp_format_decoder.

Member Function Documentation

◆ begin_url()

void pretty_printer::begin_url ( const char * url)
Support for encoding URLs.
See egmontkob/Hyperlinks_in_Terminal_Emulators.md
( https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda ).

> A hyperlink is opened upon encountering an OSC 8 escape sequence with
> the target URI. The syntax is
>  OSC 8 ; params ; URI ST
> A hyperlink is closed with the same escape sequence, omitting the
> parameters and the URI but keeping the separators:
> OSC 8 ; ; ST
> OSC (operating system command) is typically ESC ].

Use BEL instead of ST, as that is currently rendered better in some
terminal emulators that don't support OSC 8, like konsole.   
If URL-printing is enabled, write an "open URL" escape sequence to PP
for the given URL.   

References gcc_unreachable, pretty_printer::m_skipping_null_url, pretty_printer::m_url_format, pp_string(), URL_FORMAT_BEL, URL_FORMAT_NONE, and URL_FORMAT_ST.

Referenced by pretty_printer::format().

◆ clear_state()

void pretty_printer::clear_state ( )
Clear this pretty_printer's output state.   

References pretty_printer::m_emitted_prefix, and pretty_printer::pp_indentation.

Referenced by pretty_printer::format(), pp_flush(), and pp_really_flush().

◆ clone()

pretty_printer * pretty_printer::clone ( ) const
Base class implementation of pretty_printer::clone vfunc.   

References pretty_printer::pretty_printer().

Referenced by attr_access::array_as_string().

◆ decode_format()

bool dump_pretty_printer::decode_format ( text_info * text,
const char * spec,
const char ** buffer_ptr )
Format decoder for dump_pretty_printer, and thus for dump_printf and

Supported format codes (in addition to the standard pretty_printer ones)

%C: cgraph_node *:
    Equivalent to: dump_symtab_node (MSG_*, node)
%E: gimple *:
    Equivalent to: dump_gimple_expr (MSG_*, TDF_SLIM, stmt, 0)
%G: gimple *:
    Equivalent to: dump_gimple_stmt (MSG_*, TDF_SLIM, stmt, 0)
%T: tree:
    Equivalent to: dump_generic_expr (MSG_*, arg, TDF_SLIM).

TODO: add a format code that can handle (symtab_node*) *and* both
subclasses (presumably means teaching -Wformat about non-virtual

These format codes build optinfo_item instances, thus capturing metadata
about the arguments being dumped, as well as the textual output.   

References text_info::m_args_ptr, make_item_for_dump_generic_expr(), make_item_for_dump_gimple_expr(), make_item_for_dump_gimple_stmt(), make_item_for_dump_symtab_node(), stash_item(), and TDF_SLIM.

Referenced by format_decoder_cb().

◆ emit_any_pending_textual_chunks()

void dump_pretty_printer::emit_any_pending_textual_chunks ( optinfo * dest)
Subroutine of dump_pretty_printer::emit_items
for consolidating multiple adjacent pure-text chunks into single
optinfo_items (in phase 3).   

References emit_item(), output_buffer::formatted_obstack, gcc_assert, NULL, output_buffer::obstack, OPTINFO_ITEM_KIND_TEXT, output_buffer_last_position_in_text(), pretty_printer::pp_buffer, pp_formatted_text(), and UNKNOWN_LOCATION.

Referenced by emit_items().

◆ emit_item()

void dump_pretty_printer::emit_item ( optinfo_item * item,
optinfo * dest )
Emit ITEM and take ownership of it.  If DEST is non-NULL, add ITEM
to DEST; otherwise delete ITEM.   

References optinfo::add_item(), dump_context::emit_item(), m_context, and m_dump_kind.

Referenced by emit_any_pending_textual_chunks(), and emit_items().

◆ emit_items()

void dump_pretty_printer::emit_items ( optinfo * dest)
Phase 3 of formatting; compare with pp_output_formatted_text.

Emit optinfo_item instances for the various formatted chunks from phases
1 and 2 (i.e. pp_format).

Some chunks may already have had their items built (during decode_format).
These chunks have been stashed into m_stashed_items; we emit them here.

For all other purely textual chunks, they are printed into
buffer->formatted_obstack, and then emitted as a textual optinfo_item.
This consolidates multiple adjacent text chunks into a single text

References output_buffer::cur_chunk_array, emit_any_pending_textual_chunks(), emit_item(), output_buffer::formatted_obstack, gcc_assert, chunk_info::get_args(), output_buffer::line_length, m_stashed_items, output_buffer::obstack, chunk_info::pop_from_output_buffer(), pretty_printer::pp_buffer, and pp_string().

Referenced by dump_context::dump_printf_va(), and opt_problem::opt_problem().

◆ emit_prefix()

◆ end_url()

void pretty_printer::end_url ( )
If URL-printing is enabled, write a "close URL" escape sequence to PP.   

References get_end_url_string(), pretty_printer::m_skipping_null_url, pretty_printer::m_url_format, pp_string(), and URL_FORMAT_NONE.

◆ format()

void pretty_printer::format ( text_info * text,
const urlifier * urlifier )
The following format specifiers are recognized as being client independent:
%d, %i: (signed) integer in base ten.
%u: unsigned integer in base ten.
%o: unsigned integer in base eight.
%x: unsigned integer in base sixteen.
%ld, %li, %lo, %lu, %lx: long versions of the above.
%lld, %lli, %llo, %llu, %llx: long long versions.
%wd, %wi, %wo, %wu, %wx: HOST_WIDE_INT versions.
%zd, %zi, %zo, %zu, %zx: size_t versions.
%td, %ti, %to, %tu, %tx: ptrdiff_t versions.
%f: double
%c: character.
%s: string.
%p: pointer (printed in a host-dependent manner).
%r: if pp_show_color(pp), switch to color identified by const char *.
%R: if pp_show_color(pp), reset color.
%m: strerror(text->err_no) - does not consume a value from args_ptr.
%%: '%'.
%<: opening quote.
%>: closing quote.
%{: URL start.  Consumes a const char * argument for the URL.
%}: URL end.    Does not consume any arguments.
%': apostrophe (should only be used in untranslated messages;
    translations should use appropriate punctuation directly).
%@: diagnostic_event_id_ptr, for which event_id->known_p () must be true.
%.*s: a substring the length of which is specified by an argument
%Ns: likewise, but length specified as constant in the format string.
Flag 'q': quote formatted text (must come immediately after '%').
%Z: Requires two arguments - array of int, and len. Prints elements
of the array.

Arguments can be used sequentially, or through %N$ resp. *N$
notation Nth argument after the format string.  If %N$ / *N$
notation is used, it must be used for all arguments, except %m, %%,
%<, %>, %} and %', which may not have a number, as they do not consume
an argument.  When %M$.*N$s is used, M must be N + 1.  (This may
also be written %M$.*s, provided N is not otherwise used.)  The
format string must have conversion specifiers with argument numbers
1 up to highest argument; each argument may only be used once.
A format string can have at most 30 arguments.   
Implementation of pp_format.
Formatting phases 1 and 2: render TEXT->format_spec plus
text->m_args_ptr into a series of chunks in pp_buffer (PP)->args[].
Phase 3 is in pp_output_formatted_text.

If URLIFIER is non-NULL, then use it to add URLs for quoted
strings, so that e.g.
  "before %<quoted%> after"
with a URLIFIER that has a URL for "quoted" might be emitted as:
  "before `BEGIN_URL(http://example.com)quotedEND_URL' after"
This is handled here for message fragments that are:
- quoted entirely in phase 1 (e.g. "%<this is quoted%>"), or
- quoted entirely in phase 2 (e.g. "%qs"),
Quoted fragments that use a mixture of both phases
(e.g. "%<this is a mixture: %s %>")
are stashed into the output_buffer's m_quotes for use in phase 3.   

References pretty_printer::begin_url(), output_buffer::chunk_obstack, pretty_printer::clear_state(), close_quote, colorize_start(), colorize_stop(), output_buffer::cur_chunk_array, end(), output_buffer::formatted_obstack, gcc_assert, gcc_unreachable, get_end_url_string(), format_postprocessor::handle(), HOST_WIDE_INT_PRINT, HOST_WIDE_INT_PRINT_HEX, HOST_WIDE_INT_PRINT_UNSIGNED, i, diagnostic_event_id_t::known_p(), output_buffer::line_length, chunk_info::m_args, text_info::m_args_ptr, pretty_printer::m_buffer, text_info::m_err_no, pretty_printer::m_format_decoder, pretty_printer::m_format_postprocessor, text_info::m_format_spec, chunk_info::m_prev, chunk_info::m_quotes, pretty_printer::m_show_color, output_buffer::obstack, chunk_info::on_begin_quote(), chunk_info::on_end_quote(), diagnostic_event_id_t::one_based(), open_quote, pp_append_text(), pp_begin_quote(), pp_character(), pp_comma, pp_decimal_int, pp_double, pp_end_quote(), pretty_printer::pp_format_decoder, pp_integer_with_precision, PP_NL_ARGMAX, pp_pointer, pp_quoted_string(), pp_scalar, pp_set_verbatim_wrapping(), pp_space, pp_string(), pp_wide_integer(), and pretty_printer::pp_wrapping_mode.

◆ format_decoder_cb()

bool dump_pretty_printer::format_decoder_cb ( pretty_printer * pp,
text_info * text,
const char * spec,
int ,
bool ,
bool ,
bool ,
bool @endverbatim * ,
const char ** buffer_ptr )
pp_format_decoder callback for dump_pretty_printer, and thus for
dump_printf and dump_printf_loc.

A wrapper around decode_format, for type-safety.   

References decode_format().

Referenced by dump_pretty_printer().

◆ get_padding()

pp_padding pretty_printer::get_padding ( ) const

◆ get_url_format()

diagnostic_url_format pretty_printer::get_url_format ( ) const

◆ maybe_space()

void pretty_printer::maybe_space ( )
Maybe print out a whitespace if needed.   

References pretty_printer::m_padding, pp_none, and pp_space.

◆ remaining_character_count_for_line()

int pretty_printer::remaining_character_count_for_line ( )
Return the amount of characters PRETTY-PRINTER can accept to
make a full line.  Meaningful only in line-wrapping mode.   

References output_buffer::line_length, pretty_printer::m_maximum_length, and pretty_printer::pp_buffer.

Referenced by pp_character(), and pp_wrap_text().

◆ set_output_stream()

◆ set_padding()

void pretty_printer::set_padding ( pp_padding padding)

◆ set_prefix()

void pretty_printer::set_prefix ( char * prefix)
Set PREFIX for PRETTY-PRINTER, taking ownership of PREFIX, which
will eventually be free-ed.   

References free(), pretty_printer::m_emitted_prefix, pretty_printer::m_prefix, pretty_printer::pp_indentation, and pretty_printer::set_real_maximum_length().

Referenced by lhd_print_error_function().

◆ set_real_maximum_length()

void pretty_printer::set_real_maximum_length ( )

◆ set_url_format()

void pretty_printer::set_url_format ( diagnostic_url_format url_format)

◆ set_verbatim_wrapping()

◆ stash_item()

void dump_pretty_printer::stash_item ( const char ** buffer_ptr,
optinfo_item * item )
Record that ITEM (generated in phase 2 of formatting) is to be used for
the chunk at BUFFER_PTR in phase 3 (by emit_items).   

References gcc_assert, and m_stashed_items.

Referenced by decode_format().

◆ supports_urls_p()

Field Documentation

◆ m_buffer

◆ m_context

dump_context* dump_pretty_printer::m_context

Referenced by emit_item().

◆ m_dump_kind

dump_flags_t dump_pretty_printer::m_dump_kind

Referenced by emit_item().

◆ m_emitted_prefix

bool pretty_printer::m_emitted_prefix

◆ m_format_decoder

printer_fn pretty_printer::m_format_decoder

Referenced by pretty_printer::format().

◆ m_format_postprocessor

format_postprocessor* pretty_printer::m_format_postprocessor

◆ m_indent_skip

int pretty_printer::m_indent_skip

◆ m_maximum_length

◆ m_need_newline

bool pretty_printer::m_need_newline

◆ m_padding

pp_padding pretty_printer::m_padding

◆ m_prefix

◆ m_show_color

bool pretty_printer::m_show_color

Referenced by pretty_printer::format().

◆ m_skipping_null_url

bool pretty_printer::m_skipping_null_url

◆ m_stashed_items

auto_vec<stashed_item> dump_pretty_printer::m_stashed_items

Referenced by emit_items(), and stash_item().

◆ m_translate_identifiers

bool pretty_printer::m_translate_identifiers

◆ m_url_format

◆ m_wrapping

pp_wrapping_mode_t pretty_printer::m_wrapping

The documentation for this class was generated from the following files: