Error Domain API Guidelines

Core Semantics

exception = throwable failure with a human-readable local reason
diagnostic = structured, renderable representation of one failure
cause = optional exception from a genuinely separate failure layer
platform context = native failure data owned by its domain diagnostic, not a cause

Primary Types

Exception // base class for all Erbsland Core exceptions
Diagnostic // abstract structured representation of one failure

Secondary Types

LogicError, RuntimeError // programming and domain-neutral runtime failures
ParameterError, OutOfRangeError // invalid argument and bounds failures
OverflowError, ParseError // representation and text-parsing failures
ErrorDocumentBuilder // shared builder for consistently styled error documents
DiagnosticHelper // adapter from exceptions and cause chains to diagnostic documents
❮domain❯::❮Type❯Error // domain specific error

Pattern Definitions

V = ❮DiagnosticData❯ // domain-specific diagnostic data

Exception Patterns

T() // create an exception with an empty reason
T(reason[, cause]) // create an exception with a reason and optional cause
T(context[, cause]) // create a domain exception from structured context
o.what() -> mem::UnsafeConstCharPtr // expose the reason at the standard exception boundary
o.reason() -> const text::String& // stored human-readable reason
o.hasCause() -> bool // test if a chained diagnostic cause is available
o.cause() -> std::exception_ptr // access the chained diagnostic cause
o.toString() -> text::String // local display text for one exception
o.diagnostic() -> DiagnosticConstPtr // abstract diagnostic for one exception
o.toTextDocument([displayText]) -> text::TextDocument // render one diagnostic with optional display text

Error Context Patterns

T(title[, description]) // create context with common diagnostic text
T(title, domainValue) // create context with domain-specific data
o.setDescription(text) -> T& // chained setters to build context
o.set❮DomainData❯(data) -> T& // adding domain specific data
o.❮domainData❯() -> V // accessing the data for building diagnostics

Throw Helper Patterns

throw❮Error❯(...) // implementation helper used only to break include cycles
❮operation❯OrThrow(...) -> T // throwing variant of an otherwise non-throwing operation