Abstract class for structured error reporting and diagnostic output. More...

#include <user_diagnostics.hpp>

Inheritance diagram for porytiles::UserDiagnostics:

Public Member Functions
virtual	~UserDiagnostics ()=default

	UserDiagnostics (gsl::not_null< const TextFormatter * > format)

virtual void	remark (const std::string &tag, const std::vector< std::string > &lines) const =0
	Display a tagged remark message.

void	remark (const std::string &tag, const std::string &msg) const
	Convenience overload for single line messages.

template<typename FirstParam , typename... RestParams> requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))
void	remark (const std::string &tag, const std::string &format_str, FirstParam &&first, RestParams &&...rest) const
	Variadic template overload for formatted remark messages.

virtual void	warning (const std::string &tag, const std::vector< std::string > &lines) const =0
	Display a tagged warning message.

void	warning (const std::string &tag, const std::string &msg) const
	Convenience overload for single line messages.

template<typename FirstParam , typename... RestParams> requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))
void	warning (const std::string &tag, const std::string &format_str, FirstParam &&first, RestParams &&...rest) const
	Variadic template overload for formatted warning messages.

virtual void	error (const std::string &tag, const std::vector< std::string > &lines) const =0
	Display a tagged error message.

void	error (const std::string &tag, const std::string &msg) const
	Convenience overload for single line messages.

template<typename FirstParam , typename... RestParams> requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))
void	error (const std::string &tag, const std::string &format_str, FirstParam &&first, RestParams &&...rest) const
	Variadic template overload for formatted error messages.

virtual void	remark_note (const std::string &tag, const std::vector< std::string > &lines) const =0
	Display a tagged note message associated with a remark.

void	remark_note (const std::string &tag, const std::string &msg) const
	Convenience overload for single line messages.

template<typename FirstParam , typename... RestParams> requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))
void	remark_note (const std::string &tag, const std::string &format_str, FirstParam &&first, RestParams &&...rest) const
	Variadic template overload for formatted remark note messages.

virtual void	warning_note (const std::string &tag, const std::vector< std::string > &lines) const =0
	Display a tagged note message associated with a warning.

void	warning_note (const std::string &tag, const std::string &msg) const
	Convenience overload for single line messages.

template<typename FirstParam , typename... RestParams> requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))
void	warning_note (const std::string &tag, const std::string &format_str, FirstParam &&first, RestParams &&...rest) const
	Variadic template overload for formatted warning note messages.

virtual void	error_note (const std::string &tag, const std::vector< std::string > &lines) const =0
	Display a tagged note message associated with an error.

void	error_note (const std::string &tag, const std::string &msg) const
	Convenience overload for single line messages.

template<typename FirstParam , typename... RestParams> requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))
void	error_note (const std::string &tag, const std::string &format_str, FirstParam &&first, RestParams &&...rest) const
	Variadic template overload for formatted error note messages.

virtual void	emit_fatal_proximate (const Error &err) const =0
	Emit the proximate (immediate) error in a fatal error chain.

virtual void	emit_fatal_step (const Error &err) const =0
	Emit an intermediate step error in a fatal error chain.

virtual void	emit_fatal_root (const Error &err) const =0
	Emit the root cause error in a fatal error chain.

template<typename T , typename E >
void	fatal (const ChainableResult< T, E > &result) const
	Display a fatal error with complete error chain visualization.

const TextFormatter &	formatter () const

Detailed Description

Abstract class for structured error reporting and diagnostic output.

UserDiagnostics provides a polymorphic interface for communicating diagnostics, warnings, errors, and fatal conditions to users. The class supports multiple severity levels and integrates with the ChainableResult error system to provide hierarchical error chain visualization.

The diagnostic system categorizes output into:

Remark: Compiler messages explaining internal compiler mechanisms / decisions of possible interest to the user
Warnings: Non-fatal issues that indicate possible user input mistakes
Errors: Serious issues requiring attention, operation will die but may continue in order to generate more errors
Fatal Errors: Complete failure scenarios with full error context
Notes: Informational messages for user awareness, associated with a remark, warning, or error

All methods support both single-line messages (std::string) and multi-line messages (std::vector<std::string>) for flexible diagnostic formatting.

Definition at line 35 of file user_diagnostics.hpp.

Constructor & Destructor Documentation

◆ ~UserDiagnostics()

virtual porytiles::UserDiagnostics::~UserDiagnostics ( )

virtualdefault

◆ UserDiagnostics()

porytiles::UserDiagnostics::UserDiagnostics ( gsl::not_null< const TextFormatter * > format )

inlineexplicit

Definition at line 39 of file user_diagnostics.hpp.

Member Function Documentation

◆ emit_fatal_proximate()

virtual void porytiles::UserDiagnostics::emit_fatal_proximate ( const Error & err ) const

pure virtual

Emit the proximate (immediate) error in a fatal error chain.

Virtual method for displaying the most immediate error in a fatal error chain. This is typically the first error encountered and is displayed with the highest visual prominence.

Parameters

err	The proximate error to display

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ emit_fatal_root()

virtual void porytiles::UserDiagnostics::emit_fatal_root ( const Error & err ) const

pure virtual

Emit the root cause error in a fatal error chain.

Virtual method for displaying the root cause error in a fatal error chain. This represents the original underlying cause of the failure and is typically displayed as the final item in the error hierarchy.

Parameters

err	The root cause error to display

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ emit_fatal_step()

virtual void porytiles::UserDiagnostics::emit_fatal_step ( const Error & err ) const

pure virtual

Emit an intermediate step error in a fatal error chain.

Virtual method for displaying intermediate errors in a fatal error chain. These are errors that occurred between the proximate and root causes, typically displayed with tree-like formatting to show the error hierarchy.

Parameters

err	The step error to display

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ error() [1/3]

template<typename FirstParam , typename... RestParams>
requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))

void porytiles::UserDiagnostics::error	(	const std::string &	tag,
		const std::string &	format_str,
		FirstParam &&	first,
		RestParams &&...	rest
	)		const

inline

Variadic template overload for formatted error messages.

Enables inline formatting of error messages by accepting a format string and variadic FormatParam arguments. The format string uses fmtlib-style {} placeholders.

Example:

++

diag.error("validation", "Expected {} but got {}", expected, actual);

Template Parameters

FirstParam	Type of the first format parameter
RestParams	Types of remaining format parameters

Parameters

tag	Categorization tag for the error
format_str	Format string with `{}` placeholders
first	First parameter to substitute
rest	Remaining parameters to substitute

Definition at line 196 of file user_diagnostics.hpp.

◆ error() [2/3]

void porytiles::UserDiagnostics::error	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Convenience overload for single line messages.

Definition at line 167 of file user_diagnostics.hpp.

◆ error() [3/3]

virtual void porytiles::UserDiagnostics::error	(	const std::string &	tag,
		const std::vector< std::string > &	lines
	)		const

pure virtual

Display a tagged error message.

Errors indicate serious issues that require attention but don't necessarily cause immediate failure of the current operation. They include a categorization tag to help users understand and/or filter the type of error being reported.

Implementations typically format the first line with an "error:" prefix and subsequent lines with appropriate indentation.

Parameters

tag	Categorization tag for the error
lines	Vector of strings representing each line of the error

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ error_note() [1/3]

template<typename FirstParam , typename... RestParams>
requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))

void porytiles::UserDiagnostics::error_note	(	const std::string &	tag,
		const std::string &	format_str,
		FirstParam &&	first,
		RestParams &&...	rest
	)		const

inline

Variadic template overload for formatted error note messages.

Enables inline formatting of error note messages by accepting a format string and variadic FormatParam arguments. The format string uses fmtlib-style {} placeholders.

Example:

++

diag.error_note("validation", "See definition at {}:{}", file, line);

Template Parameters

FirstParam	Type of the first format parameter
RestParams	Types of remaining format parameters

Parameters

tag	Categorization tag for the note (should match the parent error's tag)
format_str	Format string with `{}` placeholders
first	First parameter to substitute
rest	Remaining parameters to substitute

Definition at line 360 of file user_diagnostics.hpp.

◆ error_note() [2/3]

void porytiles::UserDiagnostics::error_note	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Convenience overload for single line messages.

Definition at line 330 of file user_diagnostics.hpp.

◆ error_note() [3/3]

virtual void porytiles::UserDiagnostics::error_note	(	const std::string &	tag,
		const std::vector< std::string > &	lines
	)		const

pure virtual

Display a tagged note message associated with an error.

Notes are informational messages that further clarify a parent diagnostic. This method is specifically for notes that follow an error diagnostic, enabling proper filtering - when an error is filtered out, its associated notes can also be suppressed.

Implementations typically format the first line with a "note:" prefix and subsequent lines with appropriate indentation. All note types use identical styling regardless of parent diagnostic type.

Parameters

tag	Categorization tag for the note (should match the parent error's tag)
lines	Vector of strings representing each line of the message

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ fatal()

template<typename T , typename E >

void porytiles::UserDiagnostics::fatal ( const ChainableResult< T, E > & result ) const

inline

Display a fatal error with complete error chain visualization.

Processes a ChainableResult error chain to display a hierarchical view of all errors that led to the fatal condition. The error chain is displayed in order from proximate (immediate) cause to root cause, creating a tree-like structure that helps users understand the failure path.

The method handles three types of errors in the chain:

Proximate: The immediate error (always present)
Steps: Intermediate causes (if chain has >2 errors)
Root: The original cause (if chain has >1 error)

Precondition: result.has_value() must be false (contains an error); result.chain() must not be empty

Template Parameters

T	The success value type of the ChainableResult
E	The error type of the ChainableResult

Parameters

result The failed ChainableResult containing the error chain

Definition at line 421 of file user_diagnostics.hpp.

◆ formatter()

const TextFormatter & porytiles::UserDiagnostics::formatter ( ) const

inline

Definition at line 460 of file user_diagnostics.hpp.

◆ remark() [1/3]

template<typename FirstParam , typename... RestParams>
requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))

void porytiles::UserDiagnostics::remark	(	const std::string &	tag,
		const std::string &	format_str,
		FirstParam &&	first,
		RestParams &&...	rest
	)		const

inline

Variadic template overload for formatted remark messages.

Enables inline formatting of remark messages by accepting a format string and variadic FormatParam arguments. The format string uses fmtlib-style {} placeholders.

Example:

++

diag.remark("tile-assign", "Assigned tile {} to palette {}", tile_id, pal_idx);

Template Parameters

FirstParam	Type of the first format parameter
RestParams	Types of remaining format parameters

Parameters

tag	Categorization tag for the remark
format_str	Format string with `{}` placeholders
first	First parameter to substitute
rest	Remaining parameters to substitute

Definition at line 90 of file user_diagnostics.hpp.

◆ remark() [2/3]

void porytiles::UserDiagnostics::remark	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Convenience overload for single line messages.

Definition at line 61 of file user_diagnostics.hpp.

◆ remark() [3/3]

virtual void porytiles::UserDiagnostics::remark	(	const std::string &	tag,
		const std::vector< std::string > &	lines
	)		const

pure virtual

Display a tagged remark message.

Remarks are the lowest severity diagnostic level, used for communicating internal compiler mechanisms or decisions that may be of interest to users. Unlike notes (which clarify other remarks/warnings/errors), remarks are standalone informational messages about compiler behavior such as optimization decisions, tile assignment choices, or palette allocation strategies.

Implementations typically format the first line with a "remark:" prefix and the tag, with subsequent lines appropriately indented.

Parameters

tag	Categorization tag for the remark
lines	Vector of strings representing each line of the message

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ remark_note() [1/3]

template<typename FirstParam , typename... RestParams>
requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))

void porytiles::UserDiagnostics::remark_note	(	const std::string &	tag,
		const std::string &	format_str,
		FirstParam &&	first,
		RestParams &&...	rest
	)		const

inline

Variadic template overload for formatted remark note messages.

Enables inline formatting of remark note messages by accepting a format string and variadic FormatParam arguments. The format string uses fmtlib-style {} placeholders.

Example:

++

diag.remark_note("tile-assign", "Previous assignment was at index {}", prev_idx);

Template Parameters

FirstParam	Type of the first format parameter
RestParams	Types of remaining format parameters

Parameters

tag	Categorization tag for the note (should match the parent remark's tag)
format_str	Format string with `{}` placeholders
first	First parameter to substitute
rest	Remaining parameters to substitute

Definition at line 250 of file user_diagnostics.hpp.

◆ remark_note() [2/3]

void porytiles::UserDiagnostics::remark_note	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Convenience overload for single line messages.

Definition at line 220 of file user_diagnostics.hpp.

◆ remark_note() [3/3]

virtual void porytiles::UserDiagnostics::remark_note	(	const std::string &	tag,
		const std::vector< std::string > &	lines
	)		const

pure virtual

Display a tagged note message associated with a remark.

Notes are informational messages that further clarify a parent diagnostic. This method is specifically for notes that follow a remark diagnostic, enabling proper filtering - when a remark is filtered out, its associated notes can also be suppressed.

Implementations typically format the first line with a "note:" prefix and subsequent lines with appropriate indentation. All note types use identical styling regardless of parent diagnostic type.

Parameters

tag	Categorization tag for the note (should match the parent remark's tag)
lines	Vector of strings representing each line of the message

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ warning() [1/3]

template<typename FirstParam , typename... RestParams>
requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))

void porytiles::UserDiagnostics::warning	(	const std::string &	tag,
		const std::string &	format_str,
		FirstParam &&	first,
		RestParams &&...	rest
	)		const

inline

Variadic template overload for formatted warning messages.

Enables inline formatting of warning messages by accepting a format string and variadic FormatParam arguments. The format string uses fmtlib-style {} placeholders.

Example:

++

diag.warning("parse", "File {} has {} errors", filename, count);

Template Parameters

FirstParam	Type of the first format parameter
RestParams	Types of remaining format parameters

Parameters

tag	Categorization tag for the warning
format_str	Format string with `{}` placeholders
first	First parameter to substitute
rest	Remaining parameters to substitute

Definition at line 142 of file user_diagnostics.hpp.

◆ warning() [2/3]

void porytiles::UserDiagnostics::warning	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Convenience overload for single line messages.

Definition at line 113 of file user_diagnostics.hpp.

◆ warning() [3/3]

virtual void porytiles::UserDiagnostics::warning	(	const std::string &	tag,
		const std::vector< std::string > &	lines
	)		const

pure virtual

Display a tagged warning message.

Warnings indicate non-fatal issues that users should be aware of. They include a categorization tag to help users understand and/or filter the type of warning being reported.

Implementations typically format the first line with a "warning:" prefix and the tag, with subsequent lines appropriately indented.

Parameters

tag	Categorization tag for the warning
lines	Vector of strings representing each line of the warning

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

◆ warning_note() [1/3]

template<typename FirstParam , typename... RestParams>
requires ( !std::is_same_v<std::decay_t<FirstParam>, std::vector<FormatParam>> && std::is_constructible_v<FormatParam, FirstParam> && (std::is_constructible_v<FormatParam, RestParams> && ...))

void porytiles::UserDiagnostics::warning_note	(	const std::string &	tag,
		const std::string &	format_str,
		FirstParam &&	first,
		RestParams &&...	rest
	)		const

inline

Variadic template overload for formatted warning note messages.

Enables inline formatting of warning note messages by accepting a format string and variadic FormatParam arguments. The format string uses fmtlib-style {} placeholders.

Example:

++

diag.warning_note("parse", "Consider using {} instead", alternative);

Template Parameters

FirstParam	Type of the first format parameter
RestParams	Types of remaining format parameters

Parameters

tag	Categorization tag for the note (should match the parent warning's tag)
format_str	Format string with `{}` placeholders
first	First parameter to substitute
rest	Remaining parameters to substitute

Definition at line 305 of file user_diagnostics.hpp.

◆ warning_note() [2/3]

void porytiles::UserDiagnostics::warning_note	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Convenience overload for single line messages.

Definition at line 275 of file user_diagnostics.hpp.

◆ warning_note() [3/3]

virtual void porytiles::UserDiagnostics::warning_note	(	const std::string &	tag,
		const std::vector< std::string > &	lines
	)		const

pure virtual

Display a tagged note message associated with a warning.

Notes are informational messages that further clarify a parent diagnostic. This method is specifically for notes that follow a warning diagnostic, enabling proper filtering - when a warning is filtered out, its associated notes can also be suppressed.

Implementations typically format the first line with a "note:" prefix and subsequent lines with appropriate indentation. All note types use identical styling regardless of parent diagnostic type.

Parameters

tag	Categorization tag for the note (should match the parent warning's tag)
lines	Vector of strings representing each line of the message

Implemented in porytiles::NullUserDiagnostics, porytiles::BufferedUserDiagnostics, porytiles::FilteredUserDiagnostics, and porytiles::StderrStyledUserDiagnostics.

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

porytiles/include/porytiles/xcut/diagnostics/user_diagnostics.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~UserDiagnostics()

◆ UserDiagnostics()

Member Function Documentation

◆ emit_fatal_proximate()

◆ emit_fatal_root()

◆ emit_fatal_step()

◆ error() [1/3]

◆ error() [2/3]

◆ error() [3/3]

◆ error_note() [1/3]

◆ error_note() [2/3]

◆ error_note() [3/3]

◆ fatal()

◆ formatter()

◆ remark() [1/3]

◆ remark() [2/3]

◆ remark() [3/3]

◆ remark_note() [1/3]

◆ remark_note() [2/3]

◆ remark_note() [3/3]

◆ warning() [1/3]

◆ warning() [2/3]

◆ warning() [3/3]

◆ warning_note() [1/3]

◆ warning_note() [2/3]

◆ warning_note() [3/3]