Documentation
¶
Overview ¶
zerrors provides additional features to standard errors package.
Build Tags: - zerrorstrace : Enables error tracing to work. Environmental Variables: - GO_ZERRORS=<value> - "file" : Output trace messages into a temporary file (case insensitive). - "stdout" : Output trace messages into the standard output (case insensitive). - "stderr" : Output trace messages into the standard error (case insensitive). - "discard" : Discard all trace messages (case insensitive). - other values are ignored.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Attrs ¶
Attrs returns error attributes as a map. If the given error implements the Attributer interface, is call the [Attributer.Attrs] internally. Attrs repeatedly unwraps the given error using errors.Unwrap. Attrs returns nil when nil error was nil.
Example ¶
package main
import (
"errors"
"fmt"
"github.com/aileron-projects/go/zerrors"
)
func main() {
e1 := errors.New("example1")
e2 := errors.New("example2")
fmt.Println(zerrors.Attrs(e1))
fmt.Println(zerrors.Attrs(fmt.Errorf("example3 [%w]", e1)))
fmt.Println(zerrors.Attrs(errors.Join(e1, e2)))
}
Output: map[msg:example1] map[msg:example3 [example1] wraps:map[msg:example1]] map[err1:map[msg:example1] err2:map[msg:example2]]
func Must ¶
Must panics if the given err is not nil. Must exits with panic(err) if the second argument err is not nil. If the err is nil, the value t is returned.
func MustNil ¶
func MustNil(err error)
MustNil panics if the given err is not nil. MustNil exits with panic(err) if the given err is not nil.
func UnwrapErr ¶
UnwrapErr returns the result of calling the Unwrap method on err. If the given err implements Unwrap() that returns an error. Otherwise, UnwrapErr returns nil.
UnwrapErr only calls a method of the form "Unwrap() error". In particular UnwrapErr does not unwrap errors returned by errors.Join. See also UnwrapErrs and errors.Unwrap.
func UnwrapErrs ¶
UnwrapErrs returns the result of calling the Unwrap method on err. If the given err implements Unwrap() that returns a []error. Otherwise, UnwrapErrs returns nil slice.
UnwrapErrs only calls a method of the form "Unwrap() []error". In particular UnwrapErrs does not unwrap errors returned by [Wrap]. UnwrapErrs can unwrap errors returned by errors.Join. See also UnwrapErr and errors.Unwrap.
Types ¶
type Attributer ¶
Attributer provides error attributes as a map.
type Definition ¶
type Definition [5]string
Definition is the error definition type. Each index has the following meanings.
0: code, name or alias for the error. (e.g. "E1234") 1: package name that the error belongs to. (e.g. "zerrors") 2: error message. (e.g. "authentication failed") 3: template of detail in [fmt.Sprintf] syntax. (e.g. "username=%s") 4: custom field . Extensible by users.
func NewDefinition ¶
func NewDefinition(code, pkg, msg, detail string) Definition
NewDefinition returns a new error definition. Only detail can be template format with fmt.Sprintf syntax.
func (Definition) Is ¶
func (d Definition) Is(err error) bool
Is returns if the target err is generated from this error definition. The err is identical to the definition when it has the type Error and both [Error.Code], [Error.Pkg] and [Error.Msg] fields are the same.
func (Definition) New ¶
func (d Definition) New(inner error, vs ...any) *Error
New returns a new Error instance from the definition with the given inner error and the arguments for detail template. New does not fill the [Error.Frames] field. Use Definition.NewStack if stack frames are necessary.
Example ¶
package main
import (
"fmt"
"io"
"github.com/aileron-projects/go/zerrors"
)
func main() {
// Define an error with detail template.
def := zerrors.NewDefinition("E123", "pkgX", "example error", "foo=%s bar=%s")
fmt.Println(def.New(nil, "FOO", "BAR").Error()) // With arguments.
fmt.Println(def.New(nil).Error()) // No arguments.
fmt.Println(def.New(nil, "FOO").Error()) // Insufficient arguments.
fmt.Println(def.New(nil, "FOO", "BAR", "BAZ").Error()) // Too many arguments.
fmt.Println(def.New(io.EOF, "FOO", "BAR").Error()) // With inner error.
}
Output: E123: pkgX: example error: foo=FOO bar=BAR E123: pkgX: example error: foo=%!s(MISSING) bar=%!s(MISSING) E123: pkgX: example error: foo=FOO bar=%!s(MISSING) E123: pkgX: example error: foo=FOO bar=BAR%!(EXTRA string=BAZ) E123: pkgX: example error: foo=FOO bar=BAR [EOF]
func (Definition) NewStack ¶
func (d Definition) NewStack(inner error, vs ...any) *Error
NewStack returns a new Error instance from the definition with the given inner error and the arguments for detail. NewTplStack fills the [Error.Frames] for stack traces. Use Definition.New if stack frames are not necessary. Note that NewStack does not fill the [Error.Frames] if the given inner error already has stack frames.
type Error ¶
type Error struct {
// Inner is the inner error.
Inner error `json:"wraps,omitempty" msgpack:"wraps,omitempty" xml:"wraps,omitempty" yaml:"wraps,omitempty"`
// Code is the error code, name or alias for the error.
// Code is compared in the [Errors.Is] method.
Code string `json:"code" msgpack:"code" xml:"code" yaml:"code"`
// Pkg is the package name that this error belongs to.
// Pkg should not be empty.
// Pkg is compared in the [Errors.Is] method.
Pkg string `json:"pkg" msgpack:"pkg" xml:"pkg" yaml:"pkg"`
// Msg is the error message.
// Msg is compared in the [Errors.Is] method.
Msg string `json:"msg" msgpack:"msg" xml:"msg" yaml:"msg"`
// Detail is the detail of this error.
// It provides additional information for the error.
// Detail is not compared in the [Errors.Is] method.
Detail string `json:"detail,omitempty" msgpack:"detail,omitempty" xml:"detail,omitempty" yaml:"detail,omitempty"`
// Ext is the user extensible field.
// Detail is not compared in the [Errors.Is] method.
Ext string `json:"ext,omitempty" msgpack:"ext,omitempty" xml:"ext,omitempty" yaml:"ext,omitempty"`
// Frames is the list of stack trace frames.
// Use [Error.WithStack] to fill this field.
Frames []Frame `json:"frames,omitempty" msgpack:"frames,omitempty" xml:"frames,omitempty" yaml:"frames,omitempty"`
}
Error is the error type. Error implements [error] and Attributer interface.
func (*Error) Attrs ¶
Attrs returns error attributes in map. Extra attributes in e.Extra is copied to the returned map.
type Frame ¶
type Frame struct {
// Pkg is go package name of the caller.
Pkg string `json:"pkg" msgpack:"pkg" toml:"pkg" xml:"pkg" yaml:"pkg"`
// File is the file name of the caller.
File string `json:"file" msgpack:"file" toml:"file" xml:"file" yaml:"file"`
// Func is the function name of the caller.
Func string `json:"func" msgpack:"func" toml:"func" xml:"func" yaml:"func"`
// Line is the line number of the caller.
Line int `json:"line" msgpack:"line" toml:"line" xml:"line" yaml:"line"`
}
Frame holds stack frame information. See also runtime.Frame.
Source Files