Errors and Diagnostics

Error Types and Error Handling

Introduction

Format Error

FormatError reports invalid format patterns, mismatched format arguments, unsupported format options, and format output limit failures.

Parse Error

ParseError reports invalid text syntax. Integer parsing uses it for invalid digits, invalid or disallowed base prefixes, invalid separators, missing digits, and strict trailing characters. ParseNumberError extends parse errors with the reader status that caused numeric parsing to fail.

Diagnostics

Diagnostic documents

Diagnostics convert to neutral TextDocument trees. Use Diagnostic::toTextDocument() for one diagnostic or diagnosticDocumentFromException() for a root diagnostic with causes, then render the result with the plain or terminal document renderer. Line-oriented excerpts use the universal CodeSnippetMarker and TextNodeType::CodeSnippet nodes from the text domain.

Diagnostic metadata is represented with FieldList nodes so labels remain secondary to their values. Related field lists are introduced by a diagnostic section heading; each list aligns its own labels and values. Causes are represented recursively as sibling pairs: a “Caused By” heading with the diagnostic-cause style is followed by a Blockquote with the same style. The quote contains the diagnostic followed by the next heading and quote pair when present. This structure lets terminal styles draw a visible border for every cause depth while keeping only the root diagnostic title in the primary error color. The cause heading and its frame use a subdued bright-black style so they read as structure rather than another error title.

Developer-authored diagnostic contexts and display text are trusted. External values such as paths, command-line arguments, native messages, and foreign exception text are represented by escaped semantic nodes before rendering.

Plain rendering prefixes the root title with Error:, adds colons to section headings, indents ordinary section content by two spaces, and adds another two spaces for each cause depth. Code snippets retain compact indentation and use │ as their gutter so redirected diagnostics remain structured.

Interface

class Diagnostic : public std::enable_shared_from_this<Diagnostic>

Abstract diagnostic interface for one error.

Subclassed by erbsland::conf::impl::ConfErrorDiagnostic, erbsland::core::impl::ApplicationErrorDiagnostic, erbsland::err::impl::ExceptionDiagnostic, erbsland::network::impl::NetworkErrorDiagnostic, erbsland::options::impl::OptionErrorDiagnostic, erbsland::path::impl::PathErrorDiagnostic, erbsland::re::impl::RegExErrorDiagnostic, erbsland::stream::impl::StreamErrorDiagnostic, erbsland::system::impl::PlatformErrorDiagnostic

Public Functions

virtual text::String sourceName() const noexcept

Get the source name, if this diagnostic points to one.

virtual text::String sourcePath() const noexcept

Get the source path, if this diagnostic points to one.

virtual unit::CodeLocation location() const noexcept

Get the source location, if this diagnostic points to one.

virtual text::String toString() const noexcept

Render this diagnostic as plain text.

virtual text::TextDocument toTextDocument(const i18n::DisplayTextMapConstPtr &displayText) const

Render this diagnostic as a structured text document.

text::TextDocument toTextDocument() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

using erbsland::err::DiagnosticPtr = std::shared_ptr<Diagnostic>

Shared diagnostic pointer.

using erbsland::err::DiagnosticConstPtr = std::shared_ptr<const Diagnostic>

Shared diagnostic pointer for immutable diagnostics.

class DiagnosticHelper

A helper class to generate diagnostic documents.

Public Functions

explicit DiagnosticHelper(const std::exception &error, const i18n::DisplayTextMapConstPtr &displayText = {})

Create a helper for one exception and optional display-text map.

Parameters:

• error – The exception to convert.

• displayText – The display texts, or the English defaults if null.

DiagnosticConstPtr toDiagnostic()

Create a diagnostic for one Erbsland Core exception.

Returns:

The diagnostic for the exception itself.

text::TextDocument toDocument()

Create a diagnostic document from an Erbsland Core exception, including causes.

Returns:

The diagnostic document.

Public Static Functions

static auto documentFromError(const std::exception_ptr &errorPtr, const i18n::DisplayTextMapConstPtr &displayText = {}) -> text::TextDocument

Create a diagnostic document from an exception pointer.

Parameters:

• errorPtr – The exception pointer to convert.

• displayText – The display texts, or the English defaults if null.

Returns:

The diagnostic document.

class ErrorDocumentBuilder

Builds consistently styled error documents.

Public Functions

explicit ErrorDocumentBuilder(text::String title, text::String description = {}, const i18n::DisplayTextMapConstPtr &displayText = {})

Create a builder and add the initial title and optional description.

text::TextNodePtr addSection(text::String title)

Add a consistently styled diagnostic section heading.

void addSource(const text::String &sourceName, const text::String &sourcePath, unit::CodeLocation location)

Add available source name, path, and location fields.

text::TextDocument takeDocument()

Transfer the completed document out of this builder.

inline text::TextNodePtr root() const noexcept

Access the document root for domain-specific additions.

inline const i18n::DisplayTextMapConstPtr &displayText() const noexcept

Access the resolved display-text map.

class Exception : public std::exception

The base class for all exceptions in this library.

Subclassed by erbsland::err::LogicError, erbsland::err::RuntimeError

Public Functions

Exception() noexcept = default

Create an empty exception.

explicit Exception(text::String reason)

Create an error with the given reason text.

Parameters:

reason – The reason for the exception.

explicit Exception(text::String reason, std::exception_ptr cause)

Create an error with the given reason text and diagnostic cause.

Parameters:

• reason – The reason for the exception.

• cause – The diagnostic cause.

explicit Exception(std::string_view reason)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

explicit Exception(std::string_view reason, std::exception_ptr cause)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

mem::UnsafeConstCharPtr what() const noexcept override

Return the exception reason as a null-terminated C string.

inline const text::String &reason() const noexcept

Get the reason text for the exception.

inline bool hasCause() const noexcept

Test if this exception has a diagnostic cause.

inline std::exception_ptr cause() const noexcept

Get the diagnostic cause.

virtual text::String toString() const noexcept

Convert the error with all its details into a string.

virtual DiagnosticConstPtr diagnostic() const

Convert the error with all its details into a structured diagnostic.

class LogicError : public erbsland::err::Exception

An error that indicates a faulty logic in the program.

This class of exceptions is not meant to be caught and handled in user-code, instead they shall cause the program to abort.

Subclassed by erbsland::err::OutOfRangeError, erbsland::err::ParameterError, erbsland::random::RandomError

Public Functions

Exception() noexcept = default

Create an empty exception.

explicit Exception(text::String reason)

Create an error with the given reason text.

Parameters:

reason – The reason for the exception.

explicit Exception(text::String reason, std::exception_ptr cause)

Create an error with the given reason text and diagnostic cause.

Parameters:

• reason – The reason for the exception.

• cause – The diagnostic cause.

explicit Exception(std::string_view reason)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

explicit Exception(std::string_view reason, std::exception_ptr cause)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class OutOfRangeError : public erbsland::err::LogicError

An out-of-range error exception.

These exceptions are thrown when an operation results in an out-of-range error.

Public Functions

inline explicit OutOfRangeError(text::String reason) noexcept

Create an out-of-range error with a reason.

Parameters:

reason – The reason for the out-of-range error.

inline explicit OutOfRangeError(const std::string_view reason) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class OverflowError : public erbsland::err::RuntimeError

An overflow error exception.

These exceptions are thrown when an operation results in an overflow.

Public Functions

inline explicit OverflowError(text::String reason) noexcept

Create an overflow error exception with a reason.

Parameters:

reason – The reason for the overflow error.

inline explicit OverflowError(const std::string_view reason) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class ParameterError : public erbsland::err::LogicError

A parameter error exception.

These exceptions are thrown when you pass invalid parameters to a function. Usually not meant to be caught by the application.

Public Functions

explicit ParameterError(text::String reason, text::String parameterName) noexcept

Create an overflow error exception with a reason.

Parameters:

• reason – The reason for the overflow error.

• parameterName – The name of the parameter that caused the error.

explicit ParameterError(std::string_view reason, std::string_view parameterName) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual text::String toString() const noexcept override

Convert the error with all its details into a string.

class ParseError : public erbsland::err::RuntimeError

A parse error exception.

These exceptions are thrown when text cannot be parsed as the requested value.

Subclassed by erbsland::text::ParseNumberError

Public Types

using Position = std::variant<std::monostate, unit::CpIndex, unit::ByteIndex, unit::CodeLocation>

A position in a parsed document.

Public Functions

explicit ParseError(text::String reason, const Position &position = {}) noexcept

Create a parse error with a reason.

Parameters:

• reason – The reason for the parse error.

• position – The optional code-point position of the parse error.

explicit ParseError(std::string_view reason, const Position &position = {}) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual text::String toString() const noexcept override

Convert the error with all its details into a string.

virtual DiagnosticConstPtr diagnostic() const override

Convert the error with all its details into a structured diagnostic.

bool hasPosition() const noexcept

Test if this error has an associated position.

const Position &position() const noexcept

Get the position of the parse error.

inline unit::CpIndex codePointIndex() const noexcept

Get a code-point position or no-index if there is no code-point index.

inline unit::ByteIndex byteIndex() const noexcept

Get a byte index or no-index if there is no byte index.

inline unit::CodeLocation codeLocation() const noexcept

Get a code location or no-location if there is no code location.

class RuntimeError : public erbsland::err::Exception

A runtime exception.

Runtime exceptions are meany to be caught and handled in user-code.

Subclassed by erbsland::conf::ConfError, erbsland::core::ApplicationError, erbsland::cryptology::CryptologyError, erbsland::cryptology::TlsRecordError, erbsland::err::OverflowError, erbsland::err::ParseError, erbsland::mem::ByteCompressionError, erbsland::network::NetworkError, erbsland::network::impl::Http1ProtocolError, erbsland::network::impl::TlsProtocolError, erbsland::options::OptionError, erbsland::path::PathError, erbsland::re::RegExError, erbsland::resource::ResourceError, erbsland::stream::StreamError, erbsland::system::PlatformError, erbsland::text::EncodingError, erbsland::text::FormatError, erbsland::text::render::RenderError, erbsland::text::render::impl::ProgramError

Public Functions

Exception() noexcept = default

Create an empty exception.

explicit Exception(text::String reason)

Create an error with the given reason text.

Parameters:

reason – The reason for the exception.

explicit Exception(text::String reason, std::exception_ptr cause)

Create an error with the given reason text and diagnostic cause.

Parameters:

• reason – The reason for the exception.

• cause – The diagnostic cause.

explicit Exception(std::string_view reason)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

explicit Exception(std::string_view reason, std::exception_ptr cause)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.