The API at a glance¶

Every exported symbol in gitlab.com/phpboyscout/go/errors, grouped by what it is for. Each links to the page that gives its exact behaviour.

The package has no dependencies outside the standard library, and depfootprint_test.go fails the build if that stops being true.

Making an error¶

Symbol	Signature	Page
`New`	`New(msg string) error`	Constructors
`Newf`	`Newf(format string, args ...any) error`	Constructors
`Errorf`	`Errorf(format string, args ...any) error`	Constructors
`NewSentinel`	`NewSentinel(kind, msg string) error`	Constructors
`Wrap`	`Wrap(err error, msg string) error`	Constructors
`Wrapf`	`Wrapf(err error, format string, args ...any) error`	Constructors
`Join`	`Join(errs ...error) error`	Constructors

Annotating one¶

Symbol	Signature	Page
`WithHint`	`WithHint(err error, hint string) error`	Annotations
`WithHintf`	`WithHintf(err error, format string, args ...any) error`	Annotations
`WithDetail`	`WithDetail(err error, detail string) error`	Annotations
`WithDetailf`	`WithDetailf(err error, format string, args ...any) error`	Annotations
`WithAttrs`	`WithAttrs(err error, attrs ...slog.Attr) error`	Annotations
`WithStack`	`WithStack(err error) error`	Annotations

Reading one back¶

Symbol	Signature	Page
`Hints`	`Hints(err error) []string`	Readers
`Details`	`Details(err error) []string`	Readers
`GetAllHints`	`GetAllHints(err error) []string`	Readers
`GetAllDetails`	`GetAllDetails(err error) []string`	Readers
`FlattenHints`	`FlattenHints(err error) string`	Readers
`FlattenDetails`	`FlattenDetails(err error) string`	Readers
`Attrs`	`Attrs(err error) []slog.Attr`	Readers
`KindOf`	`KindOf(err error) string`	Readers
`StackOf`	`StackOf(err error) StackTrace`	Readers

Standard-library passthroughs¶

Symbol	Signature	Page
`Is`	`Is(err, target error) bool`	Readers
`As`	`As(err error, target any) bool`	Readers
`AsType`	`AsType[E error](err error) (E, bool)`	Readers
`Unwrap`	`Unwrap(err error) error`	Readers

Types, interfaces and constants¶

Symbol	Kind	Page
`StackTrace`	`[]uintptr`, with `String() string`	Kinds and interfaces
`Kinder`	interface — `ErrorKind() string`	Kinds and interfaces
`Payloader`	interface — `ErrorKind() string`, `ErrorPayload() any`	Kinds and interfaces
`StackTracer`	interface — `StackTrace() StackTrace`	Kinds and interfaces
`KindBasic` … `KindJoin`	eight `string` constants	Kinds and interfaces

Two rules that apply everywhere¶

Every function taking an error returns nil when given nil. That is true of Wrap, Wrapf, WithHint, WithHintf, WithDetail, WithDetailf, WithAttrs and WithStack without exception, so they compose in a return statement with no guard around them.

Readers walk the whole tree, including through an aggregate. Hints, Details, Attrs, KindOf and StackOf all descend into the members of a Join. There is one traversal in the package and every reader uses it, so none of them can drift from the others.

See Formatting and logging for what %v, %+v and a slog handler produce, and What this package does not do for the deliberate absences.