merry

README

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)

  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()

  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

  err := merry.WithMessage(ParseError, "Bad input")
  merry.Is(err, ParseError) // yes it is
  

• Is() supports hierarchies of errors

  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

  merry.HTTPCode(errors.New("regular error")) // 500
  merry.HTTPCode(merry.New("merry error").WithHTTPCode(404)) // 404
  

• Set an alternate error message for end users

  e := merry.New("crash").WithUserMessage("nothing to see here")
  merry.UserMessage(e)  // returns "nothing to see here"
  

• Functions for printing error details

  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

  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:

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.

Documentation

Index

• Variables
• func Details(e error) string
• func HTTPCode(e error) int
• func Is(e error, originals ...error) bool
• func Location(e error) (file string, line int)
• func Message(e error) string
• func SetStackCaptureEnabled(enabled bool)
• func SetVerboseDefault(b bool)
• func SourceLine(e error) string
• func Stack(e error) []uintptr
• func StackCaptureEnabled() bool
• func Stacktrace(e error) string
• func Unwrap(e error) error
• func UserMessage(e error) string
• func Value(e error, key interface{}) interface{}
• func Values(e error) map[interface{}]interface{}
• func VerboseDefault() bool
• type Error
  • func Append(e error, msg string) Error
  • func Appendf(e error, format string, args ...interface{}) Error
  • func Errorf(format string, a ...interface{}) Error
  • func Here(e error) Error
  • func New(msg string) Error
  • func Prepend(e error, msg string) Error
  • func Prependf(e error, format string, args ...interface{}) Error
  • func UserError(msg string) Error
  • func UserErrorf(format string, a ...interface{}) Error
  • func WithHTTPCode(e error, code int) Error
  • func WithMessage(e error, msg string) Error
  • func WithMessagef(e error, format string, a ...interface{}) Error
  • func WithUserMessage(e error, msg string) Error
  • func WithUserMessagef(e error, format string, args ...interface{}) Error
  • func WithValue(e error, key, value interface{}) Error
  • func Wrap(e error) Error
  • func WrapSkipping(e error, skip int) Error

Variables

var MaxStackDepth = 50

MaxStackDepth is the maximum number of stackframes on any error.

Functions

func Details

func Details(e error) string

Details returns e.Error() and e's stacktrace and user message, if set.

func HTTPCode

func HTTPCode(e error) int

HTTPCode converts an error to an http status code. All errors map to 500, unless the error has an http code attached. If e is nil, returns 200.

func Is

func Is(e error, originals ...error) bool

Is checks whether e is equal to or wraps the original, at any depth. If e == nil, return false. This is useful if your package uses the common golang pattern of exported error constants. If your package exports an ErrEOF constant, which is initialized like this:

var ErrEOF = errors.New("End of file error")

...and your user wants to compare an error returned by your package with ErrEOF:

err := urpack.Read()
if err == urpack.ErrEOF {

...the comparison will fail if the error has been wrapped by merry at some point. Replace the comparison with:

if merry.Is(err, urpack.ErrEOF) {

func Location

func Location(e error) (file string, line int)

Location returns zero values if e has no stacktrace

func Message

func Message(e error) string

Message returns just the error message. It is equivalent to Error() when Verbose is false. The behavior of Error() is (pseudo-code):

if verbose
  Details(e)
else
  Message(e) || UserMessage(e)

If e is nil, returns "".

func SetStackCaptureEnabled

func SetStackCaptureEnabled(enabled bool)

SetStackCaptureEnabled sets stack capturing globally. Disabling stack capture can increase performance

func SetVerboseDefault

func SetVerboseDefault(b bool)

SetVerboseDefault sets the global default for verbose mode. When true, e.Error() == Details(e) When false, e.Error() == Message(e)

func SourceLine

func SourceLine(e error) string

SourceLine returns the string representation of Location's result or an empty string if there's no stracktrace.

func Stack

func Stack(e error) []uintptr

Stack returns the stack attached to an error, or nil if one is not attached If e is nil, returns nil.

func StackCaptureEnabled

func StackCaptureEnabled() bool

StackCaptureEnabled returns whether stack capturing is enabled

func Stacktrace

func Stacktrace(e error) string

Stacktrace returns the error's stacktrace as a string formatted the same way as golangs runtime package. If e has no stacktrace, returns an empty string.

func Unwrap

func Unwrap(e error) error

Unwrap returns the innermost underlying error. Only useful in advanced cases, like if you need to cast the underlying error to some type to get additional information from it. If e == nil, return nil.

func UserMessage

func UserMessage(e error) string

UserMessage returns the end-user safe message. Returns empty if not set. If e is nil, returns "".

func Value

func Value(e error, key interface{}) interface{}

Value returns the value for key, or nil if not set. If e is nil, returns nil.

func Values

func Values(e error) map[interface{}]interface{}

Values returns a map of all values attached to the error If a key has been attached multiple times, the map will contain the last value mapped If e is nil, returns nil.

func VerboseDefault

func VerboseDefault() bool

VerboseDefault returns the global default for verbose mode. When true, e.Error() == Details(e) When false, e.Error() == Message(e)

Types

type Error

type Error interface {
	error
	Appendf(format string, args ...interface{}) Error
	Append(msg string) Error
	Prepend(msg string) Error
	Prependf(format string, args ...interface{}) Error
	WithMessage(msg string) Error
	WithMessagef(format string, args ...interface{}) Error
	WithUserMessage(msg string) Error
	WithUserMessagef(format string, args ...interface{}) Error
	WithValue(key, value interface{}) Error
	Here() Error
	WithStackSkipping(skip int) Error
	WithHTTPCode(code int) Error
	fmt.Formatter
}

Error extends the standard golang `error` interface with functions for attachment additional data to the error

func Append

func Append(e error, msg string) Error

Append a message after the current error message, in the format "original: new". If e == nil, return nil.

func Appendf

func Appendf(e error, format string, args ...interface{}) Error

Appendf is the same as Append, but uses fmt.Sprintf().

func Errorf

func Errorf(format string, a ...interface{}) Error

Errorf creates a new error with a formatted message and a stack. The equivalent of golang's fmt.Errorf()

func Here

func Here(e error) Error

Here returns an error with a new stacktrace, at the call site of Here(). Useful when returning copies of exported package errors. If e is nil, returns nil.

func New

func New(msg string) Error

New creates a new error, with a stack attached. The equivalent of golang's errors.New()

func Prepend

func Prepend(e error, msg string) Error

Prepend a message before the current error message, in the format "new: original". If e == nil, return nil.

func Prependf

func Prependf(e error, format string, args ...interface{}) Error

Prependf is the same as Prepend, but uses fmt.Sprintf()

func UserError

func UserError(msg string) Error

UserError creates a new error with a message intended for display to an end user.

func UserErrorf

func UserErrorf(format string, a ...interface{}) Error

UserErrorf is like UserError, but uses fmt.Sprintf()

func WithHTTPCode

func WithHTTPCode(e error, code int) Error

WithHTTPCode returns an error with an http code attached. If e is nil, returns nil.

func WithMessage

func WithMessage(e error, msg string) Error

WithMessage returns an error with a new message. The resulting error's Error() method will return the new message. If e is nil, returns nil.

func WithMessagef

func WithMessagef(e error, format string, a ...interface{}) Error

WithMessagef is the same as WithMessage(), using fmt.Sprintf().

func WithUserMessage

func WithUserMessage(e error, msg string) Error

WithUserMessage adds a message which is suitable for end users to see. If e is nil, returns nil.

func WithUserMessagef

func WithUserMessagef(e error, format string, args ...interface{}) Error

WithUserMessagef is the same as WithMessage(), using fmt.Sprintf()

func WithValue

func WithValue(e error, key, value interface{}) Error

WithValue adds a context an error. If the key was already set on e, the new value will take precedence. If e is nil, returns nil.

func Wrap

func Wrap(e error) Error

Wrap turns the argument into a merry.Error. If the argument already is a merry.Error, this is a no-op. If e == nil, return nil

func WrapSkipping

func WrapSkipping(e error, skip int) Error

WrapSkipping turns the error arg into a merry.Error if the arg is not already a merry.Error. If e is nil, return nil. If a merry.Error is created by this call, the stack captured will skip `skip` frames (0 is the call site of `WrapSkipping()`)