Reference¶
Lookup material: every exported symbol, every level, every exit code, every log field the handler emits, and the things the package deliberately does not do.
The pages here describe observed behaviour of the current release, checked against the source rather than restated from the design intent. Where the two differ, the behaviour is what is written down.
Which reference page answers which question¶
| You want to know | Page |
|---|---|
| What a function or type does, and what it does with bad input | API reference |
| What each method logs, and what an outcome does to it | Report levels |
Which exit code Fatal returns |
Exit codes |
| What the fields in a log line mean | Log fields |
| Whether something is supported at all | Limitations |
Every exported symbol¶
The package surface is deliberately small. This is all of it, as of v0.4.0.
| Symbol | Kind | What it is |
|---|---|---|
New |
func | Construct an ErrorHandler |
ErrorHandler |
interface | The reporting boundary: Fatal, Error, Warn, SetUsage |
StandardErrorHandler |
struct | The one implementation New returns |
HelpConfig |
interface | Supplies the support-channel message; you implement it |
ReportOption |
type | Adjusts a single report |
WithPrefix |
func | Label a report with a phase name |
Prefix |
func | Join prefix fragments |
Quietly |
func | Demote a fatal report to debug |
WithStackDepth |
func | Bound the rendered stack |
DefaultStackDepth |
const | 20 |
Outcome |
struct | How a terminal error ends: code, level, message, usage |
WithOutcome |
func | Attach an outcome to an error |
OutcomeOf |
func | Read the outermost outcome back |
UnknownSubCommand |
func | Wrap the sentinel with the offending verb |
OutcomeKind |
const | "errorhandling.outcome" |
WithExitCode |
func | Attach a process exit code to an error |
ExitCode |
func | Read the attached exit code back |
ExitCodeUsage |
const | 2, carried by the usage sentinels |
ExitCodeKind |
const | "errorhandling.exit_code" |
ErrNotImplemented |
var | Sentinel: a command stub |
NewErrNotImplemented |
func | Stub error carrying an issue-tracker link |
ErrRunSubCommand |
var | Sentinel: a parent command needs a subcommand |
ErrUnknownSubCommand |
var | Sentinel: a parent was given a verb it does not have |
ErrAssertionFailure |
var | Sentinel: a violated internal invariant |
NewAssertionFailure |
func | Create an error marked as a programming bug |
KeyError |
const | "err" |
KeyPrefix |
const | "prefix" |
KeyHelp |
const | "help" |
KeyStacktrace |
const | "stacktrace" |
The mocks subpackage adds MockErrorHandler and MockHelpConfig, both generated by
mockery — see Test error handling.
Why generated Go docs are not enough¶
pkg.go.dev carries the signatures and the doc comments, and it is the right place to look up a parameter order. What it cannot show is behaviour that emerges from how the pieces combine — the outcome that overrides the code you attached, the option that only one of three methods reads, the level a sentinel reports at whichever method you called. Those live here.