GCC Middle and Back End API Reference
pretty-print.cc File Reference
#include "config.h"
#include "system.h"
#include "coretypes.h"
#include "intl.h"
#include "pretty-print.h"
#include "pretty-print-urlifier.h"
#include "diagnostic-color.h"
#include "diagnostic-event-id.h"
#include "selftest.h"
Include dependency graph for pretty-print.cc:

Data Structures

class  quoting_info
struct  quoting_info::location
struct  quoting_info::run
struct  auto_obstack


#define PTRDIFF_MAX   INTTYPE_MAXIMUM (ptrdiff_t)
#define pp_integer_with_precision(PP, ARG, PREC, T, F)


static int decode_utf8_char (const unsigned char *, size_t len, unsigned int *)
static void pp_quoted_string (pretty_printer *, const char *, size_t=-1)
template<unsigned int N, typename T >
void pp_wide_integer (pretty_printer *pp, const poly_int< N, T > &x)
template void pp_wide_integer (pretty_printer *, const poly_uint16 &)
template void pp_wide_integer (pretty_printer *, const poly_int64 &)
template void pp_wide_integer (pretty_printer *, const poly_uint64 &)
void pp_write_text_to_stream (pretty_printer *pp)
void pp_write_text_as_dot_label_to_stream (pretty_printer *pp, bool for_record)
void pp_write_text_as_html_like_dot_to_stream (pretty_printer *pp)
static void pp_wrap_text (pretty_printer *pp, const char *start, const char *end)
static void pp_maybe_wrap_text (pretty_printer *pp, const char *start, const char *end)
static void pp_append_r (pretty_printer *pp, const char *start, int length)
void pp_indent (pretty_printer *pp)
static const char * get_end_url_string (pretty_printer *)
static void obstack_append_string (obstack *ostack, const char *str)
static void obstack_append_string (obstack *ostack, const char *str, size_t len)
static size_t urlify_quoted_string (pretty_printer *pp, obstack *obstack, const urlifier *urlifier, size_t quoted_text_start_idx, size_t quoted_text_end_idx)
void pp_output_formatted_text (pretty_printer *pp, const urlifier *urlifier)
void pp_format_verbatim (pretty_printer *pp, text_info *text)
void pp_flush (pretty_printer *pp)
void pp_really_flush (pretty_printer *pp)
void pp_set_line_maximum_length (pretty_printer *pp, int length)
void pp_clear_output_area (pretty_printer *pp)
char * pp_take_prefix (pretty_printer *pp)
void pp_destroy_prefix (pretty_printer *pp)
void pp_append_text (pretty_printer *pp, const char *start, const char *end)
const char * pp_formatted_text (pretty_printer *pp)
const char * pp_last_position_in_text (const pretty_printer *pp)
void pp_printf (pretty_printer *pp, const char *msg,...)
void pp_verbatim (pretty_printer *pp, const char *msg,...)
void pp_newline (pretty_printer *pp)
void pp_character (pretty_printer *pp, int c)
void pp_string (pretty_printer *pp, const char *str)
void pp_unicode_character (pretty_printer *pp, unsigned c)
void pp_newline_and_flush (pretty_printer *pp)
void pp_newline_and_indent (pretty_printer *pp, int n)
void pp_separate_with (pretty_printer *pp, char c)
void pp_begin_quote (pretty_printer *pp, bool show_color)
void pp_end_quote (pretty_printer *pp, bool show_color)
const char * identifier_to_locale (const char *ident)


void *(* identifier_to_locale_alloc )(size_t) = xmalloc
void(* identifier_to_locale_free )(void *) = free

Macro Definition Documentation


Various declarations for language-independent pretty-print subroutines.
   Copyright (C) 2003-2024 Free Software Foundation, Inc.
   Contributed by Gabriel Dos Reis <gdr@integrable-solutions.net>

This file is part of GCC.

GCC is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later

GCC is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
for more details.

You should have received a copy of the GNU General Public License
along with GCC; see the file COPYING3.  If not see

◆ pp_integer_with_precision

#define pp_integer_with_precision ( PP,
F )
Format an integer given by va_arg (ARG, type-specifier T) where
type-specifier is a precision modifier as indicated by PREC.  F is
a string used to construct the appropriate format-specifier.   

Referenced by pretty_printer::format().


#define PTRDIFF_MAX   INTTYPE_MAXIMUM (ptrdiff_t)

Function Documentation

◆ decode_utf8_char()

static int decode_utf8_char ( const unsigned char * p,
size_t len,
unsigned int * value )
The string starting at P has LEN (at least 1) bytes left; if they
start with a valid UTF-8 sequence, return the length of that
sequence and set *VALUE to the value of that sequence, and
otherwise return 0 and set *VALUE to (unsigned int) -1.   

References abort, and i.

Referenced by identifier_to_locale(), and pp_quoted_string().

◆ get_end_url_string()

static const char * get_end_url_string ( pretty_printer * pp)
Helper function for pp_end_url and pp_format, return the "close URL" escape
sequence string.   

References gcc_unreachable, pretty_printer::get_url_format(), URL_FORMAT_BEL, URL_FORMAT_NONE, and URL_FORMAT_ST.

Referenced by pretty_printer::end_url(), pretty_printer::format(), and urlify_quoted_string().

◆ identifier_to_locale()

const char * identifier_to_locale ( const char * ident)
Given IDENT, an identifier in the internal encoding, return a
version of IDENT suitable for diagnostics in the locale character
set: either IDENT itself, or a string, allocated using
identifier_to_locale_alloc, converted to the locale character set
and using escape sequences if not representable in the locale
character set or containing control characters or invalid byte
sequences.  Existing backslashes in IDENT are not doubled, so the
result may not uniquely specify the contents of an arbitrary byte
sequence identifier.   

References cd, CONST_CAST, decode_utf8_char(), errno, i, identifier_to_locale_alloc, identifier_to_locale_free, locale_encoding, locale_utf8, and NULL.

Referenced by announce_function(), default_tree_make_json_for_path(), default_tree_printer(), dump_fancy_name(), expand_expr_real_1(), compiler_logical_location::get_name_with_scope_for_tree(), compiler_logical_location::get_short_name_for_tree(), lhd_print_error_function(), pp_tree_identifier(), resolve_operand_name_1(), symtab_node::verify_base(), and cgraph_node::verify_node().

◆ obstack_append_string() [1/2]

static void obstack_append_string ( obstack * ostack,
const char * str )
Append STR to OSTACK, without a null-terminator.   

Referenced by urlify_quoted_string().

◆ obstack_append_string() [2/2]

static void obstack_append_string ( obstack * ostack,
const char * str,
size_t len )
Append STR to OSTACK, without a null-terminator.   

◆ pp_append_r()

static void pp_append_r ( pretty_printer * pp,
const char * start,
int length )
Append to the output area of PRETTY-PRINTER a string specified by its
STARTing character and LENGTH.   

References output_buffer_append_r(), and pp_buffer().

Referenced by pretty_printer::emit_prefix(), pp_append_text(), and pp_unicode_character().

◆ pp_append_text()

void pp_append_text ( pretty_printer * pp,
const char * start,
const char * end )
Append a string delimited by START and END to the output area of
PRETTY-PRINTER.  No line wrapping is done.  However, if beginning a
new line then emit PRETTY-PRINTER's prefix and skip any leading
whitespace if appropriate.  The caller must ensure that it is
safe to do so.   

References pretty_printer::emit_prefix(), end(), pp_append_r(), pp_buffer(), and pp_is_wrapping_line.

Referenced by dump_fancy_name(), pretty_printer::format(), pp_maybe_wrap_text(), pp_tree_identifier(), and pp_wrap_text().

◆ pp_begin_quote()

void pp_begin_quote ( pretty_printer * pp,
bool show_color )
Add a localized open quote, and if SHOW_COLOR is true, begin colorizing
using the "quote" color.   

References colorize_start(), open_quote, and pp_string().

Referenced by decls_mismatched_attributes(), and pretty_printer::format().

◆ pp_character()

◆ pp_clear_output_area()

◆ pp_destroy_prefix()

void pp_destroy_prefix ( pretty_printer * pp)
Free PRETTY-PRINTER's prefix, a previously malloc()'d string.   

Referenced by diagnostic_append_note().

◆ pp_end_quote()

void pp_end_quote ( pretty_printer * pp,
bool show_color )
If SHOW_COLOR is true, stop colorizing.
Add a localized close quote.   

References close_quote, colorize_stop(), and pp_string().

Referenced by decls_mismatched_attributes(), and pretty_printer::format().

◆ pp_flush()

◆ pp_format_verbatim()

void pp_format_verbatim ( pretty_printer * pp,
text_info * text )
Helper subroutine of output_verbatim and verbatim. Do the appropriate
settings needed by BUFFER for a verbatim formatting.   

References pp_format(), pp_output_formatted_text(), pp_set_verbatim_wrapping(), and pp_wrapping_mode().

Referenced by pp_verbatim(), and verbatim().

◆ pp_formatted_text()

◆ pp_indent()

void pp_indent ( pretty_printer * pp)
Insert enough spaces into the output area of PRETTY-PRINTER to bring
the column position to the current indentation level, assuming that a
newline has just been written to the buffer.   

References i, pp_indentation(), and pp_space.

Referenced by pretty_printer::emit_prefix(), pp_newline_and_indent(), json::array::print(), and json::object::print().

◆ pp_last_position_in_text()

const char * pp_last_position_in_text ( const pretty_printer * pp)
Return a pointer to the last character emitted in PRETTY-PRINTER's
output area.  A NULL pointer means no character available.   

References output_buffer_last_position_in_text(), and pp_buffer().

◆ pp_maybe_wrap_text()

static void pp_maybe_wrap_text ( pretty_printer * pp,
const char * start,
const char * end )
Same as pp_wrap_text but wrap text only when in line-wrapping mode.   

References end(), pp_append_text(), pp_is_wrapping_line, and pp_wrap_text().

Referenced by quoting_info::handle_phase_3(), pp_quoted_string(), and pp_string().

◆ pp_newline()

void pp_newline ( pretty_printer * pp)

◆ pp_newline_and_flush()

◆ pp_newline_and_indent()

void pp_newline_and_indent ( pretty_printer * pp,
int n )

◆ pp_output_formatted_text()

◆ pp_printf()

◆ pp_quoted_string()

static void pp_quoted_string ( pretty_printer * pp,
const char * str,
size_t n )
Append the leading N characters of STRING to the output area of
PRETTY-PRINTER, quoting in hexadecimal non-printable characters.
Setting N = -1 is as if N were set to strlen (STRING).  The STRING
may be line-wrapped if in appropriate mode.   

References decode_utf8_char(), gcc_checking_assert, last, and pp_maybe_wrap_text().

Referenced by pretty_printer::format().

◆ pp_really_flush()

void pp_really_flush ( pretty_printer * pp)
Flush the content of BUFFER onto the attached stream independently
of the value of pp->output_buffer->flush_p.   

References pretty_printer::clear_state(), pp_buffer(), and pp_write_text_to_stream().

◆ pp_separate_with()

void pp_separate_with ( pretty_printer * pp,
char c )

References pp_character(), and pp_space.

◆ pp_set_line_maximum_length()

void pp_set_line_maximum_length ( pretty_printer * pp,
int length )
Sets the number of maximum characters per line PRETTY-PRINTER can
output in line-wrapping mode.  A LENGTH value 0 suppresses

References pp_line_cutoff(), and pretty_printer::set_real_maximum_length().

Referenced by common_handle_option().

◆ pp_string()

void pp_string ( pretty_printer * pp,
const char * str )
Append a STRING to the output area of PRETTY-PRINTER; the STRING may
be line-wrapped if in appropriate mode.   

References gcc_checking_assert, and pp_maybe_wrap_text().

Referenced by gcc_rich_location::add_fixit_insert_formatted(), asan_add_global(), asan_dynamic_init_call(), asan_emit_stack_protection(), graphviz_out::begin_td(), graphviz_out::begin_tr(), graphviz_out::begin_trtd(), pretty_printer::begin_url(), decls_mismatched_attributes(), default_diagnostic_start_span_fn(), default_tree_printer(), do_niy(), draw_cfg_node(), irange_bitmask::dump(), dump_array_domain(), dump_binary_rhs(), dump_block_node(), dump_decl_name(), digraph< GraphTraits >::dump_dot_to_pp(), dump_function_declaration(), dump_function_name(), dump_generic_node(), dump_gimple_asm(), dump_gimple_assign(), dump_gimple_assume(), dump_gimple_call(), dump_gimple_call_args(), dump_gimple_cond(), dump_gimple_fmt(), dump_gimple_label(), dump_gimple_mem_ops(), dump_gimple_omp_atomic_load(), dump_gimple_omp_atomic_store(), dump_gimple_omp_block(), dump_gimple_omp_continue(), dump_gimple_omp_critical(), dump_gimple_omp_for(), dump_gimple_omp_masked(), dump_gimple_omp_ordered(), dump_gimple_omp_parallel(), dump_gimple_omp_return(), dump_gimple_omp_scan(), dump_gimple_omp_scope(), dump_gimple_omp_sections(), dump_gimple_omp_single(), dump_gimple_omp_target(), dump_gimple_omp_task(), dump_gimple_omp_taskgroup(), dump_gimple_omp_teams(), dump_gimple_phi(), dump_gimple_return(), dump_gimple_switch(), dump_gimple_transaction(), dump_gimple_try(), dump_implicit_edges(), dump_location(), dump_mem_ref(), dump_omp_atomic_memory_order(), dump_omp_clause(), dump_omp_context_selector(), dump_omp_iterators(), dump_omp_loop_non_rect_expr(), dump_ssaname_info(), dump_ternary_rhs(), ana::one_way_id_map< T >::dump_to_pp(), ana::record_layout::item::dump_to_pp(), diagnostic_event::meaning::dump_to_pp(), dump_unary_rhs(), dump_context::emit_item(), dump_pretty_printer::emit_items(), graphviz_out::end_td(), graphviz_out::end_tdtr(), graphviz_out::end_tr(), pretty_printer::end_url(), fixup_debug_use(), pretty_printer::format(), gimple_dump_bb_for_graph(), pp_begin_quote(), pp_cfg_jump(), pp_double_int(), pp_end_quote(), pp_gimple_stmt_1(), pp_output_formatted_text(), pp_points_to_solution(), pp_wide_int_large(), pretty_print_string(), ana::dynamic_call_info_t::print(), ana::rewind_info_t::print(), json::array::print(), json::float_number::print(), json::integer_number::print(), json::literal::print(), json::object::print(), diagnostic_context::print_any_cwe(), diagnostic_context::print_any_rules(), print_call_name(), edited_line::print_content(), print_declaration(), edited_file::print_diff(), edited_file::print_diff_hunk(), print_escaped_json_string(), print_escaped_string(), print_exp(), vrange_printer::print_frange_nan(), print_insn(), print_insn_with_notes(), print_int_bound(), print_irange_bitmasks(), print_lto_docs_link(), diagnostic_context::print_option_information(), print_parseable_fixits(), print_pattern(), vrange_printer::print_real_value(), edited_file::print_run_of_changed_lines(), print_struct_decl(), print_value(), simd_clone_mangle(), start_graph_dump(), pair_fusion_bb_info::track_access(), ubsan_type_descriptor(), vrange_printer::visit(), vrange_printer::visit(), vrange_printer::visit(), and vrange_printer::visit().

◆ pp_take_prefix()

char * pp_take_prefix ( pretty_printer * pp)

◆ pp_unicode_character()

void pp_unicode_character ( pretty_printer * pp,
unsigned c )
Append code point C to the output area of PRETTY-PRINTER, encoding it
as UTF-8.   

References limits, and pp_append_r().

◆ pp_verbatim()

void pp_verbatim ( pretty_printer * pp,
const char * msg,
... )

◆ pp_wide_integer() [1/4]

template void pp_wide_integer ( pretty_printer * ,
const poly_int64 &  )

◆ pp_wide_integer() [2/4]

template void pp_wide_integer ( pretty_printer * ,
const poly_uint16 &  )

◆ pp_wide_integer() [3/4]

template void pp_wide_integer ( pretty_printer * ,
const poly_uint64 &  )

◆ pp_wide_integer() [4/4]

template<unsigned int N, typename T >
void pp_wide_integer ( pretty_printer * pp,
const poly_int< N, T > & x )

◆ pp_wrap_text()

static void pp_wrap_text ( pretty_printer * pp,
const char * start,
const char * end )
Wrap a text delimited by START and END into PRETTY-PRINTER.   

References end(), pp_append_text(), pp_is_wrapping_line, pp_newline(), pp_space, and pretty_printer::remaining_character_count_for_line().

Referenced by pp_maybe_wrap_text().

◆ pp_write_text_as_dot_label_to_stream()

void pp_write_text_as_dot_label_to_stream ( pretty_printer * pp,
bool for_record )
As pp_write_text_to_stream, but for GraphViz label output.

Flush the formatted text of pretty-printer PP onto the attached stream.
Replace characters in PPF that have special meaning in a GraphViz .dot

This routine is not very fast, but it doesn't have to be as this is only
be used by routines dumping intermediate representations in graph form.   

References fputc(), gcc_assert, pp_buffer(), pp_clear_output_area(), pp_formatted_text(), and output_buffer::stream.

Referenced by gimple_dump_bb_for_graph(), rtl_dump_bb_for_graph(), and start_graph_dump().

◆ pp_write_text_as_html_like_dot_to_stream()

void pp_write_text_as_html_like_dot_to_stream ( pretty_printer * pp)
As pp_write_text_to_stream, but for GraphViz HTML-like strings.

Flush the formatted text of pretty-printer PP onto the attached stream,
escaping these characters
  " & < >
using XML escape sequences.

http://www.graphviz.org/doc/info/lang.html#html states:
   special XML escape sequences for ", &, <, and > may be necessary in
   order to embed these characters in attribute values or raw text
This doesn't list "'" (which would normally be escaped in XML
as "&apos;" or in HTML as "&#39;");.

Experiments show that escaping "'" doesn't seem to be necessary.   

References fputc(), pp_buffer(), pp_clear_output_area(), pp_formatted_text(), and output_buffer::stream.

◆ pp_write_text_to_stream()

◆ urlify_quoted_string()

static size_t urlify_quoted_string ( pretty_printer * pp,
obstack * obstack,
const urlifier * urlifier,
size_t quoted_text_start_idx,
size_t quoted_text_end_idx )
Given quoted text within the buffer OBSTACK
at the half-open interval [QUOTED_TEXT_START_IDX, QUOTED_TEXT_END_IDX),
potentially use URLIFIER (if non-null) to see if there's a URL for the
quoted text.

If so, replace the quoted part of the text in the buffer with a URLified
version of the text, using PP's settings.

For example, given this is the buffer:
  "this is a test `hello worldTRAILING-CONTENT"
with the quoted text starting at the 'h' of "hello world", the buffer
  "this is a test `BEGIN_URL(URL)hello worldEND(URL)TRAILING-CONTENT"

Return the new offset into the buffer of the quoted text endpoint i.e.
the offset of "TRAILING-CONTENT" in the above.   

References free(), gcc_unreachable, get_end_url_string(), urlifier::get_url_for_quoted_text(), pretty_printer::get_url_format(), obstack, obstack_append_string(), pretty_printer::supports_urls_p(), URL_FORMAT_BEL, URL_FORMAT_NONE, and URL_FORMAT_ST.

Referenced by quoting_info::handle_phase_3(), and quoting_info::on_end_quote().

Variable Documentation

◆ identifier_to_locale_alloc

void *(* identifier_to_locale_alloc) (size_t) ( size_t ) = xmalloc
Allocator for identifier_to_locale and corresponding function to
free memory.   

Referenced by general_init(), and identifier_to_locale().

◆ identifier_to_locale_free

void(* identifier_to_locale_free) (void *) ( void * ) = free