Add Newf, Joinf, Messagef, remove WithWrapper, update docs

Author: MDobak

README.md

@@ -3,5 +3,6 @@
 // that simplify common error handling tasks by adding support for stack
 // traces, combining multiple errors, and simplifying working with panics.
 // The package maintains full compatibility with Go's standard error handling
-// features (Go 1.13+), including errors.As, errors.Is, and errors.Unwrap.
+// features (including changes in Go 1.13 and 1.20), such as errors.As,
+// errors.Is, and errors.Unwrap.
 package xerrors

doc.go

@@ -13,8 +13,8 @@ var errWriter io.Writer = os.Stderr
 
 // Print writes a formatted error to stderr.
 //
-// If the error implements the [ErrorDetails] interface, the result
-// of [ErrorDetails] is used for each wrapped error. Otherwise, the
+// If the error implements the [DetailedError] interface, the result
+// of [DetailedError] is used for each wrapped error. Otherwise, the
 // standard Error method is used. The formatted error can span
 // multiple lines and always ends with a newline.
 func Print(err error) {
@@ -23,8 +23,8 @@ func Print(err error) {
 
 // Sprint returns a formatted error as a string.
 //
-// If the error implements the [ErrorDetails] interface, the result
-// of [ErrorDetails] is used for each wrapped error. Otherwise, the
+// If the error implements the [DetailedError] interface, the result
+// of [DetailedError] is used for each wrapped error. Otherwise, the
 // standard Error method is used. The formatted error can span
 // multiple lines and always ends with a newline.
 func Sprint(err error) string {
@@ -35,8 +35,8 @@ func Sprint(err error) string {
 
 // Fprint writes a formatted error to the provided [io.Writer].
 //
-// If the error implements the [ErrorDetails] interface, the result
-// of [ErrorDetails] is used for each wrapped error. Otherwise, the
+// If the error implements the [DetailedError] interface, the result
+// of [DetailedError] is used for each wrapped error. Otherwise, the
 // standard Error method is used. The formatted error can span
 // multiple lines and always ends with a newline.
 func Fprint(w io.Writer, err error) (int, error) {
@@ -45,36 +45,39 @@ func Fprint(w io.Writer, err error) (int, error) {
 
 // fprint is a helper function that writes the formatted error to the
 // given [io.Writer].
-func fprint(w io.Writer, e error) (n int, err error) {
+//
+// This function will print all errors in the chain, that implement the
+// [DetailedError] interface, with the exception of the first error, which
+// will be printed using the standard Error method if it doesn't implement
+// the [DetailedError] interface.
+func fprint(w io.Writer, err error) (int, error) {
 	const firstErrorPrefix = "Error: "
 	const previousErrorPrefix = "Previous error: "
 	var buffer bytes.Buffer
 	first := true
-	for e != nil {
-		switch terr := e.(type) {
-		case ErrorDetails:
+	for err != nil {
+		switch tErr := err.(type) {
+		case DetailedError:
 			if first {
 				buffer.WriteString(firstErrorPrefix)
 			} else {
 				buffer.WriteString(previousErrorPrefix)
 			}
-			buffer.WriteString(terr.Error())
-			buffer.WriteByte('\n')
-			buffer.WriteString(terr.ErrorDetails())
+			buffer.WriteString(tErr.DetailedError())
 		default:
-			// If an error does not implement the ErrorDetails interface,
-			// then the Error() method will print all errors separated
+			// If an error does not implement the DetailedError interface,
+			// then the Error() method should print all errors separated
 			// with ":", so there is no need to render each error other than
 			// the first one.
 			if first {
 				buffer.WriteString(firstErrorPrefix)
-				buffer.WriteString(terr.Error())
+				buffer.WriteString(tErr.Error())
 				buffer.WriteByte('\n')
 			}
 		}
 		first = false
-		if we, ok := e.(unwrapper); ok {
-			e = we.Unwrap()
+		if wErr, ok := err.(interface{ Unwrap() error }); ok {
+			err = wErr.Unwrap()
 			continue
 		}
 		break

format.go

@@ -16,8 +16,8 @@ func (e testErr) Error() string {
 	return e.err
 }
 
-func (e testErr) ErrorDetails() string {
-	return e.details + "\n"
+func (e testErr) DetailedError() string {
+	return e.err + "\n" + e.details + "\n"
 }
 
 func (e testErr) Unwrap() error {
@@ -32,9 +32,6 @@ func TestFormat(t *testing.T) {
 		{
 			err: Message("foo"), want: "Error: foo\n",
 		},
-		{
-			err: WithWrapper(Message("foo"), Message("bar")), want: "Error: foo: bar\n",
-		},
 		{
 			err:  testErr{err: "err", details: "details"},
 			want: "Error: err\ndetails\n",
@@ -73,7 +70,7 @@ func TestPrint(t *testing.T) {
 }
 
 func TestSprint(t *testing.T) {
-	a := New("access denided")
+	a := New("access denied")
 	Print(a)
 
 	err := Message("foo")

format_test.go

@@ -6,7 +6,7 @@ import (
 	"strings"
 )
 
-const multiErrorErrorPrefix = "the following errors occurred: "
+const multiErrorPrefix = "the following errors occurred:"
 
 // Append appends the provided errors to an existing error or list of
 // errors. If `err` is not a [multiError], it will be converted into
@@ -19,6 +19,9 @@ const multiErrorErrorPrefix = "the following errors occurred: "
 // The returned error is compatible with Go errors, supporting
 // [errors.Is], [errors.As], and the Go 1.20 `Unwrap() []error`
 // method.
+//
+// To create a chained error, use [New], [Newf], [Join], or
+// [Joinf] instead.
 func Append(err error, errs ...error) error {
 	var me multiError
 	if err != nil {
@@ -54,8 +57,8 @@ type multiError []error
 // Error implements the [error] interface.
 func (e multiError) Error() string {
 	var s strings.Builder
-	s.WriteString(multiErrorErrorPrefix)
-	s.WriteString("[")
+	s.WriteString(multiErrorPrefix)
+	s.WriteString(" [")
 	for n, err := range e {
 		s.WriteString(err.Error())
 		if n < len(e)-1 {
@@ -66,9 +69,14 @@ func (e multiError) Error() string {
 	return s.String()
 }
 
-// ErrorDetails implements the [ErrorDetails] interface.
-func (e multiError) ErrorDetails() string {
+// DetailedError implements the [DetailedError] interface.
+func (e multiError) DetailedError() string {
+	if len(e) == 0 {
+		return ""
+	}
 	var s strings.Builder
+	s.WriteString(multiErrorPrefix)
+	s.WriteByte('\n')
 	for n, err := range e.Unwrap() {
 		s.WriteString(strconv.Itoa(n + 1))
 		s.WriteString(". ")

multierror.go

@@ -60,22 +60,22 @@ func TestAppend(t *testing.T) {
 	}
 }
 
-func TestMultiError_ErrorDetails(t *testing.T) {
+func TestMultiError_DetailedError(t *testing.T) {
 	tests := []struct {
 		errs   []error
 		want   string
 		regexp bool
 	}{
 		{errs: []error{}, want: ``},
-		{errs: []error{Message("a")}, want: "1. Error: a\n"},
-		{errs: []error{Message("a"), Message("b")}, want: "1. Error: a\n2. Error: b\n"},
-		{errs: []error{Message("a"), multiError{Message("b"), Message("c")}}, want: "1. Error: a\n2. Error: the following errors occurred: [b, c]\n\t1. Error: b\n\t2. Error: c\n"},
+		{errs: []error{Message("a")}, want: "the following errors occurred:\n1. Error: a\n"},
+		{errs: []error{Message("a"), Message("b")}, want: "the following errors occurred:\n1. Error: a\n2. Error: b\n"},
+		{errs: []error{Message("a"), multiError{Message("b"), Message("c")}}, want: "the following errors occurred:\n1. Error: a\n2. Error: the following errors occurred:\n\t1. Error: b\n\t2. Error: c\n"},
 	}
 	for n, tt := range tests {
 		t.Run(fmt.Sprintf("case-%d", n+1), func(t *testing.T) {
 			err := multiError(tt.errs)
-			if got := err.ErrorDetails(); got != tt.want {
-				t.Errorf("multiError(errs).ErrorDetails(): %q does not match %q", got, tt.want)
+			if got := err.DetailedError(); got != tt.want {
+				t.Errorf("multiError(errs).DetailedError(): %q does not match %q", got, tt.want)
 			}
 		})
 	}

multierror_test.go

@@ -10,20 +10,22 @@ import (
 
 const stackTraceDepth = 32
 
-// StackTrace extracts the stack trace from the given error or the
-// first wrapped error that implements [stackTracer].
+// StackTrace extracts the stack trace from the provided error.
+// It traverses the error chain, looking for the last error that
+// has a stack trace.
 func StackTrace(err error) Callers {
+	var callers Callers
 	for err != nil {
-		if e, ok := err.(stackTracer); ok {
-			return e.StackTrace()
+		if e, ok := err.(interface{ StackTrace() Callers }); ok {
+			callers = e.StackTrace()
 		}
-		if e, ok := err.(unwrapper); ok {
+		if e, ok := err.(interface{ Unwrap() error }); ok {
 			err = e.Unwrap()
 			continue
 		}
 		break
 	}
-	return nil
+	return callers
 }
 
 // WithStackTrace wraps the provided error with a stack trace,
@@ -52,9 +54,13 @@ func (e *withStackTrace) Error() string {
 	return e.err.Error()
 }
 
-// ErrorDetails implements the [ErrorDetails] interface.
-func (e *withStackTrace) ErrorDetails() string {
-	return e.stack.String()
+// DetailedError implements the [DetailedError] interface.
+func (e *withStackTrace) DetailedError() string {
+	s := &strings.Builder{}
+	s.WriteString(e.err.Error())
+	s.WriteString("\n")
+	s.WriteString(e.stack.String())
+	return s.String()
 }
 
 // Unwrap implements the Go 1.13 `Unwrap() error` method, returning
@@ -200,12 +206,6 @@ func (c Callers) writeTrace(w io.Writer) {
 	}
 }
 
-// stackTracer represents an error that provides a stack trace.
-type stackTracer interface {
-	error
-	StackTrace() Callers
-}
-
 // callers captures the current stack trace, skipping the specified
 // number of frames.
 func callers(skip int) Callers {

stacktrace.go

@@ -5,45 +5,36 @@ import (
 	"strings"
 )
 
-// WithWrapper wraps `err` with a `wrapper` error.
-//
-// The `wrapper` should generally be a simple, sentinel error, as
-// details like its stack trace are ignored. The `Unwrap` method
-// will only unwrap `err`, but [errors.Is] and [errors.As] work
-// with both `wrapper` and `err`.
-//
-// If `wrapper` is nil, `err` is returned. If `err` is nil,
-// WithWrapper returns nil.
-func WithWrapper(wrapper error, err error) error {
-	if err == nil {
-		return nil
-	}
-	if wrapper == nil {
-		return err
-	}
-	return &withWrapper{
-		wrapper: wrapper,
-		err:     err,
-	}
-}
-
 // withWrapper wraps an error with another error.
+//
+// It is intended to be build error chains, e.g. if we have a
+// following error chain: `err1: err2: err3`, the wrapper is `err1`,
+// and the err is another withWrapper containing `err2` and `err3`.
 type withWrapper struct {
-	wrapper error
-	err     error
+	wrapper error  // wrapper is the error that wraps the next error in the chain, may be nil
+	err     error  // err is the next error in the chain, must not be nil
+	msg     string // msg overwrites the error message, if set
 }
 
 // Error implements the [error] interface.
 func (e *withWrapper) Error() string {
+	if e.msg != "" {
+		return e.msg
+	}
 	s := &strings.Builder{}
-	s.WriteString(e.wrapper.Error())
-	s.WriteString(": ")
+	if e.wrapper != nil {
+		s.WriteString(e.wrapper.Error())
+		s.WriteString(": ")
+	}
 	s.WriteString(e.err.Error())
 	return s.String()
 }
 
 // Unwrap implements the Go 1.13 `Unwrap() error` method, returning
 // the wrapped error.
+//
+// Since withWrapper represents a chain of errors, the Unwrap method
+// returns the next error in the chain, not both the wrapper and the error.
 func (e *withWrapper) Unwrap() error {
 	return e.err
 }

wrapper.go

@@ -8,45 +8,42 @@ import (
 	"testing"
 )
 
-func TestWrap(t *testing.T) {
+func TestWithWrapper(t *testing.T) {
 	tests := []struct {
-		err     error
 		wrapper error
+		err     error
+		msg     string
 		want    string
-		wantNil bool
 	}{
-		{err: Message("err"), wrapper: Message("wrapper"), want: "wrapper: err"},
-		{err: io.EOF, wrapper: Message("wrapper"), want: "wrapper: EOF"},
-		{err: nil, wrapper: Message("wrapper"), wantNil: true},
-		{err: Message("err"), wrapper: nil, want: "err"},
+		{wrapper: Message("wrapper"), err: Message("err"), want: "wrapper: err"},
+		{wrapper: Message("wrapper"), err: io.EOF, want: "wrapper: EOF"},
+		{wrapper: nil, err: Message("err"), want: "err"},
+		{wrapper: Message("wrapper"), err: Message("err"), msg: "msg", want: "msg"},
 	}
 	for n, tt := range tests {
 		t.Run(fmt.Sprintf("case-%d", n+1), func(t *testing.T) {
-			got := WithWrapper(tt.wrapper, tt.err)
-			switch {
-			case tt.wantNil:
-				if got != nil {
-					t.Errorf("WithWrapper(%#v, %#v): expected nil", tt.wrapper, tt.err)
-				}
-			default:
-				if got.Error() != tt.want {
-					t.Errorf("WithWrapper(%#v, %#v): got: %q, want %q", tt.wrapper, tt.err, got, tt.want)
-				}
-				if len(StackTrace(got)) != 0 {
-					t.Errorf("WithWrapper(%#v, %#v): returned error must not contain a stack trace", tt.wrapper, tt.err)
-				}
-				if !errors.Is(got, tt.err) {
-					t.Errorf("WithWrapper(%#v, %#v): errors.Is must return true for err", tt.wrapper, tt.err)
-				}
-				if tt.wrapper != nil && !errors.Is(got, tt.wrapper) {
-					t.Errorf("WithWrapper(%#v, %#v): errors.Is must return true for wrapper", tt.wrapper, tt.err)
-				}
-				if tt.err != nil && !errors.As(got, reflect.New(reflect.TypeOf(tt.err)).Interface()) {
-					t.Errorf("errors.As(WithWrapper(%#v, %#v), err): must return true for the err error type", tt.wrapper, tt.err)
-				}
-				if tt.wrapper != nil && !errors.As(got, reflect.New(reflect.TypeOf(tt.wrapper)).Interface()) {
-					t.Errorf("errors.As(WithWrapper(%#v, %#v), err): must return true for the wrapper error type", tt.wrapper, tt.err)
-				}
+			got := &withWrapper{
+				wrapper: tt.wrapper,
+				err:     tt.err,
+				msg:     tt.msg,
+			}
+			if got.Error() != tt.want {
+				t.Errorf("WithWrapper(%#v, %#v): got: %q, want %q", tt.wrapper, tt.err, got, tt.want)
+			}
+			if len(StackTrace(got)) != 0 {
+				t.Errorf("WithWrapper(%#v, %#v): returned error must not contain a stack trace", tt.wrapper, tt.err)
+			}
+			if !errors.Is(got, tt.err) {
+				t.Errorf("WithWrapper(%#v, %#v): errors.Is must return true for err", tt.wrapper, tt.err)
+			}
+			if tt.wrapper != nil && !errors.Is(got, tt.wrapper) {
+				t.Errorf("WithWrapper(%#v, %#v): errors.Is must return true for wrapper", tt.wrapper, tt.err)
+			}
+			if tt.err != nil && !errors.As(got, reflect.New(reflect.TypeOf(tt.err)).Interface()) {
+				t.Errorf("errors.As(WithWrapper(%#v, %#v), err): must return true for the err error type", tt.wrapper, tt.err)
+			}
+			if tt.wrapper != nil && !errors.As(got, reflect.New(reflect.TypeOf(tt.wrapper)).Interface()) {
+				t.Errorf("errors.As(WithWrapper(%#v, %#v), err): must return true for the wrapper error type", tt.wrapper, tt.err)
 			}
 		})
 	}