README
¶
errors
[
](https://sourcegraph.com/bytelog.org/pkg
/errors?badge)
godoc travis appveyor goreportcard appveyor
Best Practices
License
Documentation
¶
Overview ¶
Package errors implements functions to manipulate errors.
This package is a drop-in replacement for the standard errors package. It provides additional convenience methods for working with and formatting errors. As much as possible, it implements functionality by wrapping the standard library to achieve compatibility.
All errors created by this package record stack frames. They implement custom Format methods for convenient printing, and can be obtained by calling the Frame method on an error.
Example (StackTrace) ¶
When formatted with %+v or %#v, errors output a multi-line stack trace.
package main
import (
"fmt"
"bytelog.org/pkg/errors"
)
func main() {
err := errors.New("some error")
err = errors.Wrap(err, "context")
fmt.Printf("%#v", err)
}
Output: context: some error bytelog.org/pkg/errors_test.Example_stackTrace bytelog.org/pkg/errors/errors_test.go:36 bytelog.org/pkg/errors_test.Example_stackTrace bytelog.org/pkg/errors/errors_test.go:37
Index ¶
- func Any(errs ...error) error
- func As(err error, target interface{}) bool
- func Cause(err error) error
- func Is(err, target error) bool
- func New(format string, args ...interface{}) error
- func Opaque(err error) error
- func Temporary(err error) bool
- func Timeout(err error) bool
- func Unwrap(err error) error
- func Wrap(err error, format string, args ...interface{}) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.
As will panic if target is not a non-nil pointer to either a type that implements error, or to any interface type. As returns false if err is nil.
Example ¶
package main
import (
"fmt"
"os"
"bytelog.org/pkg/errors"
)
func main() {
if _, err := os.Open("non-existing"); err != nil {
var pathError *os.PathError
if errors.As(err, &pathError) {
fmt.Println("Failed at path:", pathError.Path)
} else {
fmt.Println(err)
}
}
}
Output: Failed at path: non-existing
func Cause ¶
Cause find's the final error in the err's chain.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
func Is ¶
Is reports whether any error in err's chain matches target.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.
func New ¶
New returns an error that formats according to the format specifier. Each call to New returns a distinct error value even if the text is identical.
If the format specifier includes a %w verb with an error operand, the returned error will implement an Unwrap method returning the operand. It is invalid to include more than one %w verb or to supply it with an operand that does not implement the error interface. The %w verb is otherwise a synonym for %v.
Example ¶
package main
import (
"fmt"
"bytelog.org/pkg/errors"
)
func main() {
err := errors.New("i/o error")
fmt.Println(err)
}
Output: i/o error
Example (Formatted) ¶
New optionally accepts a format specifier, akin to fmt.Errorf.
package main
import (
"fmt"
"bytelog.org/pkg/errors"
)
func main() {
err := errors.New("unexpected type: %T", uint(0))
fmt.Println(err)
}
Output: unexpected type: uint
Example (Wrapped) ¶
New can also be used to wrap an existing error, using the %w verb.
package main
import (
"fmt"
"bytelog.org/pkg/errors"
)
func main() {
err := errors.New("bad input")
fmt.Println(errors.New("could not perform action: %w", err))
}
Output: could not perform action: bad input
func Opaque ¶
Opaque returns an error with the same error formatting as err but that does not match err and cannot be unwrapped.
Example ¶
Use Opaque to prevent an error as being recognised as a timeout.
package main
import (
"fmt"
"net"
"bytelog.org/pkg/errors"
)
func main() {
err := error(&net.DNSError{
Err: "timeout after 15 seconds",
IsTimeout: true,
})
opaqueErr := errors.Opaque(err)
fmt.Println("net error is timeout:", errors.Timeout(err))
fmt.Println("opaque error is timeout:", errors.Timeout(opaqueErr))
}
Output: net error is timeout: true opaque error is timeout: false
func Temporary ¶
Temporary finds the first error in err's chain that has a Temporary method and returns true if the result of calling that Temporary method is true
func Timeout ¶
Timeout finds the first error in err's chain that has a Timeout method and returns true if the result of calling that Timeout method is true
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.
func Wrap ¶
Wrap annotates an error in the format "%s: %w", where %w is err, and %s is is a string formatted according to the format specifier. Because %w is implicit to wrap, it is invalid to include in the format specifier.
Wrap differs from New in that if a nil error is supplied, Wrap returns nil.
Example ¶
Wrap provides an explicit way of wrapping a non-nil error.
package main
import (
"encoding/json"
"fmt"
"bytelog.org/pkg/errors"
)
func main() {
var x int
err := errors.Wrap(json.Unmarshal([]byte(`0`), &x), "parse failure")
fmt.Println(err)
err = errors.Wrap(json.Unmarshal([]byte(`"0"`), &x), "parse failure")
fmt.Println(err)
}
Output: <nil> parse failure: json: cannot unmarshal string into Go value of type int
Types ¶
This section is empty.
Source Files
Directories