replace zxq.co/ripple/hanayo
This commit is contained in:
Alicia
193
vendor/github.com/ansel1/merry/README.md
generated
vendored
Normal file
193
vendor/github.com/ansel1/merry/README.md
generated
vendored
Normal file
@@ -0,0 +1,193 @@
|
||||
merry [](https://travis-ci.org/ansel1/merry) [](https://godoc.org/github.com/ansel1/merry) [](https://goreportcard.com/report/github.com/ansel1/merry)
|
||||
=====
|
||||
|
||||
Make your golang errors merry, with stacktraces, inheritance, and arbitrary additional context.
|
||||
|
||||
The package is largely based on http://github.com/go-errors/errors, with additional
|
||||
inspiration from https://github.com/go-errgo/errgo and https://github.com/amattn/deeperror.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
go get github.com/ansel1/merry
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
Merry errors work a lot like google's golang.org/x/net/context package.
|
||||
Merry errors wrap normal errors with a context of key/value pairs.
|
||||
Like contexts, merry errors are immutable: adding a key/value to an error
|
||||
always creates a new error which wraps the original.
|
||||
|
||||
`merry` comes with built-in support for adding information to errors:
|
||||
|
||||
* stacktraces
|
||||
* overriding the error message
|
||||
* HTTP status codes
|
||||
* End user error messages
|
||||
|
||||
You can also add your own additional information.
|
||||
|
||||
The stack capturing feature can be turned off for better performance, though it's pretty fast. Benchmarks
|
||||
on an early 2011 MacBook Pro, with go 1.7rc1:
|
||||
|
||||
BenchmarkNew_withStackCapture-8 1000000 1413 ns/op
|
||||
BenchmarkNew_withoutStackCapture-8 10000000 218 ns/op
|
||||
|
||||
Details
|
||||
-------
|
||||
|
||||
* New errors have a stacktrace captured where they are created
|
||||
* Add a stacktrace to existing errors (captured where they are wrapped)
|
||||
|
||||
```go
|
||||
err := lib.Read()
|
||||
return merry.Wrap(err) // no-op if err is already merry
|
||||
```
|
||||
|
||||
* Allow golang idiom of comparing an err value to an exported value, using `Is()`
|
||||
|
||||
```go
|
||||
var ParseError = merry.New("Parse error")
|
||||
|
||||
func Parse() error {
|
||||
err := ParseError.Here() // captures a stacktrace here
|
||||
merry.Is(err, ParseError) // instead of err == ParseError
|
||||
}
|
||||
```
|
||||
|
||||
* Change the message on an error, while still using `Is()` to compare to the original error
|
||||
|
||||
```go
|
||||
err := merry.WithMessage(ParseError, "Bad input")
|
||||
merry.Is(err, ParseError) // yes it is
|
||||
```
|
||||
|
||||
* `Is()` supports hierarchies of errors
|
||||
|
||||
```go
|
||||
var ParseError = merry.New("Parse error")
|
||||
var InvalidCharSet = merry.WithMessage(ParseError, "Invalid char set")
|
||||
var InvalidSyntax = merry.WithMessage(ParseError, "Invalid syntax")
|
||||
|
||||
func Parse(s string) error {
|
||||
// use chainable methods to add context
|
||||
return InvalidCharSet.Here().WithMessagef("Invalid char set: %s", "UTF-8")
|
||||
// or functions
|
||||
// return merry.WithMessagef(merry.Here(InvalidCharSet), "Invalid char set: %s", "UTF-8")
|
||||
}
|
||||
|
||||
func Check() {
|
||||
err := Parse("fields")
|
||||
merry.Is(err, ParseError) // yup
|
||||
merry.Is(err, InvalidCharSet) // yup
|
||||
merry.Is(err, InvalidSyntax) // nope
|
||||
}
|
||||
```
|
||||
|
||||
* Add an HTTP status code
|
||||
|
||||
```go
|
||||
merry.HTTPCode(errors.New("regular error")) // 500
|
||||
merry.HTTPCode(merry.New("merry error").WithHTTPCode(404)) // 404
|
||||
```
|
||||
|
||||
* Set an alternate error message for end users
|
||||
|
||||
```go
|
||||
e := merry.New("crash").WithUserMessage("nothing to see here")
|
||||
merry.UserMessage(e) // returns "nothing to see here"
|
||||
```
|
||||
|
||||
* Functions for printing error details
|
||||
|
||||
```go
|
||||
err := merry.New("boom")
|
||||
m := merry.Stacktrace(err) // just the stacktrace
|
||||
m = merry.Details(err) // error message and stacktrace
|
||||
fmt.Sprintf("%+v", err) == merry.Details(err) // errors implement fmt.Formatter
|
||||
```
|
||||
|
||||
* Add your own context info
|
||||
|
||||
```go
|
||||
err := merry.New("boom").WithValue("explosive", "black powder")
|
||||
```
|
||||
|
||||
Basic Usage
|
||||
-----------
|
||||
|
||||
The package contains functions for creating new errors with stacks, or adding a stack to `error`
|
||||
instances. Functions with add context (e.g. `WithValue()`) work on any `error`, and will
|
||||
automatically convert them to merry errors (with a stack) if necessary.
|
||||
|
||||
Capturing the stack can be globally disabled with `SetStackCaptureEnabled(false)`
|
||||
|
||||
Functions which get context values from errors also accept `error`, and will return default
|
||||
values if the error is not merry, or doesn't have that key attached.
|
||||
|
||||
All the functions which create or attach context return concrete instances of `*Error`. `*Error`
|
||||
implements methods to add context to the error (they mirror the functions and do
|
||||
the same thing). They allow for a chainable syntax for adding context.
|
||||
|
||||
Example:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"github.com/ansel1/merry"
|
||||
"errors"
|
||||
)
|
||||
|
||||
var InvalidInputs = errors.New("Input is invalid")
|
||||
|
||||
func main() {
|
||||
// create a new error, with a stacktrace attached
|
||||
err := merry.New("bad stuff happened")
|
||||
|
||||
// create a new error with format string, like fmt.Errorf
|
||||
err = merry.Errorf("bad input: %v", os.Args)
|
||||
|
||||
// capture a fresh stacktrace from this callsite
|
||||
err = merry.Here(InvalidInputs)
|
||||
|
||||
// Make err merry if it wasn't already. The stacktrace will be captured here if the
|
||||
// error didn't already have one. Also useful to cast to *Error
|
||||
err = merry.Wrap(err, 0)
|
||||
|
||||
// override the original error's message
|
||||
err.WithMessagef("Input is invalid: %v", os.Args)
|
||||
|
||||
// Use Is to compare errors against values, which is a common golang idiom
|
||||
merry.Is(err, InvalidInputs) // will be true
|
||||
|
||||
// associated an http code
|
||||
err.WithHTTPCode(400)
|
||||
|
||||
perr := parser.Parse("blah")
|
||||
err = Wrap(perr, 0)
|
||||
// Get the original error back
|
||||
merry.Unwrap(err) == perr // will be true
|
||||
|
||||
// Print the error to a string, with the stacktrace, if it has one
|
||||
s := merry.Details(err)
|
||||
|
||||
// Just print the stacktrace (empty string if err is not a RichError)
|
||||
s := merry.Stacktrace(err)
|
||||
|
||||
// Get the location of the error (the first line in the stacktrace)
|
||||
file, line := merry.Location(err)
|
||||
|
||||
// Get an HTTP status code for an error. Defaults to 500 for non-nil errors, and 200 if err is nil.
|
||||
code := merry.HTTPCode(err)
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
See inline docs for more details.
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
This package is licensed under the MIT license, see LICENSE.MIT for details.
|
||||
Reference in New Issue
Block a user