README

Yet another errors package for Go.

Import as zgo.at/errors; godoc.

This is based on the new errors API introduced in Go 1.13 with the additions:

  1. Add Wrap(err, "some context") and Wrapf(err, "some context", ...), which return nil if the passed error is nil.

    I tried using the fmt.Errorf("...: %w", err) pattern, but I found I missed being able to do:

    func f() error {
    return errors.Wrap(f2(), "context")
}

    Which I find much more convenient than:

    func f() error {
    err := f2()
    if err != nil {
        return fmt.Errorf("context: %w", err)
    }
    return nil
}

  2. A stack trace is added with erorrs.New(), errors.Errorf(), and erorrs.Wrap() I know it's not needed with appropriate context but sometimes I accidentally add the same context more than once, or just want to quickly see where exactly the error is coming from. Especially on dev it's much more convenient.

    You can use errors.Package to only add stack traces for a specific package. For example errors.Package = "zgo.at/goatcounter" will only add trace lines in zgo.at/goatcounter/...

    You can control the maximum stack size with errors.StackSize; set to 0 to disable adding stack traces altogether (i.e. on production).

  3. Group type for collecting grouped errors:

     errs := NewGroup(20)  // 20 is the maximum amount of errors
 for {
     err := doStuff()
     if err.Append(err) { // Won't append on nil, returns false if it's nil.
         continue
     }
 }

 fmt.Println(errs)        // Print all errors (if any).
 return errs.ErrorOrNil() // No errors? Returns nil.
Expand ▾ Collapse ▴

Documentation

Overview

Package errors adds some useful error helpers.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Package to add trace lines for; if blank all traces are added.
	Package string

	// StackSize is the maximum stack sized added to errors. Set to 0 to
	// disable.
	StackSize int = 32
)

Functions

func As 

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

func Errorf 

func Errorf(f string, a ...interface{}) error

func Is 

func Is(err, target error) bool

func New 

func New(text string) error

func Unwrap 

func Unwrap(err error) error

func Wrap 

func Wrap(err error, s string) error

Wrap an error with fmt.Errorf(), returning nil if err is nil.

func Wrapf 

func Wrapf(err error, format string, a ...interface{}) error

Wrapf an error with fmt.Errorf(), returning nil if err is nil.

Types

type Group 

type Group struct {
	// Maximum number of errors; calls to Append() won't do anything if the
	// number of errors is larger than this.
	MaxSize int
	// contains filtered or unexported fields
}

Group multiple errors.

func NewGroup 

func NewGroup(maxSize int) *Group

NewGroup create a new Group instance. It will record a maximum of maxSize errors. Set to 0 for no limit.

func (*Group) Append 

func (g *Group) Append(err error) bool

Append a new error to the list; this is thread-safe.

It won't do anything if the error is nil, in which case it will return false. This makes appending errors in a loop slightly nicer: 

for {
    err := do()
    if errors.Append(err) {
        continue
    }
}

func (Group) Error 

func (g Group) Error() string

func (*Group) ErrorOrNil 

func (g *Group) ErrorOrNil() error

ErrorOrNil returns itself if there are errors, or nil otherwise.

It avoids an if-check at the end: 

return errs.ErrorOrNil()

func (Group) Len 

func (g Group) Len() int

Len returns the number of errors.

type StackErr 

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

func (StackErr) Error 

func (err StackErr) Error() string

func (StackErr) StackTrace 

func (err StackErr) StackTrace() string

func (StackErr) Unwrap 

func (err StackErr) Unwrap() error

type StackTracer 

type StackTracer interface {
	StackTrace() string
}

Source Files

View all