v2.1.0 (#18)

Author: mkenney

CHANGELOG.md

@@ -3,13 +3,31 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - **Major**: backwards incompatible package updates
-- **Minor**: feature additions
+- **Minor**: feature additions, removal of deprecated features
 - **Patch**: bug fixes, backward compatible model and function changes, etc.
 
-# v2.0.0 - 2020-05-01
+# v2.1.0 - 2020-05-30
+#### Added
+* Additional documentation
+* Pre-generics implementation of `As`, returns the error instance when found
+
+#### Changed
+* Upgrade to `bdlm/std` v2.1.0
+* Cleaner type checking in `Is` methods
+
+#### Removed
+* deprecated `Has` methods, use `Is` instead
+
+# v2.0.1 - 2020-05-01
+#### Added
+* n/a
+
 #### Changed
 * Refactoring to better implement the `std/errors.Error` interface
 
+#### Removed
+* n/a
+
 # v2.0.0 - 2020-05-01
 `v2.0.0` is the production release of the `v0.2.0` development branch.
 
@@ -33,6 +51,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 #### Changed
 * Minor formatting updates and cleanup
 
+#### Removed
+* n/a
+
 
 # v0.2.0 - 2019-07-18
 This release is a full rewrite of the `errors` package. See the [README](README.md) for further details.
@@ -62,20 +83,41 @@ This release is a full rewrite of the `errors` package. See the [README](README.
 
 
 # v0.1.3 - 2018-10-02
+#### Added
+* n/a
+
 #### Changed
 * Fixes a message formatting error
 
+#### Removed
+* n/a
 
 # v0.1.2 - 2018-09-09
+#### Added
+* n/a
+
 #### Changed
 * Fixes issues with concurrent writes
 
+#### Removed
+* n/a
 
 # v0.1.1 - 2018-08-22
 #### Added
 * Implemented a `Trace` method
 
+#### Changed
+* n/a
+
+#### Removed
+* n/a
 
 # v0.1.0 - 2018-06-23
 #### Added
 * Initial release
+
+#### Changed
+* n/a
+
+#### Removed
+* n/a

README.md

@@ -3,7 +3,7 @@
 <a href="https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#mature"><img src="https://img.shields.io/badge/stability-mature-008000.svg" alt="Mature"></a> This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). This package is considered mature, you should expect package stability in <strong>Minor</strong> and <strong>Patch</strong> version releases
 
 - **Major**: backwards incompatible package updates
-- **Minor**: feature additions
+- **Minor**: feature additions, removal of deprecated features
 - **Patch**: bug fixes, backward compatible model and function changes, etc.
 
 **[CHANGELOG](CHANGELOG.md)**<br>
@@ -36,7 +36,7 @@ go get github.com/bdlm/errors/v2
 
 ## Quick start
 
-See the [documentation](https://pkg.go.dev/github.com/bdlm/errors#pkg-examples) for more examples. All exported methods work with any `error` type as well as `nil` values.
+See the [documentation](https://pkg.go.dev/github.com/bdlm/errors#pkg-examples) for more examples. All package methods work with any `error` type as well as `nil` values, and error instances implement the [`Unwrap`](https://go.googlesource.com/proposal/+/master/design/go2draft-error-inspection.md), [`Is`](https://go.googlesource.com/proposal/+/master/design/go2draft-error-inspection.md), [`Marshaler`](https://golang.org/pkg/encoding/json/#Marshaler), [`Unmarshaler`](https://golang.org/pkg/encoding/json/#Unmarshaler), and [`Formatter`](https://golang.org/pkg/fmt/#Formatter) interfaces as well as the [`github.com/bdlm/std/errors`](https://github.com/bdlm/std/tree/master/errors) interfaces.
 
 #### Create an error
 ```go
@@ -75,23 +75,12 @@ if prevErr := errors.Unwrap(err); nil != prevErr {
 }
 ```
 
-#### Test for a specific error type
-```go
-var MyError = errors.New("My error")
-func main() {
-	err := doWork()
-	if errors.Is(err, MyError) {
-		...
-	}
-}
-```
-
 #### Test to see if a specific error type exists anywhere in an error stack
 ```go
 var MyError = errors.New("My error")
 func main() {
 	err := doWork()
-	if errors.Has(err, MyError) {
+	if errors.Is(err, MyError) {
 		...
 	}
 }
@@ -106,54 +95,69 @@ for nil != err {
 }
 ```
 
-#
-
-See the [documentation](https://godoc.org/github.com/bdlm/errors#pkg-examples) for more examples.
-
-
-## The `Error` interface
+#### Formatting verbs
+`errors` implements the `%s` and `%v` [`fmt.Formatter`](https://golang.org/pkg/fmt/#hdr-Printing) formatting verbs and several modifier flags:
 
-The exported package methods return `github.com/bdlm/std/v2/errors` interfaces that expose metadata and troubleshooting information:
+##### Verbs
+* `%s` - Returns the error string of the last error added.
+* `%v` - Alias for `%s`
 
-```go
-// Error defines a robust error stack interface.
-type Error interface {
-	// Caller returns the associated Caller instance.
-	Caller() Caller
-
-	// Error implements error.
-	Error() string
-
-	// Has tests to see if the test error exists anywhere in the error
-	// stack.
-	Has(test error) bool
+##### Flags
+* `#` - JSON formatted output, useful for logging
+* `-` - Output caller details, useful for troubleshooting
+* `+` - Output full error stack details, useful for debugging
+* ` ` - (space) Add whitespace formatting for readability, useful for development
 
-	// Is tests to see if the test error matches most recent error in the
-	// stack.
-	Is(test error) bool
-
-	// Unwrap returns the next error, if any.
-	Unwrap() Error
+##### Examples
+`fmt.Printf("%s", err)`
+```
+An error occurred
+```
+`fmt.Printf("%v", err)`
+```
+An error occurred
+```
+`fmt.Printf("%-v", err)`
+```
+#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors) - An error occurred
+```
+`fmt.Printf("%+v", err)`
+```
+#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors) - An error occurred #1 stack_test.go:39 (github.com/bdlm/error_test.TestErrors) - An error occurred
+```
+`fmt.Printf("%#v", err)`
+```json
+{"error":"An error occurred"}
+```
+`fmt.Printf("%#-v", err)`
+```json
+{"caller":"#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)","error":"An error occurred"}
+```
+`fmt.Printf("%#+v", err)`
+```json
+[{"caller":"#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)","error":"An error occurred"},{"caller":"#1 stack_test.go:39 (github.com/bdlm/error_test.TestErrors)","error":"An error occurred"}]
+```
+`fmt.Printf("% #-v", err)`
+```json
+{
+    "caller": "#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)",
+    "error": "An error occurred"
 }
+```
+`fmt.Printf("% #+v", err)`
+```json
+[
+    {
+        "caller": "#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)",
+        "error": "An error occurred"
+    },
+    {
+        "caller": "#1 stack_test.go:39 (github.com/bdlm/error_test.TestErrors)",
+        "error": "An error occurred"
+    }
+]
+```
 
-// Caller defines an interface to runtime caller results.
-type Caller interface {
-	// File returns the file in which the call occurred.
-	File() string
-
-	// Func returns the name of the function in which the call occurred.
-	Func() string
-
-	// Line returns the line number in the file in which the call occurred.
-	Line() int
-
-	// Pc returns the program counter.
-	Pc() uintptr
-
-	// Trace returns the call stack.
-	Trace() Trace
-}
+#
 
-// Trace defines an error trace.
-type Trace []Caller
-```
+See the [documentation](https://godoc.org/github.com/bdlm/errors#pkg-examples) for more examples.

caller.go

@@ -5,7 +5,7 @@ import (
 	"runtime"
 	"strings"
 
-	std_err "github.com/bdlm/std/v2/errors"
+	std_caller "github.com/bdlm/std/v2/caller"
 )
 
 // caller is a github.com/bdlm/std.Caller interface implementation and holds
@@ -15,12 +15,12 @@ type caller struct {
 	line  int
 	ok    bool
 	pc    uintptr
-	trace std_err.Trace
+	trace std_caller.Trace
 }
 
 // NewCaller returns a new Caller containing data for the current call stack.
-func NewCaller() std_err.Caller {
-	trace := std_err.Trace{}
+func NewCaller() std_caller.Caller {
+	trace := std_caller.Trace{}
 	clr := &caller{}
 	a := 0
 	for {
@@ -75,6 +75,6 @@ func (caller *caller) String() string {
 }
 
 // Trace implements Caller.
-func (caller *caller) Trace() std_err.Trace {
+func (caller *caller) Trace() std_caller.Trace {
 	return caller.trace
 }

error.go

@@ -1,66 +1,77 @@
 package errors
 
 import (
-	std_err "github.com/bdlm/std/v2/errors"
+	"reflect"
+
+	std_caller "github.com/bdlm/std/v2/caller"
+	std_error "github.com/bdlm/std/v2/errors"
 )
 
 // E is a github.com/bdlm/std.Error interface implementation and simply wraps
 // the exported package methods as a convenience.
 type E struct {
-	caller std_err.Caller
+	caller std_caller.Caller
 	err    error
 	prev   error
 }
 
-// Caller implements std.Error.
-func (e *E) Caller() std_err.Caller {
+// Caller implements std_error.Caller.
+func (e *E) Caller() std_caller.Caller {
 	if nil == e {
 		return nil
 	}
 	return e.caller
 }
 
-// Error implements std.Error.
+// Error implements std_error.Error.
 func (e *E) Error() string {
 	return e.err.Error()
 }
 
-// Has implements std.Error.
-func (e *E) Has(test error) bool {
-	if e.Is(test) {
-		return true
-	}
-	if prev := e.Unwrap(); nil != prev {
-		return prev.Has(test)
-	}
-	return false
-}
-
-// Is implements std.Error.
+// Is implements std_error.Error.
 func (e *E) Is(test error) bool {
 	if nil == test {
 		return false
 	}
-	if e.err == test && e.Error() == test.Error() {
+
+	isComparable := reflect.TypeOf(e).Comparable() && reflect.TypeOf(test).Comparable()
+	if isComparable && e == test {
 		return true
 	}
-	if std, ok := test.(std_err.Error); ok {
-		return func(e1, e2 std_err.Error) bool {
-			return e1 == e2 && e1.Error() == e2.Error()
-		}(e, std)
+	isComparable = reflect.TypeOf(e.err).Comparable() && reflect.TypeOf(test).Comparable()
+	if isComparable && e.err == test {
+		return true
 	}
+
+	if testE, ok := test.(*E); ok {
+		isComparable = reflect.TypeOf(e).Comparable() && reflect.TypeOf(testE).Comparable()
+		if isComparable && e == testE {
+			return true
+		}
+		isComparable = reflect.TypeOf(e.err).Comparable() && reflect.TypeOf(testE.err).Comparable()
+		if isComparable && e.err == testE.err {
+			return true
+		}
+	}
+
+	if err := e.Unwrap(); nil != err {
+		if err, ok := err.(interface{ Is(error) bool }); ok {
+			return err.Is(test)
+		}
+	}
+
 	return false
 }
 
-// Unwrap implements std.Error.
-func (e *E) Unwrap() std_err.Error {
+// Unwrap implements std_error.Wrapper.
+func (e *E) Unwrap() error {
 	if nil == e {
 		return nil
 	}
 	if nil == e.prev {
 		return nil
 	}
-	if prev, ok := e.prev.(std_err.Error); ok {
+	if prev, ok := e.prev.(std_error.Error); ok {
 		return prev
 	}
 	return &E{
@@ -73,7 +84,7 @@ func list(e error) []error {
 	ret := []error{}
 
 	if nil != e {
-		if std, ok := e.(std_err.Error); ok {
+		if std, ok := e.(std_error.Wrapper); ok {
 			ret = append(ret, e)
 			ret = append(ret, list(std.Unwrap())...)
 		}