Store the stack of the caller to New, Errorf, Wrap and Wrapf (#27)

Store up to 32 stack frames for the caller to New, Errorf, Wrap, and
Wrapf.

README.md

@@ -19,14 +19,21 @@ if err != nil {
         return errors.Wrap(err, "read failed")
 }
 ```
-In addition, `errors.Wrap` records the file and line where it was called, allowing the programmer to retrieve the path to the original error.
+## 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.
+```go
+type Stack interface {
+        Stack() []uintptr
+}
+```
 ## 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 recurse the operation of errors.Wrap to retrieve the original error for inspection. Any error value which implements this interface can be inspected by `errors.Cause`.
 ```go
 type causer interface {
-     Cause() error
+        Cause() error
 }
 ```
 `errors.Cause` will recursively retrieve the topmost error which does not implement `causer`, which is assumed to be the original cause. For example:

errors.go

@@ -21,8 +21,14 @@
 //              return errors.Wrap(err, "read failed")
 //      }
 //
-// In addition, errors.Wrap records the file and line where it was called,
+// Retrieving the stack trace of an error or wrapper
-// allowing the programmer to retrieve the path to the original error.
+//
+// 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 Stack interface {
+//             Stack() []uintptr
+//     }
 //
 // Retrieving the cause of an error
 //
@@ -31,8 +37,8 @@
 // to reverse the operation of errors.Wrap to retrieve the original error
 // for inspection. Any error value which implements this interface
 //
-//     type causer interface {
+//     type Causer interface {
-//          Cause() error
+//             Cause() error
 //     }
 //
 // can be inspected by errors.Cause. errors.Cause will recursively retrieve
@@ -58,6 +64,8 @@ import (
 // stack represents a stack of programm counters.
 type stack []uintptr
 
+func (s stack) Stack() []uintptr { return s }
+
 func (s stack) Location() (string, int) {
 	return location(s[0] - 1)
 }
@@ -191,7 +199,7 @@ func Fprint(w io.Writer, err error) {
 }
 
 func callers() stack {
-	const depth = 1
+	const depth = 32
 	var pcs [depth]uintptr
 	n := runtime.Callers(3, pcs[:])
 	return pcs[0:n]

errors_test.go

@@ -187,3 +187,42 @@ func TestErrorf(t *testing.T) {
 		}
 	}
 }
+
+func TestStack(t *testing.T) {
+	type fileline struct {
+		file string
+		line int
+	}
+	tests := []struct {
+		err  error
+		want []fileline
+	}{{
+		New("ooh"), []fileline{
+			{"github.com/pkg/errors/errors_test.go", 200},
+		},
+	}, {
+		Wrap(New("ooh"), "ahh"), []fileline{
+			{"github.com/pkg/errors/errors_test.go", 204}, // this is the stack of Wrap, not New
+		},
+	}, {
+		Cause(Wrap(New("ooh"), "ahh")), []fileline{
+			{"github.com/pkg/errors/errors_test.go", 208}, // this is the stack of New
+		},
+	}}
+	for _, tt := range tests {
+		x, ok := tt.err.(interface {
+			Stack() []uintptr
+		})
+		if !ok {
+			t.Errorf("expected %#v to implement Stack()", tt.err)
+			continue
+		}
+		st := x.Stack()
+		for i, want := range tt.want {
+			file, line := location(st[i] - 1)
+			if file != want.file || line != want.line {
+				t.Errorf("frame %d: expected %s:%d, got %s:%d", i, want.file, want.line, file, line)
+			}
+		}
+	}
+}