errors

Documentation

Overview

Package errors provides a standard error compatible error implementation with key:value context It is based on github.com/pkg/errors package: errors returned by this package support both StackTrace() and Cause(). They also support fmt.Formatter – key:value pairs are formatted using the format flags passed to Format, and the wrapped error is asked to format itself.

Example (Cause)

package main

import (
	"fmt"

	uerrors "github.com/Akagi201/utilgo/errors"
	"github.com/pkg/errors"
)

func main() {
	var rootCause error = uerrors.From(errors.New("root cause")).
		WithValue("rootKey", "rootValue")

	var wrapped error = uerrors.From(errors.Wrap(rootCause, "wrapped")).
		WithValue("wrappedKey", "wrappedValue")

	fmt.Println("rootKey:", uerrors.GetOpt(wrapped, "rootKey"))
	fmt.Println("wrappedKey:", uerrors.GetOpt(wrapped, "wrappedKey"))

}

Output:

rootKey: rootValue
wrappedKey: wrappedValue

Example (Format)

package main

import (
	"fmt"
	"io"
	"time"

	uerrors "github.com/Akagi201/utilgo/errors"
)

func main() {
	type state struct {
		Url      string
		Duration time.Duration
	}

	err := uerrors.From(io.EOF).
		WithValue("filename", "/tmp/stuff").
		WithValue("state", state{
			"https://example.com",
			2 * time.Second,
		})

	fmt.Printf("%v\n", err)
	fmt.Printf("%+v\n", err)
	fmt.Printf("%#v\n", err)

}

Output:

[state={https://example.com 2s},filename=/tmp/stuff] EOF
[state={Url:https://example.com Duration:2s},filename=/tmp/stuff] EOF
["state"=errors_test.state{Url:"https://example.com", Duration:2000000000},"filename"="/tmp/stuff"] EOF

Example (Overriding)

package main

import (
	"fmt"

	uerrors "github.com/Akagi201/utilgo/errors"
	"github.com/pkg/errors"
)

func main() {
	var rootCause error = uerrors.From(errors.New("root cause")).
		WithValue("key", "rootValue")

	var wrapped error = uerrors.From(errors.Wrap(rootCause, "wrapped")).
		WithValue("key", "wrappedValue")

	fmt.Println("key:", uerrors.GetOpt(rootCause, "key"))
	fmt.Println("key:", uerrors.GetOpt(wrapped, "key"))

}

Output:

key: rootValue
key: wrappedValue

Example (Simple)

package main

import (
	"fmt"

	uerrors "github.com/Akagi201/utilgo/errors"
	"github.com/pkg/errors"
)

func main() {
	var err error = errors.New("fail")
	var errWithProp error = uerrors.From(err).
		WithValue("key", "value").
		WithValue("foo", "bar")

	fmt.Println("key:", uerrors.GetOpt(errWithProp, "key"))
	fmt.Println("foo:", uerrors.GetOpt(errWithProp, "foo"))

}

Output:

key: value
foo: bar

Index

• func Get(err error, key interface{}) (interface{}, bool)
• func GetOpt(err error, key interface{}) interface{}
• type ContextError
  • func From(err error) ContextError

Examples

• Package (Cause)
• Package (Format)
• Package (Overriding)
• Package (Simple)

Functions

func Get

func Get(err error, key interface{}) (interface{}, bool)

Get returns the value associated with key using the following rules to resolve key:

• If the key exists on the current error, return the value set by the last call to WithValue.
• Else, if the current error has a cause, recursively look for the key on the cause.

func GetOpt

func GetOpt(err error, key interface{}) interface{}

GetOpt is the same as Get but just returns nil if the key isn't set, to make it more convenient to use in single-value contexts.

Types

type ContextError

type ContextError interface {
	error

	fmt.Formatter

	// Returns a copy of this ContextError with the specified key/value pair.
	// Do not modify the current ContextError.
	WithValue(key, value interface{}) ContextError
	// contains filtered or unexported methods
}

ContextError An implementation of the standard error interface with key:value context. ContextError is immutable.

This interface should never be used as a return *type* for a function.

Good:

func do() error { return errors.From(…) }

Bad:

func do() ContextError { return errors.From(…) }

func From

func From(err error) ContextError

From teturns a ContextError that can be used to set key:value context on err. The original err is not modified.

Intended to be used in a fluent style, like:

return From(err).
	WithValue("someKey", someValue).
	WithValue("anotherKey", anotherValue)