Initial Commit

Author: Dean Karn

.gitignore

@@ -0,0 +1,15 @@
+# Created by .ignore support plugin (hsz.mobi)
+### Go template
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, build with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+

README.md

@@ -0,0 +1,112 @@
+Package errors
+============
+![Project status](https://img.shields.io/badge/version-1.0.0-green.svg)
+[![GoDoc](https://godoc.org/github.com/go-playground/errors?status.svg)](https://godoc.org/github.com/go-playground/errors)
+![License](https://img.shields.io/dub/l/vibe-d.svg)
+
+Package errors is an errors wrapping package to help propogate not only produce a chain of errors, but also
+stack trace, any tags(additional information) and even a Type classification system to categorize errors into types eg. Permanent vs Transient.
+
+
+Common Questions
+
+Why another package?
+Because most of the existing packages either don't take the error handling far enough, too far or down right unfriendly to use/consume. 
+
+Features
+--------
+- [x] works with go-playground/log, the Tags will be added as Field Key Values and Types will be concatenated as well when using `WithError`
+
+Installation
+------------
+
+Use go get.
+
+	go get -u github.com/go-playground/errors
+    
+Usage
+-----
+```go
+package main
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/go-playground/errors"
+)
+
+func main() {
+	err := level1("testing error")
+	fmt.Println(err)
+	if errors.HasType(err, "Permanent") {
+		// os.Exit(1)
+	}
+
+	// root error
+	cause := errors.Cause(err)
+	fmt.Println(cause)
+
+	// can even still inspect the internal error
+	fmt.Println(errors.IsErr(err, io.EOF)) // will extract the cause for you
+	fmt.Println(errors.IsErr(cause, io.EOF))
+
+	// or manually with access to base fields
+	wrapped := cause.(*errors.Wrapped)
+	fmt.Println(wrapped.Err == io.EOF)
+}
+
+func level1(value string) error {
+	if err := level2(value); err != nil {
+		return errors.Wrap(err, "level2 call failed")
+	}
+	return nil
+}
+
+func level2(value string) error {
+	err := fmt.Errorf("this is an %s", "error")
+	return errors.Wrap(err, "failed to do something").WithTypes("Permanent").WithTags(errors.T("value", value))
+}
+```
+
+or using stack only
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"strings"
+
+	"github.com/go-playground/errors"
+)
+
+func main() {
+	// maybe you just want to grab a stack trace and process on your own like go-playground/log
+	// uses it to produce a stack trace log message
+	frame := errors.Stack()
+	name := fmt.Sprintf("%n", frame)
+	file := fmt.Sprintf("%+s", frame)
+	line := fmt.Sprintf("%d", frame)
+	parts := strings.Split(file, "\n\t")
+	if len(parts) > 1 {
+		file = parts[1]
+	}
+
+	fmt.Printf("Name: %s File: %s Line: %s\n", name, file, line)
+}
+```
+
+Package Versioning
+----------
+I'm jumping on the vendoring bandwagon, you should vendor this package as I will not
+be creating different version with gopkg.in like allot of my other libraries.
+
+Why? because my time is spread pretty thin maintaining all of the libraries I have + LIFE,
+it is so freeing not to worry about it and will help me keep pouring out bigger and better
+things for you the community.
+
+License
+------
+Distributed under MIT License, please see license file in code for more details.

_examples/basic/main.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/go-playground/errors"
+)
+
+func main() {
+	err := level1("testing error")
+	fmt.Println(err)
+	if errors.HasType(err, "Permanent") {
+		// os.Exit(1)
+	}
+
+	// root error
+	cause := errors.Cause(err)
+	fmt.Println(cause)
+
+	// can even still inspect the internal error
+	fmt.Println(errors.IsErr(err, io.EOF)) // will extract the cause for you
+	fmt.Println(errors.IsErr(cause, io.EOF))
+
+	// or manually with access to base fields
+	wrapped := cause.(*errors.Wrapped)
+	fmt.Println(wrapped.Err == io.EOF)
+}
+
+func level1(value string) error {
+	if err := level2(value); err != nil {
+		return errors.Wrap(err, "level2 call failed")
+	}
+	return nil
+}
+
+func level2(value string) error {
+	err := fmt.Errorf("this is an %s", "error")
+	return errors.Wrap(err, "failed to do something").WithTypes("Permanent").WithTags(errors.T("value", value))
+}

_examples/stack/main.go

@@ -0,0 +1,24 @@
+package main
+
+import (
+	"fmt"
+
+	"strings"
+
+	"github.com/go-playground/errors"
+)
+
+func main() {
+	// maybe you just want to grab a stack trace and process on your own like go-playground/log
+	// uses it to produce a stack trace log message
+	frame := errors.Stack()
+	name := fmt.Sprintf("%n", frame)
+	file := fmt.Sprintf("%+s", frame)
+	line := fmt.Sprintf("%d", frame)
+	parts := strings.Split(file, "\n\t")
+	if len(parts) > 1 {
+		file = parts[1]
+	}
+
+	fmt.Printf("Name: %s File: %s Line: %s\n", name, file, line)
+}

errors.go

@@ -0,0 +1,52 @@
+package errors
+
+// Wrap encapsulates the error, stores a contextual prefix and automatically obtains
+// a stack trace.
+func Wrap(err error, prefix string) *Wrapped {
+	if w, ok := err.(*Wrapped); ok {
+		w.errors = append(w.errors, newWrapped(err, prefix))
+		return w
+	}
+	return &Wrapped{
+		errors: []*Wrapped{newWrapped(err, prefix)},
+	}
+}
+
+// HasType is a helper function that will recurse up from the root error and check that the provided type
+// is present using an equality check
+func HasType(err error, typ string) bool {
+	w, ok := err.(*Wrapped)
+	if !ok {
+		return false
+	}
+	for i := len(w.errors) - 1; i >= 0; i-- {
+		for j := 0; j < len(w.errors[i].Types); j++ {
+			if w.errors[i].Types[j] == typ {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// Cause extracts and returns the root error
+func Cause(err error) error {
+	if w, ok := err.(*Wrapped); ok {
+		return w.errors[0]
+	}
+	return err
+}
+
+// IsErr will fetch the root error, and check the original error against the provided type
+// eg. errors.IsErr(io.EOF)
+func IsErr(err, errType error) bool {
+	if w, ok := err.(*Wrapped); ok {
+		// if root level error
+		if len(w.errors) > 0 {
+			return w.errors[0].Err == errType
+		}
+		// already extracted error
+		return w.Err == errType
+	}
+	return err == errType
+}

errors_test.go

@@ -0,0 +1,121 @@
+package errors
+
+import (
+	"fmt"
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestWrap(t *testing.T) {
+	tests := []struct {
+		pre string
+		suf string
+	}{
+		{
+			pre: "source=TestWrap: ",
+			suf: "errors_test.go:24 prefix: this is an error",
+		},
+	}
+
+	defaultErr := fmt.Errorf("this is an %s", "error")
+
+	for i, tt := range tests {
+		err := Wrap(defaultErr, "prefix")
+		if !strings.HasSuffix(err.Error(), tt.suf) || !strings.HasPrefix(err.Error(), tt.pre) {
+			t.Fatalf("IDX: %d want %s<path>%s got %s", i, tt.pre, tt.suf, err.Error())
+		}
+	}
+}
+
+func TestTags(t *testing.T) {
+	tests := []struct {
+		err  string
+		tags []Tag
+	}{
+		{
+			err:  "key=value key2=value2",
+			tags: []Tag{T("key", "value"), T("key2", "value2")},
+		},
+	}
+
+	defaultErr := fmt.Errorf("this is an %s", "error")
+
+	for i, tt := range tests {
+		err := Wrap(defaultErr, "prefix").WithTags(tt.tags...)
+		if !strings.HasSuffix(err.Error(), tt.err) {
+			t.Fatalf("IDX: %d want %s got %s", i, tt.err, err.Error())
+		}
+	}
+}
+
+func TestTypes(t *testing.T) {
+	tests := []struct {
+		err   string
+		tags  []Tag
+		types []string
+	}{
+		{
+			err:   "types=Permanent,InternalError",
+			tags:  []Tag{T("key", "value"), T("key2", "value2")},
+			types: []string{"Permanent", "InternalError"},
+		},
+	}
+
+	defaultErr := fmt.Errorf("this is an %s", "error")
+
+	for i, tt := range tests {
+		err := Wrap(defaultErr, "prefix").WithTags(tt.tags...).WithTypes(tt.types...)
+		if !strings.HasSuffix(err.Error(), tt.err) {
+			t.Fatalf("IDX: %d want %s got %s", i, tt.err, err.Error())
+		}
+	}
+}
+
+func TestHasType(t *testing.T) {
+	tests := []struct {
+		types []string
+		typ   string
+	}{
+		{
+			types: []string{"Permanent", "internalError"},
+			typ:   "Permanent",
+		},
+	}
+
+	defaultErr := fmt.Errorf("this is an %s", "error")
+
+	for i, tt := range tests {
+		err := Wrap(defaultErr, "prefix").WithTypes(tt.types...)
+		if !HasType(err, tt.typ) {
+			t.Fatalf("IDX: %d want %t got %t", i, true, false)
+		}
+	}
+}
+
+func TestCause(t *testing.T) {
+	defaultErr := fmt.Errorf("this is an %s", "error")
+	err := Wrap(defaultErr, "prefix")
+	err = Wrap(err, "prefix2")
+	cause := Cause(err)
+	expect := "prefix: this is an error"
+	if !strings.HasSuffix(cause.Error(), expect) {
+		t.Fatalf("want %s got %s", expect, err.Error())
+	}
+}
+
+func TestIsErr(t *testing.T) {
+	err := Wrap(io.EOF, "prefix")
+	err = Wrap(err, "prefix2")
+
+	if !IsErr(err, io.EOF) {
+		t.Fatalf("want %t got %t", true, false)
+	}
+	cause := Cause(err)
+	if !IsErr(cause, io.EOF) {
+		t.Fatalf("want %t got %t", true, false)
+	}
+	if !IsErr(io.EOF, io.EOF) {
+		t.Fatalf("want %t got %t", true, false)
+	}
+}