https://github.com/yext/yerrors
https://github.com/yext/yerrors
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/yext/yerrors
- Owner: yext
- License: mit
- Created: 2020-10-26T15:27:42.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-07-16T03:04:15.000Z (almost 3 years ago)
- Last Synced: 2024-07-30T14:34:06.053Z (almost 2 years ago)
- Language: Go
- Size: 14.6 KB
- Stars: 8
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# yerrors [](http://godoc.org/github.com/yext/yerrors) [](https://goreportcard.com/report/github.com/yext/yerrors)
`import "github.com/yext/yerrors"`
* [Overview](#pkg-overview)
* [Index](#pkg-index)
## Overview
Package yerrors wraps [golang.org/x/xerrors](https://golang.org/x/xerrors) to support a
no-context Wrapper.
The party line is that error traces should include meaningful context at each
step. If there's no meaningful context to add, then omitting the stack frame
is ok. This policy leads to concise stack traces, especially compared to
enterprise development in Java.
However, the ability to record a stack trace without providing context is
useful in some places, and the community-favorite `pkg/errors` supported
that. The official solution (xerrors) does not.
This package provides a no-context Wrapper that is compatible with xerrors.
### Summary
- yerrors.Wrap will add a stack frame to the error without modifying the
error's message, printed when formatted with "%+v", but not with "%v".
- yerrors.Mask does the same thing, while preventing `As` or `Is` from
introspecting the error it wraps.
- The above functionality depends on using yerrors.Errorf instead of
xerrors.Errorf, so we also supply aliases to all of the commonly-used
things within the xerrors package.
This package should be used to replace all xerrors usage, due to the last
point above.
### Example
Taking this error as an example:
err := yerrors.Errorf("some context: %w",
yerrors.Wrap(
yerrors.New("an error")))
It would include all 3 invocations in the stack trace, e.g. when printed like
this:
fmt.Printf("%+v", err)
It would include only the two pieces of content in the error message:
err.Error() == fmt.Sprintf("%v", err)
// Output: "some context: an error"
See xerrors_test.go for a complete example.
## Index
* [Variables](#pkg-variables)
* [func Errorf(format string, a ...interface{}) error](#Errorf)
* [func Mask(err error) error](#Mask)
* [func Wrap(err error) error](#Wrap)
* [func WrapFrame(err error, caller int) error](#WrapFrame)
* [type Wrapper](#Wrapper)
#### Package files
[doc.go](/src/target/doc.go) [fmt.go](/src/target/fmt.go) [xerrors.go](/src/target/xerrors.go)
## Variables
``` go
var (
New = xerrors.New
Is = xerrors.Is
As = xerrors.As
Unwrap = xerrors.Unwrap
Opaque = xerrors.Opaque
)
```
## func [Errorf](/src/target/fmt.go?s=1321:1371#L38)
``` go
func Errorf(format string, a ...interface{}) error
```
Errorf formats according to a format specifier and returns the string as a
value that satisfies error.
The returned error includes the file and line number of the caller when
formatted with additional detail enabled. If the last argument is an error
the returned error's Format method will return it if the format string ends
with ": %s", ": %v", or ": %w". If the last argument is an error and the
format string ends with ": %w", the returned error implements an Unwrap
method returning it.
If the format specifier includes a %w verb with an error operand in a
position other than at the end, the returned error will still implement an
Unwrap method returning the operand, but the error's Format method will not
return the wrapped error.
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.
## func [Mask](/src/target/xerrors.go?s=996:1022#L40)
``` go
func Mask(err error) error
```
Mask returns the given error opaquely wrapped, without additional context.
As a special case, a nil argument results in a nil return.
## func [Wrap](/src/target/xerrors.go?s=470:496#L22)
``` go
func Wrap(err error) error
```
Wrap returns the given error transparently wrapped, without additional context.
As a special case, a nil argument results in a nil return.
## func [WrapFrame](/src/target/xerrors.go?s=718:761#L31)
``` go
func WrapFrame(err error, caller int) error
```
WrapFrame is like Wrap, except uses the location a given number of stack frames up.
WrapFrame(err, 0) is equivalent to Wrap(err).
## type [Wrapper](/src/target/xerrors.go?s=170:200#L10)
``` go
type Wrapper = xerrors.Wrapper
```
- - -
Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)