v2.1.0 (#9)

CHANGELOG.md

@@ -3,9 +3,21 @@ All notable changes to this project will be 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 protobuf model changes, etc.
 
+# v2.1.0 - 2020-05-30
+#### Added
+* `Caller` package
+
+#### Changed
+* n/a
+
+#### Removed
+* `github.com/bdlm/std/v2/errors.Caller`
+* `github.com/bdlm/std/v2/errors.Trace`
+* `github.com/bdlm/std/v2/errors.Error.Has`
+
 # v2.0.0 - 2020-05-01
 #### Added
 * `go.mod`

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>

caller/README.md

@@ -0,0 +1 @@
+The `caller` package defines an interface for managing call stack data. This is useful for logging, error handling, and other applications.

errors/caller.go → caller/caller.go

@@ -1,4 +1,4 @@
-package error
+package caller
 
 // Caller defines an interface to runtime caller results.
 type Caller interface {
@@ -17,3 +17,6 @@ type Caller interface {
 	// Trace returns the call stack.
 	Trace() Trace
 }
+
+// Trace defines a call stack trace.
+type Trace []Caller

errors/README.md

@@ -0,0 +1 @@
+The `errors` package defines interfaces for error types that manage wrapping errors with additional context or data. This allows for troubleshooting and error handling comparable to traditional exception management.

errors/error.go

@@ -1,21 +1,33 @@
 package error
 
-// Error defines a robust error stack interface.
-type Error interface {
+import (
+	"github.com/bdlm/std/v2/caller"
+)
+
+// Caller is the interface implemented by error types that can expose
+// runtime caller data.
+type Caller interface {
 	// Caller returns the associated Caller instance.
-	Caller() Caller
+	Caller() caller.Caller
+}
 
+// Error defines a robust error stack interface.
+type Error interface {
 	// Error implements error.
 	Error() string
 
-	// Has tests to see if the test error exists anywhere in the error
-	// stack.
-	Has(error) bool
-
-	// Is tests to see if the test error matches most recent error in the
-	// stack.
+	// Is tests to see if the test error matches any error in the stack via
+	// equality comparison.
 	Is(error) bool
 
-	// Unwrap returns the next error, if any.
-	Unwrap() Error
+	// Unwrap returns the wrapped error, if any, otherwise nil.
+	Unwrap() error
+}
+
+// Wrapper is an interface implemented by error types that have wrapped
+// a previous error.
+type Wrapper interface {
+	// Unwrap returns the next error in the error stack, if any, otherwise
+	// nil.
+	Unwrap() error
 }

importer/importer.go

@@ -1,13 +1,12 @@
 package importer
 
-// Importer is the interface that wraps the basic Import method.
-//
-// Importer accepts the empty interface and extracts data from there, returning
-// an error if the import fails.
-//
-// Implementations must not retain data. Implementations should not retain any
-// imported data if returning an error.
+// Importer is the interface that wraps the standard Import method.
 type Importer interface {
-	// Import imports the given data into the reciever's data structure.
-	Import(data interface{}) error
+	// Import imports the given data into the reciever's data structure. It
+	// accepts the empty interface and extracts data from there, returning
+	// an error if the import fails.
+	//
+	// Implementations must not retain d. Implementations should not retain
+	// any imported data if returning an error.
+	Import(d interface{}) error
 }

parser/parser.go

@@ -4,13 +4,12 @@ import (
 	"io"
 )
 
-// Parser is the interface that wraps the basic Parse method.
-//
-// Parser accepts a reader r and parses the data it returns, returning an error
-// if parsing fails.
-//
-// Implementations must not retain r. Implementations should not retain any
-// parsed data if returning an error.
+// Parser is the interface that wraps the standard Parse method.
 type Parser interface {
+	// Parse accepts a reader and parses the data it returns, returning an
+	// error if parsing fails.
+	//
+	// Implementations must not retain r. Implementations should not retain
+	// any parsed data if returning an error.
 	Parse(r io.Reader) (interface{}, error)
 }