text: // Package errors provides simple error handling primitives.
  //
  // The traditional error handling idiom in Go is roughly akin to
  //
  //     if err != nil {
  //             return err
  //     }
  //
  // which applied recursively up the call stack results in error reports
  // without context or debugging information. The errors package allows
  // programmers to add context to the failure path in their code in a way
  // that does not destroy the original value of the error.
  //
  // Adding context to an error
  //
  // The errors.Wrap function returns a new error that adds context to the
  // original error by recording a stack trace at the point Wrap is called,
  // and the supplied message. For example
  //
  //     _, err := ioutil.ReadAll(r)
  //     if err != nil {
  //             return errors.Wrap(err, "read failed")
  //     }
  //
  // If additional control is required the errors.WithStack and errors.WithMessage
  // functions destructure errors.Wrap into its component operations of annotating
  // an error with a stack trace and an a message, respectively.
  //
  // Retrieving the cause of an error
  //
  // Using errors.Wrap constructs a stack of errors, adding context to the
  // preceding error. Depending on the nature of the error it may be necessary
  // to reverse the operation of errors.Wrap to retrieve the original error
  // for inspection. Any error value which implements this interface
  //
  //     type causer interface {
  //             Cause() error
  //     }
  //
  // can be inspected by errors.Cause. errors.Cause will recursively retrieve
  // the topmost error which does not implement causer, which is assumed to be
  // the original cause. For example:
  //
  //     switch err := errors.Cause(err).(type) {
  //     case *MyError:
  //             // handle specifically
  //     default:
  //             // unknown error
  //     }
  //
  // causer interface is not exported by this package, but is considered a part
  // of stable public API.
  //
  // Formatted printing of errors
  //
  // All error values returned from this package implement fmt.Formatter and can
  // be formatted by the fmt package. The following verbs are supported
  //
  //     %s    print the error. If the error has a Cause it will be
  //           printed recursively
  //     %v    see %s
  //     %+v   extended format. Each Frame of the error's StackTrace will
  //           be printed in detail.
  //
  // Retrieving the stack trace of an error or wrapper
  //
  // New, Errorf, Wrap, and Wrapf record a stack trace at the point they are
  // invoked. This information can be retrieved with the following interface.
  //
  //     type stackTracer interface {
  //             StackTrace() errors.StackTrace
  //     }
  //
  // Where errors.StackTrace is defined as
  //
  //     type StackTrace []Frame
  //
  // The Frame type represents a call site in the stack trace. Frame supports
  // the fmt.Formatter interface that can be used for printing information about
  // the stack trace of this error. For example:
  //
  //     if err, ok := err.(stackTracer); ok {
  //             for _, f := range err.StackTrace() {
  //                     fmt.Printf("%+s:%d", f)
  //             }
  //     }
  //
  // stackTracer interface is not exported by this package, but is considered a part
  // of stable public API.
  //
  // See the documentation for Frame.Format for more details.
  package errors
  
  import (
  	"fmt"
  	"io"
  )
  
  // New returns an error with the supplied message.
  // New also records the stack trace at the point it was called.
  func New(message string) error {
  	return &fundamental{
  		msg:   message,
  		stack: callers(),
  	}
  }
  
  // Errorf formats according to a format specifier and returns the string
  // as a value that satisfies error.
  // Errorf also records the stack trace at the point it was called.
  func Errorf(format string, args ...interface{}) error {
  	return &fundamental{
  		msg:   fmt.Sprintf(format, args...),
  		stack: callers(),
  	}
  }
  
  // fundamental is an error that has a message and a stack, but no caller.
  type fundamental struct {
  	msg string
  	*stack
  }
  
  func (f *fundamental) Error() string { return f.msg }
  
  func (f *fundamental) Format(s fmt.State, verb rune) {
  	switch verb {
  	case 'v':
  		if s.Flag('+') {
  			io.WriteString(s, f.msg)
  			f.stack.Format(s, verb)
  			return
  		}
  		fallthrough
  	case 's':
  		io.WriteString(s, f.msg)
  	case 'q':
  		fmt.Fprintf(s, "%q", f.msg)
  	}
  }
  
  // WithStack annotates err with a stack trace at the point WithStack was called.
  // If err is nil, WithStack returns nil.
  func WithStack(err error) error {
  	if err == nil {
  		return nil
  	}
  	return &withStack{
  		err,
  		callers(),
  	}
  }
  
  type withStack struct {
  	error
  	*stack
  }
  
  func (w *withStack) Cause() error { return w.error }
  
  func (w *withStack) Format(s fmt.State, verb rune) {
  	switch verb {
  	case 'v':
  		if s.Flag('+') {
  			fmt.Fprintf(s, "%+v", w.Cause())
  			w.stack.Format(s, verb)
  			return
  		}
  		fallthrough
  	case 's':
  		io.WriteString(s, w.Error())
  	case 'q':
  		fmt.Fprintf(s, "%q", w.Error())
  	}
  }
  
  // Wrap returns an error annotating err with a stack trace
  // at the point Wrap is called, and the supplied message.
  // If err is nil, Wrap returns nil.
  func Wrap(err error, message string) error {
  	if err == nil {
  		return nil
  	}
  	err = &withMessage{
  		cause: err,
  		msg:   message,
  	}
  	return &withStack{
  		err,
  		callers(),
  	}
  }
  
  // Wrapf returns an error annotating err with a stack trace
  // at the point Wrapf is call, and the format specifier.
  // If err is nil, Wrapf returns nil.
  func Wrapf(err error, format string, args ...interface{}) error {
  	if err == nil {
  		return nil
  	}
  	err = &withMessage{
  		cause: err,
  		msg:   fmt.Sprintf(format, args...),
  	}
  	return &withStack{
  		err,
  		callers(),
  	}
  }
  
  // WithMessage annotates err with a new message.
  // If err is nil, WithMessage returns nil.
  func WithMessage(err error, message string) error {
  	if err == nil {
  		return nil
  	}
  	return &withMessage{
  		cause: err,
  		msg:   message,
  	}
  }
  
  type withMessage struct {
  	cause error
  	msg   string
  }
  
  func (w *withMessage) Error() string { return w.msg + ": " + w.cause.Error() }
  func (w *withMessage) Cause() error  { return w.cause }
  
  func (w *withMessage) Format(s fmt.State, verb rune) {
  	switch verb {
  	case 'v':
  		if s.Flag('+') {
  			fmt.Fprintf(s, "%+v\n", w.Cause())
  			io.WriteString(s, w.msg)
  			return
  		}
  		fallthrough
  	case 's', 'q':
  		io.WriteString(s, w.Error())
  	}
  }
  
  // Cause returns the underlying cause of the error, if possible.
  // An error value has a cause if it implements the following
  // interface:
  //
  //     type causer interface {
  //            Cause() error
  //     }
  //
  // If the error does not implement Cause, the original error will
  // be returned. If the error is nil, nil will be returned without further
  // investigation.
  func Cause(err error) error {
  	type causer interface {
  		Cause() error
  	}
  
  	for err != nil {
  		cause, ok := err.(causer)
  		if !ok {
  			break
  		}
  		err = cause.Cause()
  	}
  	return err
  }
  