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