Merge pull request #8 from dc0d/add-examples

add more examples

README.md

@@ -1,9 +1,15 @@
-[![GoDoc](https://godoc.org/github.com/dc0d/wrapperr?status.svg)](https://pkg.go.dev/github.com/dc0d/wrapperr)
+[![PkgGoDev](https://pkg.go.dev/badge/dc0d/wrapperr)](https://pkg.go.dev/dc0d/wrapperr)
 
-# here
+# wrapperr
 
-a pick at _where the logging happens_ vs _where the error happened_ in Go
+> a pick at _where the logging happens_ vs _where the error happened_ in Go
 
-## TODO
+Many Go modules for logging provide the option to log where the methods of the logger are called. For example the `logger.Error(someError)` could be called inside a file named _service.go_, from a function named `gitrepo.com/user/module/service-pkg/Connect(...)`.
 
-- ...
+That's useful information.
+
+But **where** the actual error - `someError` - is coming from?
+
+This library provides a utility for enhancing the error with information about the call stack. Which is very helpful especially while working on legacy code-bases.
+
+Also the root cause error can be accessed using the standard `errors.Unwrap(error)` function at any step.

example_1_test.go

@@ -0,0 +1,32 @@
+package wrapperr_test
+
+import (
+	"errors"
+
+	"github.com/dc0d/wrapperr"
+)
+
+func end1() error {
+	return wrapperr.WithStack(errors.New("OP-ERR"))
+}
+
+func caller1() error {
+	return end1()
+}
+
+func begin1() error {
+	return caller1()
+}
+
+func ExampleWithStack() {
+	err := begin1()
+	show(err)
+
+	// Output:
+	// stack: .../example_1_test.go:10 github.com/dc0d/wrapperr_test.end1
+	// >> .../example_1_test.go:14 github.com/dc0d/wrapperr_test.caller1
+	// >> .../example_1_test.go:18 github.com/dc0d/wrapperr_test.begin1
+	// >> .../example_1_test.go:22 github.com/dc0d/wrapperr_test.ExampleWithStack
+	// >> ...:0 ... - rest of stack
+	// cause: OP-ERR
+}

example_2_test.go

@@ -0,0 +1,32 @@
+package wrapperr_test
+
+import (
+	"errors"
+
+	"github.com/dc0d/wrapperr"
+)
+
+func end2() error {
+	return wrapperr.WithStack(errors.New("OP-ERR"))
+}
+
+func caller2() error {
+	return wrapperr.WithStack(end2(), "some notes on the call stack")
+}
+
+func begin2() error {
+	return caller2()
+}
+
+func ExampleWithStack_withAnnotation() {
+	err := begin2()
+	show(err)
+
+	// Output:
+	// stack: .../example_2_test.go:10 github.com/dc0d/wrapperr_test.end2
+	// >> .../example_2_test.go:14 github.com/dc0d/wrapperr_test.caller2 - some notes on the call stack
+	// >> .../example_2_test.go:18 github.com/dc0d/wrapperr_test.begin2
+	// >> .../example_2_test.go:22 github.com/dc0d/wrapperr_test.ExampleWithStack_withAnnotation
+	// >> ...:0 ... - rest of stack
+	// cause: OP-ERR
+}

example_3_test.go

@@ -0,0 +1,63 @@
+package wrapperr_test
+
+import (
+	"errors"
+
+	"github.com/dc0d/wrapperr"
+)
+
+func end3() error {
+	return wrapperr.WithStack(errors.New("OP-ERR"))
+}
+
+func caller3() error {
+	return wrapperr.WithStack(end3(), "some notes on the call stack")
+}
+
+func begin3() error {
+	return caller3()
+}
+
+func ExampleWithStack_toJSON() {
+	err := begin3()
+	showJSON(err)
+
+	// Output:
+	// {
+	//   "stack": [
+	//     {
+	//       "loc": {
+	//         "file": ".../example_3_test.go:10",
+	//         "func": "github.com/dc0d/wrapperr_test.end3"
+	//       }
+	//     },
+	//     {
+	//       "loc": {
+	//         "file": ".../example_3_test.go:14",
+	//         "func": "github.com/dc0d/wrapperr_test.caller3"
+	//       },
+	//       "message": "some notes on the call stack"
+	//     },
+	//     {
+	//       "loc": {
+	//         "file": ".../example_3_test.go:18",
+	//         "func": "github.com/dc0d/wrapperr_test.begin3"
+	//       }
+	//     },
+	//     {
+	//       "loc": {
+	//         "file": ".../example_3_test.go:22",
+	//         "func": "github.com/dc0d/wrapperr_test.ExampleWithStack_toJSON"
+	//       }
+	//     },
+	//     {
+	//       "loc": {
+	//         "file": "...:0",
+	//         "func": "..."
+	//       },
+	//       "message": "rest of stack"
+	//     }
+	//   ],
+	//   "cause": "OP-ERR"
+	// }
+}

examples_test.go

@@ -0,0 +1,65 @@
+package wrapperr_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"path"
+	"strings"
+
+	"github.com/dc0d/wrapperr"
+)
+
+func show(err error) {
+	terr, ok := err.(wrapperr.TracedErr)
+	if !ok {
+		fmt.Println(err)
+		return
+	}
+
+	var stack wrapperr.Stack
+	for _, v := range terr.Stack {
+		if !strings.Contains(v.Loc.Func, "wrapperr") {
+			v.Loc.Line = 0
+			v.Loc.File = "..."
+			v.Loc.Func = "..."
+			v.Message = "rest of stack"
+			stack = append(stack, v)
+			break
+		}
+		v.Loc.File = ".../" + path.Base(v.Loc.File)
+		stack = append(stack, v)
+	}
+	terr.Stack = stack
+
+	fmt.Println(terr)
+}
+
+func showJSON(err error) {
+	terr, ok := err.(wrapperr.TracedErr)
+	if !ok {
+		fmt.Println(err)
+		return
+	}
+
+	var stack wrapperr.Stack
+	for _, v := range terr.Stack {
+		if !strings.Contains(v.Loc.Func, "wrapperr") {
+			v.Loc.Line = 0
+			v.Loc.File = "..."
+			v.Loc.Func = "..."
+			v.Message = "rest of stack"
+			stack = append(stack, v)
+			break
+		}
+		v.Loc.File = ".../" + path.Base(v.Loc.File)
+		stack = append(stack, v)
+	}
+	terr.Stack = stack
+
+	js, err := json.MarshalIndent(terr, "", "  ")
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(string(js))
+}

stack.go

@@ -14,7 +14,7 @@ func (stack Stack) String() string {
 	for _, note := range stack {
 		lines = append(lines, note.String())
 	}
-	return strings.Join(lines, " \n>> ")
+	return strings.Join(lines, "\n>> ")
 }
 
 func WithStack(err error, message ...string) error {

stack_test.go

@@ -47,7 +47,7 @@ func (suiteStack) toString(t *testing.T) {
 			},
 		}
 
-		expectedString = "file-1:1 fn1 - message-1 \n>> file-2:2 fn2 - message-2"
+		expectedString = "file-1:1 fn1 - message-1\n>> file-2:2 fn2 - message-2"
 	}
 
 	actualString := fmt.Sprint(stack)