errors

README

errors

中文README

A simple error library that supports error stacks, error codes, and error chains:

• Supports carrying stacks and constructing nested error chains

• Supports carrying error codes

• Supports customizing the depth of stack printing and error chain printing format

• Uses CallersFrames instead of FuncForPC to generate stacks, avoiding issues such as "line number errors" in special cases, see runtime: strongly encourage using CallersFrames over FuncForPC with Callers result

• Simplifies stack information when using multiple Wrap operations by only keeping the deepest stack in a chain and printing it only once.

Installation and Docs

Install using go get github.com/morrisxyang/errors.

Full documentation is available at https://pkg.go.dev/github.com/morrisxyang/errors

Quick Start

Construct error chain

func a() error {
	err := b()
	err = Wrap(err, "a failed reason")
	return err
}

func b() error {
	err := c()
	err = Wrap(err, "b failed reason")
	return err
}

func c() error {
	_, err := os.Open("test")
	if err != nil {
		return WrapWithCode(err, 123, "c failed reason")
	}
	return nil
}

Print error message. %+v will print the error stack trace and %v only prints the error message.

a failed reason
Caused by: b failed reason
Caused by: 123, c failed reason
Caused by: open test: no such file or directory
github.com/morrisxyang/errors.c
	/Users/morrisyang/Nutstore Files/go-proj/githuberrors/errors_test.go:94
github.com/morrisxyang/errors.b
	/Users/morrisyang/Nutstore Files/go-proj/githuberrors/errors_test.go:86
github.com/morrisxyang/errors.a
	/Users/morrisyang/Nutstore Files/go-proj/githuberrors/errors_test.go:80
....

Core Methods

Error Chain

• func New(msg string) error
• func Newf(format string, args ...interface{}) error
• func NewWithCode(code int, msg string) error
• func NewWithCodef(code int, format string, args ...interface{}) error
• func Wrap(e error, msg string) error
• func Wrapf(e error, format string, args ...interface{}) error
• func WrapWithCode(e error, code int, msg string) error
• func WrapWithCodef(e error, code int, format string, args ...interface{}) error

Error Handling

• func Code(e error) int
• func EffectiveCode(e error) int
• func Msg(e error) string
• func As(err error, target interface{}) bool
• func Is(err, target error) bool
• func Cause(e error) error
• func Unwrap(err error) error

Config

• type Config

• • func GetCfg() *Config

• func ResetCfg()

• func SetCfg(c *Config)

FAQ

Will multiple Wrap errors carry multiple stacks?

You can Wrap multiple times with explanatory information in the calling chain, but only the deepest Wrap operation will set the stack. Continuing to Wrap, return err and other operations will not affect the stack information.

If a suitable error code is set for an error in the chain, but not set when continuing to Wrap, how can it be obtained?

It is recommended to set the valid error code at an appropriate and clear time. You can use EffectiveCode to obtain the first valid non-zero error code outside the link layer. Due to system calls and other situations, there may be multiple errors carrying error codes in the same link, in which case the error code of the outer layer should be exposed to the outside world by default, shielding the detailed information of the inner layer.

Documentation

Overview

Package errors provides wrapped errors with stack trace.

Index

• Constants
• func As(err error, target interface{}) bool
• func Cause(e error) error
• func Code(e error) int
• func EffectiveCode(e error) int
• func Errorf(format string, args ...interface{}) error
• func Is(err, target error) bool
• func Msg(e error) string
• func New(msg string) error
• func NewWithCode(code int, msg string) error
• func NewWithCodef(code int, format string, args ...interface{}) error
• func Newf(format string, args ...interface{}) error
• func ResetCfg()
• func SetCfg(c *Config)
• func Unwrap(err error) error
• func Wrap(e error, msg string) error
• func WrapWithCode(e error, code int, msg string) error
• func WrapWithCodef(e error, code int, format string, args ...interface{}) error
• func Wrapf(e error, format string, args ...interface{}) error
• type Config
  • func GetCfg() *Config
• type StackTrace
  • func (st StackTrace) Format(s fmt.State, verb rune)

Constants

const (
	// UnknownCode is the error code for unspecified errors.
	UnknownCode = math.MinInt32
	// Success is the success prompt string.
	Success = "success"
)

Functions

func As

func As(err error, target interface{}) bool

As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.

As will panic if target is not a non-nil pointer to either a type that implements error, or to any interface type. As returns false if err is nil.

func Cause

func Cause(e error) error

Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface:

type causer interface {
       Cause() error
}

If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.

func Code

func Code(e error) int

Code function returns the error code associated with an error object if it is of type *baseError. If the error object is not of type *baseError, it returns the minimum value of int32.

func EffectiveCode

func EffectiveCode(e error) int

EffectiveCode returns the first valid error code from the error chain. If error object encountered is not of type *baseError, it will return UnknownCode.

func Errorf

func Errorf(format string, args ...interface{}) error

Errorf formats according to a format specifier and returns the string as a value that satisfies error. Errorf also records the stack trace at the point it was called.

func Is

func Is(err, target error) bool

Is reports whether any error in err's chain matches target.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.

func Msg

func Msg(e error) string

Msg function returns the error message associated with an error object if it is of type *baseError. If the error object is not of type *baseError, it returns it's Error().

func New

func New(msg string) error

New creates an error with a stack trace using the provided message

func NewWithCode

func NewWithCode(code int, msg string) error

NewWithCode creates a new error with a stack trace, using the provided code and message.

func NewWithCodef

func NewWithCodef(code int, format string, args ...interface{}) error

NewWithCodef creates a new error with a stack trace, the provided code, format specifier and arguments. This function has the same functionality as the NewWithCode function.

func Newf

func Newf(format string, args ...interface{}) error

Newf creates a new error with the provided format specifier and arguments. It has the same functionality as New function

func ResetCfg

func ResetCfg()

ResetCfg resets the global configuration to its default value.

func SetCfg

func SetCfg(c *Config)

SetCfg sets the global configuration instance.

func Unwrap

func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.

func Wrap

func Wrap(e error, msg string) error

Wrap function wraps the incoming error with stack information and message. If the incoming err already has a stack, the stack will not be set again. If the incoming err is nil, Wrap will return nil.

func WrapWithCode

func WrapWithCode(e error, code int, msg string) error

WrapWithCode function wraps the incoming error with stack information, code and message. If the incoming err already has a stack, the stack will not be set again. If the incoming err is nil, WrapWithCode will return nil.

func WrapWithCodef

func WrapWithCodef(e error, code int, format string, args ...interface{}) error

WrapWithCodef function wraps the incoming error with stack information, code, format specifier and arguments. This function has the same functionality as the WrapWithCode function.

func Wrapf

func Wrapf(e error, format string, args ...interface{}) error

Wrapf function wraps the incoming error with stack information, format specifier and arguments. This function has the same functionality as the Wrap function.

Types

type Config

type Config struct {
	StackDepth          int    // StackDepth specifies the depth of the function call stack trace. Default value is 10.
	ErrorConnectionFlag string // ErrorConnectionFlag specifies the error connection flag string. Default value is "\nCaused by: ".
}

Config represents the configuration options.

func GetCfg

func GetCfg() *Config

GetCfg retrieves the global configuration instance.

type StackTrace

type StackTrace struct {
	runtime.Frames
}

StackTrace is stack of Frames from innermost (newest) to outermost (oldest).

func (StackTrace) Format

func (st StackTrace) Format(s fmt.State, verb rune)

Format formats the stack of Frames according to the fmt.Formatter interface.

%s	lists source files for each Frame in the stack
%v	lists the source file and line number for each Frame in the stack

Format accepts flags that alter the printing of some verbs, as follows:

%+v   Prints filename, function, and line number for each Frame in the stack.