// Package errors provides simple error handling primitives.

//

// The traditional error handling idiom in Go is roughly akin to

//

//     if err != nil {

//             return err

//     }

//

// which when 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,

// together with 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: annotating an error with a stack trace and with 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 that 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

//     }

//

// Although the causer interface is not exported by this package, it is

// considered a part of its stable public interface.

//

// 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

//     }

//

// The returned errors.StackTrace type 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() {

//             }

//     }

//

// Although the stackTracer interface is not exported by this package, it is

// considered a part of its stable public interface.

//

// 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 called, 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,

	}

}

// WithMessagef annotates err with the format specifier.

// If err is nil, WithMessagef returns nil.

func WithMessagef(err error, format string, args ...interface{}) error {

	if err == nil {

		return nil

	}

	return &withMessage{

		cause: err,

		msg:   fmt.Sprintf(format, args...),

	}

}

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

}