Merge pull request #8 from go-playground/updates

Author: Dean Karn

Makefile

@@ -1,14 +1,13 @@
-GOCMD=go
+GOCMD=GO111MODULE=on go
 
 linters-install:
-	@gometalinter --version >/dev/null 2>&1 || { \
+	@golangci-lint --version >/dev/null 2>&1 || { \
 		echo "installing linting tools..."; \
-		$(GOCMD) get github.com/alecthomas/gometalinter; \
-		gometalinter --install; \
+		$(GOCMD) get github.com/golangci/golangci-lint/cmd/golangci-lint; \
 	}
 
 lint: linters-install
-	gometalinter --vendor --disable-all --enable=vet --enable=vetshadow --enable=golint --enable=megacheck --enable=ineffassign --enable=misspell --enable=errcheck --enable=goconst ./...
+	golangci-lint run
 
 test:
 	$(GOCMD) test -cover -race ./...

README.md

@@ -1,6 +1,6 @@
 Package errors
 ============
-![Project status](https://img.shields.io/badge/version-3.3.0-green.svg)
+![Project status](https://img.shields.io/badge/version-4.0.0-green.svg)
 [![Build Status](https://semaphoreci.com/api/v1/joeybloggs/errors/branches/master/badge.svg)](https://semaphoreci.com/joeybloggs/errors)
 [![Go Report Card](https://goreportcard.com/badge/github.com/go-playground/errors)](https://goreportcard.com/report/github.com/go-playground/errors)
 [![GoDoc](https://godoc.org/github.com/go-playground/errors?status.svg)](https://godoc.org/github.com/go-playground/errors)
@@ -13,12 +13,18 @@ stack traces, tags(additional information) and even a Type classification system
 Common Questions
 
 Why another package?
-Because IMO most of the existing packages either don't take the error handling far enough, too far or down right unfriendly to use/consume. 
+There are two main reasons.
+- I think that the programs generating the original error(s) should be responsible for handling them, even though this package allows access to the original error, and that the callers are mainly interested in:
+  - If the error is Transient or Permanent for retries.
+  - Additional details for logging.
+
+- IMO 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`
 - [x] helpers to extract and classify error types using `RegisterHelper(...)`, many already existing such as ioerrors, neterrors, awserrors...
+- [x] built in helpers only need to be imported, eg. `_ github.com/go-playground/errors/helpers/neterrors` allowing libraries to register their own helpers not needing the caller to do or guess what needs to be imported.
 
 Installation
 ------------
@@ -44,15 +50,24 @@ func main() {
 	fmt.Println(err)
 	if errors.HasType(err, "Permanent") {
 		// os.Exit(1)
+		fmt.Println("it is a permanent error")
 	}
 
 	// root error
 	cause := errors.Cause(err)
-	fmt.Println(cause)
+	fmt.Println("CAUSE:", cause)
 
 	// can even still inspect the internal error
 	fmt.Println(errors.Cause(err) == io.EOF) // will extract the cause for you
 	fmt.Println(errors.Cause(cause) == io.EOF)
+
+	// and still in a switch
+	switch errors.Cause(err) {
+	case io.EOF:
+		fmt.Println("EOF error")
+	default:
+		fmt.Println("unknown error")
+	}
 }
 
 func level1(value string) error {
@@ -63,7 +78,7 @@ func level1(value string) error {
 }
 
 func level2(value string) error {
-	err := fmt.Errorf("this is an %s", "error")
+	err := io.EOF
 	return errors.Wrap(err, "failed to do something").AddTypes("Permanent").AddTags(errors.T("value", value))
 }
 ```
@@ -76,35 +91,23 @@ 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("Function: %s File: %s Line: %d\n", frame.Function(), frame.File(), frame.Line())
 
-	fmt.Printf("Name: %s File: %s Line: %s\n", name, file, line)
+	// and still have access to the underlying runtime.Frame
+	fmt.Printf("%+v\n", frame.Frame)
 }
 ```
 
 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.
+Using Go modules and proper semantic version releases (as always).
 
 License
 ------

_examples/basic/main.go

@@ -12,15 +12,24 @@ func main() {
 	fmt.Println(err)
 	if errors.HasType(err, "Permanent") {
 		// os.Exit(1)
+		fmt.Println("it is a permanent error")
 	}
 
 	// root error
 	cause := errors.Cause(err)
-	fmt.Println(cause)
+	fmt.Println("CAUSE:", cause)
 
 	// can even still inspect the internal error
 	fmt.Println(errors.Cause(err) == io.EOF) // will extract the cause for you
 	fmt.Println(errors.Cause(cause) == io.EOF)
+
+	// and still in a switch
+	switch errors.Cause(err) {
+	case io.EOF:
+		fmt.Println("EOF error")
+	default:
+		fmt.Println("unknown error")
+	}
 }
 
 func level1(value string) error {
@@ -31,6 +40,6 @@ func level1(value string) error {
 }
 
 func level2(value string) error {
-	err := fmt.Errorf("this is an %s", "error")
+	err := io.EOF
 	return errors.Wrap(err, "failed to do something").AddTypes("Permanent").AddTags(errors.T("value", value))
 }

_examples/helpers/main.go renamed to _examples/helpers/built-in/main.go

@@ -5,11 +5,11 @@ import (
 	"net"
 
 	"github.com/go-playground/errors"
-	"github.com/go-playground/errors/helpers/neterrors"
+	// init function handles registration automatically
+	_ "github.com/go-playground/errors/helpers/neterrors"
 )
 
 func main() {
-	errors.RegisterHelper(neterrors.NETErrors)
 	_, err := net.ResolveIPAddr("tcp", "foo")
 	if err != nil {
 		err = errors.Wrap(err, "failed to perform operation")

_examples/helpers/custom/main.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"fmt"
+	"net"
+
+	"github.com/go-playground/errors"
+)
+
+func main() {
+	errors.RegisterHelper(MyCustomErrHandler)
+	_, err := net.ResolveIPAddr("tcp", "foo")
+	if err != nil {
+		err = errors.Wrap(err, "failed to perform operation")
+	}
+
+	// all that extra context, types and tags captured for free
+	// there are more helpers and you can even create your own.
+	fmt.Println(err)
+}
+
+// MyCustomErrHandler helps classify my errors
+func MyCustomErrHandler(c errors.Chain, err error) (cont bool) {
+	switch err.(type) {
+	case net.UnknownNetworkError:
+		_ = c.AddTypes("io").AddTag("additional", "details")
+		return
+		//case net.Other:
+		//	...
+		//	return
+	}
+	return true
+}

_examples/stack/main.go

@@ -3,22 +3,15 @@ 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("Function: %s File: %s Line: %d\n", frame.Function(), frame.File(), frame.Line())
 
-	fmt.Printf("Name: %s File: %s Line: %s\n", name, file, line)
+	// and still have access to the underlying runtime.Frame
+	fmt.Printf("%+v\n", frame.Frame)
 }

benchmarks_test.go

@@ -0,0 +1,21 @@
+package errors
+
+import (
+	"testing"
+)
+
+func BenchmarkError(b *testing.B) {
+	err := New("base error")
+	for i := 0; i < b.N; i++ {
+		_ = err.Error()
+	}
+}
+
+func BenchmarkErrorParallel(b *testing.B) {
+	err := New("base error")
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			_ = err.Error()
+		}
+	})
+}

chain.go

@@ -2,6 +2,7 @@ package errors
 
 import (
 	"fmt"
+	"strconv"
 	"strings"
 )
 
@@ -10,7 +11,7 @@ func T(key string, value interface{}) Tag {
 	return Tag{Key: key, Value: value}
 }
 
-// Tag contains a single key value conbination
+// Tag contains a single key value combination
 // to be attached to your error
 type Tag struct {
 	Key   string
@@ -21,7 +22,7 @@ func newLink(err error, prefix string, skipFrames int) *Link {
 	return &Link{
 		Err:    err,
 		Prefix: prefix,
-		Source: st(skipFrames),
+		Source: StackLevel(skipFrames),
 	}
 
 }
@@ -31,13 +32,16 @@ type Chain []*Link
 
 // Error returns the formatted error string
 func (c Chain) Error() string {
-	lines := make([]string, 0, len(c))
+	b := make([]byte, 0, len(c)*128)
+
 	//source=<source> <prefix>: <error> tag=value tag2=value2 types=type1,type2
 	for i := len(c) - 1; i >= 0; i-- {
-		line := c[i].formatError()
-		lines = append(lines, line)
+		b = c[i].formatError(b)
+		if i > 0 {
+			b = append(b, '\n')
+		}
 	}
-	return strings.Join(lines, "\n")
+	return string(b)
 }
 
 // Link contains a single error entry, unless it's the top level error, in
@@ -57,32 +61,41 @@ type Link struct {
 	Tags []Tag
 
 	// Source contains the name, file and lines obtained from the stack trace
-	Source string
+	Source Frame
 }
 
 // formatError prints a single Links error
-func (l *Link) formatError() string {
-	line := fmt.Sprintf("source=%s ", l.Source)
+func (l *Link) formatError(b []byte) []byte {
+	b = append(b, "source="...)
+	b = append(b, l.Source.Function()...)
+	b = append(b, ": "...)
+	b = append(b, l.Source.File()...)
+	b = append(b, ':')
+	strconv.AppendInt(b, int64(l.Source.Line()), 10)
 
 	if l.Prefix != "" {
-		line += l.Prefix
+		b = append(b, l.Prefix...)
 	}
 
 	if _, ok := l.Err.(Chain); !ok {
 		if l.Prefix != "" {
-			line += ": "
+			b = append(b, ": "...)
 		}
-		line += l.Err.Error()
+		b = append(b, l.Err.Error()...)
 	}
 
 	for _, tag := range l.Tags {
-		line += fmt.Sprintf(" %s=%v", tag.Key, tag.Value)
+		b = append(b, ' ')
+		b = append(b, tag.Key...)
+		b = append(b, '=')
+		b = append(b, fmt.Sprintf("%v", tag.Value)...)
 	}
 
 	if len(l.Types) > 0 {
-		line += " types=" + strings.Join(l.Types, ",")
+		b = append(b, " types="...)
+		b = append(b, strings.Join(l.Types, ",")...)
 	}
-	return line
+	return b
 }
 
 // helper method to get the current *Link from the top level
@@ -114,5 +127,5 @@ func (c Chain) AddTypes(typ ...string) Chain {
 
 // Wrap adds another contextual prefix to the error chain
 func (c Chain) Wrap(prefix string) Chain {
-	return wrap(c, prefix, 0)
+	return wrap(c, prefix, 3)
 }