yerrors

yerrors

import "github.com/yext/yerrors"

• Overview
• Index

Overview

Package yerrors wraps 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
• func Errorf(format string, a ...interface{}) error
• func Mask(err error) error
• func Wrap(err error) error
• func WrapFrame(err error, caller int) error
• type Wrapper

Package files

doc.go fmt.go xerrors.go

Variables

var (
    New    = xerrors.New
    Is     = xerrors.Is
    As     = xerrors.As
    Unwrap = xerrors.Unwrap
    Opaque = xerrors.Opaque
)

func Errorf

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

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

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

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

type Wrapper = xerrors.Wrapper

Generated by godoc2md