xerror

Documentation

Overview

Package xerror implements helpers for errors

Index

• func TryUnwrap[T any](val T, err error) T
• type Stack
• type StackTrace
  • func (st StackTrace) Format(s fmt.State, verb rune)
• type XError
  • func New(format string, args ...any) *XError
  • func Unwrap(err error) *XError
  • func Wrap(cause error, message ...any) *XError
  • func (e *XError) Error() string
  • func (e *XError) Format(s fmt.State, verb rune)
  • func (e *XError) Id(id string) *XError
  • func (e *XError) Info() *errInfo
  • func (e *XError) Is(target error) bool
  • func (e *XError) StackTrace() StackTrace
  • func (e *XError) Stacks() []*Stack
  • func (e *XError) Unwrap() error
  • func (e *XError) Values() map[string]any
  • func (e *XError) With(key string, value any) *XError
  • func (e *XError) Wrap(cause error) *XError

Examples

• New
• TryUnwrap
• Wrap
• XError.Id
• XError.Info
• XError.Is
• XError.StackTrace
• XError.Unwrap
• XError.Values
• XError.With
• XError.Wrap

Functions

func TryUnwrap

func TryUnwrap[T any](val T, err error) T

TryUnwrap if err is nil then it returns a valid value If err is not nil, Unwrap panics with err. Play: https://go.dev/play/p/w84d7Mb3Afk

Example

result1 := TryUnwrap(strconv.Atoi("42"))
fmt.Println(result1)

_, err := strconv.Atoi("4o2")
defer func() {
	v := recover()
	result2 := reflect.DeepEqual(err.Error(), v.(*strconv.NumError).Error())
	fmt.Println(result2)
}()

TryUnwrap(strconv.Atoi("4o2"))

Output:

42
true

Types

type Stack

type Stack struct {
	Func string `json:"func"`
	File string `json:"file"`
	Line int    `json:"line"`
}

Stack contains function, file and line number info in the stack trace.

type StackTrace

type StackTrace []frame

StackTrace is array of frame. It's exported for compatibility with github.com/pkg/errors

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.

type XError

type XError struct {
	// contains filtered or unexported fields
}

XError is to handle error related information.

func New

func New(format string, args ...any) *XError

New creates a new XError with message

Example

err := New("error")
fmt.Println(err.Error())

Output:

error

func Unwrap

func Unwrap(err error) *XError

Unwrap returns unwrapped XError from err by errors.As. If no XError, returns nil

func Wrap

func Wrap(cause error, message ...any) *XError

Wrap creates a new XError and add message.

Example

err := New("wrong password")
wrapErr := Wrap(err, "error")

fmt.Println(wrapErr.Error())

Output:

error: wrong password

func (*XError) Error

func (e *XError) Error() string

Error implements standard error interface.

func (*XError) Format

func (e *XError) Format(s fmt.State, verb rune)

Format returns: - %v, %s, %q: formatted message - %+v: formatted message with stack trace

func (*XError) Id

func (e *XError) Id(id string) *XError

Id sets id to check equality in XError.Is

Example

err1 := New("error").Id("e001")
err2 := New("error").Id("e001")
err3 := New("error").Id("e003")

equal := err1.Is(err2)
notEqual := err1.Is(err3)

fmt.Println(equal)
fmt.Println(notEqual)

Output:

true
false

func (*XError) Info

func (e *XError) Info() *errInfo

Info returns information of xerror, which can be printed.

Example

cause := errors.New("error")
err := Wrap(cause, "invalid username").Id("e001").With("level", "high")

errInfo := err.Info()

fmt.Println(errInfo.Id)
fmt.Println(errInfo.Cause)
fmt.Println(errInfo.Values["level"])
fmt.Println(errInfo.Message)

Output:

e001
error
high
invalid username

func (*XError) Is

func (e *XError) Is(target error) bool

Is checks if target error is XError and Error.id of two errors are matched.

Example

err1 := New("error").Id("e001")
err2 := New("error").Id("e001")
err3 := New("error").Id("e003")

equal := err1.Is(err2)
notEqual := err1.Is(err3)

fmt.Println(equal)
fmt.Println(notEqual)

Output:

true
false

func (*XError) StackTrace

func (e *XError) StackTrace() StackTrace

StackTrace returns stack trace which is compatible with pkg/errors

Example

err := New("error")

stacks := err.Stacks()

fmt.Println(stacks[0].Func)
fmt.Println(stacks[0].Line)

containFile := strings.Contains(stacks[0].File, "xerror_example_test.go")
fmt.Println(containFile)

Output:

github.com/duke-git/lancet/v2/xerror.ExampleXError_StackTrace
52
true

func (*XError) Stacks

func (e *XError) Stacks() []*Stack

Stacks returns stack trace array generated by pkg/errors

func (*XError) Unwrap

func (e *XError) Unwrap() error

Unwrap compatible with github.com/pkg/errors

Example

err1 := New("error").With("level", "high")
err2 := err1.Wrap(errors.New("invalid username"))

err := err2.Unwrap()

fmt.Println(err.Error())

Output:

invalid username

func (*XError) Values

func (e *XError) Values() map[string]any

Values returns map of key and value that is set by With. All wrapped xerror.XError key and values will be merged. Key and values of wrapped error is overwritten by upper xerror.XError.

Example

err := New("error").With("level", "high")

errLevel := err.Values()["level"]

fmt.Println(errLevel)

Output:

high

func (*XError) With

func (e *XError) With(key string, value any) *XError

With adds key and value related to the error object

Example

err := New("error").With("level", "high")

errLevel := err.Values()["level"]

fmt.Println(errLevel)

Output:

high

func (*XError) Wrap

func (e *XError) Wrap(cause error) *XError

Wrap creates a new XError and copy message and id to new one.

Example

err1 := New("error").With("level", "high")
err2 := err1.Wrap(errors.New("invalid username"))

fmt.Println(err2.Error())

Output:

error: invalid username