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

#include <user_diagnostics.hpp>

Inheritance diagram for porytiles2::UserDiagnostics:

Public Member Functions
virtual	~UserDiagnostics ()=default

void	note (const std::string &tag, const std::string &msg) const
	Display a tagged informational note message.

virtual void	note (const std::string &tag, const std::vector< std::string > &lines) const =0
	Display a multi-line tagged informational note message.

void	warn_note (const std::string &tag, const std::string &msg) const
	Display a note message with a warning tag.

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

void	warn (const std::string &tag, const std::string &msg) const
	Display a tagged warning message.

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

void	err (const std::string &tag, const std::string &msg) const
	Display a tagged error message.

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

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.

Detailed Description

Abstract interface 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:

Notes: Informational messages for user awareness
Warning Notes: Notes that are emitted in concert with a particular warning
Warnings: Non-fatal issues with categorization tags
Errors: Serious issues requiring attention
Fatal Errors: Complete failure scenarios with full error context

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

Definition at line 30 of file user_diagnostics.hpp.

Constructor & Destructor Documentation

◆ ~UserDiagnostics()

virtual porytiles2::UserDiagnostics::~UserDiagnostics ( )

virtualdefault

Member Function Documentation

◆ emit_fatal_proximate()

virtual void porytiles2::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 porytiles2::BufferedUserDiagnostics, and porytiles2::StderrStyledUserDiagnostics.

◆ emit_fatal_root()

virtual void porytiles2::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 porytiles2::BufferedUserDiagnostics, and porytiles2::StderrStyledUserDiagnostics.

◆ emit_fatal_step()

virtual void porytiles2::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 porytiles2::BufferedUserDiagnostics, and porytiles2::StderrStyledUserDiagnostics.

◆ err() [1/2]

void porytiles2::UserDiagnostics::err	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

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.

Parameters

tag	Categorization tag for the error
msg	The error message to display

Definition at line 145 of file user_diagnostics.hpp.

◆ err() [2/2]

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

pure virtual

Display a multi-line tagged error message.

Virtual method for displaying multi-line error messages. 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 porytiles2::BufferedUserDiagnostics, and porytiles2::StderrStyledUserDiagnostics.

◆ fatal()

template<typename T , typename E >

void porytiles2::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 217 of file user_diagnostics.hpp.

◆ note() [1/2]

void porytiles2::UserDiagnostics::note	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Display a tagged informational note message.

Notes are the lowest severity diagnostic level, used for informational messages that help users understand what's happening without indicating any problems. They include a categorization tag to help users understand and/or filter the type of note being reported.

Parameters

tag	Categorization tag for the note
msg	The informational message to display

Definition at line 45 of file user_diagnostics.hpp.

◆ note() [2/2]

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

pure virtual

Display a multi-line tagged informational note message.

Virtual method for displaying multi-line informational messages. Implementations typically format the first line with a "note:" prefix and subsequent lines with appropriate indentation.

Parameters

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

Implemented in porytiles2::BufferedUserDiagnostics, and porytiles2::StderrStyledUserDiagnostics.

◆ warn() [1/2]

void porytiles2::UserDiagnostics::warn	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

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.

Parameters

tag	Categorization tag for the warning
msg	The warning message to display

Definition at line 99 of file user_diagnostics.hpp.

◆ warn() [2/2]

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

pure virtual

Display a multi-line tagged warning message.

Virtual method for displaying multi-line warnings with categorization. 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 porytiles2::BufferedUserDiagnostics, and porytiles2::StderrStyledUserDiagnostics.

◆ warn_note() [1/2]

void porytiles2::UserDiagnostics::warn_note	(	const std::string &	tag,
		const std::string &	msg
	)		const

inline

Display a note message with a warning tag.

Warning notes are note messages that are emitted in concert with a specific warning. They have tags so that like warnings they can be filtered by the user.

Parameters

tag	Categorization tag for the warning note
msg	The warning note message to display

Definition at line 72 of file user_diagnostics.hpp.

◆ warn_note() [2/2]

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

pure virtual

Display a multi-line tagged warning note message.

Virtual method for displaying multi-line warning notes with categorization. Implementations typically format these with note-style prefixes but include the tag for categorization purposes.

Parameters

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

Implemented in porytiles2::BufferedUserDiagnostics, and porytiles2::StderrStyledUserDiagnostics.

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

Porytiles2/include/porytiles2/xcut/diagnostics/user_diagnostics.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~UserDiagnostics()

Member Function Documentation

◆ emit_fatal_proximate()

◆ emit_fatal_root()

◆ emit_fatal_step()

◆ err() [1/2]

◆ err() [2/2]

◆ fatal()

◆ note() [1/2]

◆ note() [2/2]

◆ warn() [1/2]

◆ warn() [2/2]

◆ warn_note() [1/2]

◆ warn_note() [2/2]