errors

README

errors

errors is an extension of and drop in replacement for the standard library errors package. Multiple errors can be composed into a single error with the Compose function, or a single error can be extended by adding context using the Extend function. The result can be checked for the presense of a specific error using Contains. If any of the underlying composed or extended errors or extensions match, Contains will return true.

This package is especially beneficial during testing, where you may wish to check for presense of a specific error, but that specific error may be extending another error or may have been extended by another function somewhere else in the call stack.

Example:

var errOne = errors.New("one")
var errTwo = errors.New("two")
_, errDNE = os.Open("file.txt")

extended := errors.Extend(errOne, errDNE)    // "[one; open file.txt: no such file or directory]"
extended2 := errors.Extend(errTwo, extended) // "[two; one; open file.txt: no such file or directory]"
errors.IsOSNotExist(extended)                // true
errors.Contains(extended, errDNE)            // true
errors.Contains(extended, errOne)            // true
errors.Contains(extended, errTwo)            // false
errors.Contains(extended2, errTwo)           // true

The Compose function works similarly to extend, however instead of simply combining the two errors into a joined set, a new Error is created that contains both underlying errors individually. The Contains and IsOSNotExist functions will still work as expected, returning true if they apply to any of the nested underlying errors.

var errOne = errors.New("one")
var errTwo = errors.New("two")
composed := errors.Compose(errOne, errTwo)                         // "[[one]; [two]]"
composed2 := errors.Compose(errOne, errors.Extend(errTwo, errTwo)) // "[[one]; [two; two]]"
errors.Contains(composed2, errTwo) // true

Documentation

Overview

Package errors is an extension of and drop in replacement for the standard library errors package. Multiple errors can be composed into a single error, and single errors can be extended with new errors or with context. You can also check whether any of the extensions or compositions contains a certain error, allowing for more flexible error handling for complex processes.

Index

• func AddContext(err error, context string) error
• func Compose(errs ...error) error
• func Contains(base, cmp error) bool
• func Extend(err, extension error) error
• func IsOSNotExist(err error) bool
• func New(s string) error
• type Error
  • func (r Error) Error() string

Functions

func AddContext

func AddContext(err error, context string) error

AddContext will add a string context to an error if the error is not nil. If the error is nil, then nil will be returned regardless of the context.

func Compose

func Compose(errs ...error) error

Compose will compose all errors together into a single error, remembering each component error so that they can be checked for matches later using the `Contains` function.

Any `nil` input errors will be ignored. If all input errors are `nil`, then `nil` will be returned.

func Contains

func Contains(base, cmp error) bool

Contains will check whether the base error contains the cmp error. If the base err is a Error, then it will check whether there is a match on any of the underlying errors.

func Extend

func Extend(err, extension error) error

Extend will extend the first error with the second error, remembering each component error so that they can be checked for matches later using the `Contains` function.

Any `nil` input will be ignored. If both inputs are `nil, then `nil` will be returned.

func IsOSNotExist

func IsOSNotExist(err error) bool

IsOSNotExist returns true if any of the errors in the underlying composition return true for os.IsNotExist.

func New

func New(s string) error

New is a passthrough to the stdlib errors package, allowing NebulousLabs/errors to be a drop in replacement for the standard library errors package.

Types

type Error

type Error struct {
	ErrSet []error
}

Error satisfies the error interface, and additionally keeps track of all extensions and compositions that have happened to the underlying errors.

func (Error) Error

func (r Error) Error() string

Error returns the composed error string of the Error, clustering errors by their composition and extension.