jbowes / cling

Clear and obvious wrapping for Go error values

cling

Clear and obvious wrapping for Go error values

Introduction

Introduction | Examples | Contributing

🚧 Disclaimer: cling is alpha quality software. The API may change without warning between revisions. 🚧

cling provides a clear and obvious error wrapping API for the new Go 2/1.13+ errors package. If you prefer a specific function over a formatting directive, and an API that returns a nil error when the error to wrap is nil, then cling is for you.

Examples

Introduction | Examples | Contributing

For complete examples and usage, see the GoDoc documentation.

Wrapping an error

err := errors.New("an error")
wrapped := cling.Wrap(err, "wrapped")

// Wrapped errors can be programatically inspected
fmt.Print(xerrors.Is(wrapped, err)) // true

Sealing an error

err := errors.New("an error")
sealed := cling.Seal(err, "sealed")

// Sealed errors cannot be programatically inspected
fmt.Print(xerrors.Is(sealed, err)) // false

Both Wrap and Seal provide format specifier versions(Wrapf, Sealf), as well.

Building APIs on cling

cling/skip implements the cling API with an additional skip argument, allowing creation of APIs on top of cling that will no report themselves in error caller frames.

Contributing

Introduction | Examples | Contributing

I would love your help!

cling is still a work in progress. You can help by:

• Opening a pull request to resolve an open issue.
• Adding a feature or enhancement of your own! If it might be big, please open an issue first so we can discuss it.
• Improving this README or adding other documentation to cling.
• Letting me know if you're using cling.