v2.0.0 release

doc.go

@@ -1,8 +1,6 @@
-/*
-Package std provides useful go interfaces for building consistent, testable,
-mockable packages.
-
-Interfaces available in the standard library should be preferred over anything
-you find here.
-*/
+// Package std provides useful go interfaces for building consistent, testable,
+// mockable packages.
+//
+// Interfaces available in the standard library should be preferred over anything
+// you find here.
 package std

errors/caller.go

@@ -0,0 +1,19 @@
+package error
+
+// 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
+}

errors/error.go

@@ -0,0 +1,21 @@
+package error
+
+// 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
+
+	// 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
+}

error/types.go → errors/types.go

@@ -1,7 +1,4 @@
 package error
 
-// Code defines an error code type.
-type Code int
-
 // Trace defines an error trace.
 type Trace []Caller

go.mod

@@ -1,3 +1,3 @@
-module github.com/bdlm/std
+module github.com/bdlm/std/v2
 
 go 1.14

importer/importer.go

@@ -1,14 +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 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.
 type Importer interface {
 	// Import imports the given data into the reciever's data structure.
 	Import(data interface{}) error

iterator/iterator.go

@@ -1,8 +1,6 @@
 package iterator
 
-/*
-Iterator defines a simple interator interface.
-*/
+// Iterator defines a simple interator interface.
 type Iterator interface {
 	// Cur reads the key and value at the current cursor postion into pK and
 	// pV respectively. Cur will return false if no iteration has begun,

logger/logger.go

@@ -1,33 +1,31 @@
 package logger
 
-/*
-Logger defines a common logger interface for packages that accept an
-injected logger. It fully implements the standard 'pkg/log' log package
-logging methods as well Info, Warn, Error, and Debug level equivalents.
-The Info* methods are expected to mirror the Print* methods.
-
-Packages that implement this interface should support level codes and
-expect usage as follows:
-
-	- Panic, highest level of severity. Log and then call panic.
-	- Fatal, log and then call `os.Exit(<code>)` with a non-zero value.
-	- Error, used for errors that should definitely be noted and addressed.
-	- Warn, non-critical information about undesirable behavior that needs
-	  to be addressed in some way.
-	- Info, general operational information about what's happening inside an
-	  application. 'Print' methods should output Info-level information.
-	- Debug, usually only enabled when debugging. Add anything useful, but
-	  still exclude PII or sensitive data...
-
-Each level should include all the log levels above it. To manage the output,
-this interface also implements a SetLevel(level uint) method that defines
-the log level of this logger.
-
-Compatible logger packages include:
-
-	- "github.com/bdlm/log"
-	- "github.com/sirupsen/logrus"
-*/
+// Logger defines a common logger interface for packages that accept an
+// injected logger. It fully implements the standard 'pkg/log' log package
+// logging methods as well Info, Warn, Error, and Debug level equivalents.
+// The Info* methods are expected to mirror the Print* methods.
+//
+// Packages that implement this interface should support level codes and
+// expect usage as follows:
+//
+// 	- Panic, highest level of severity. Log and then call panic.
+// 	- Fatal, log and then call `os.Exit(<code>)` with a non-zero value.
+// 	- Error, used for errors that should definitely be noted and addressed.
+// 	- Warn, non-critical information about undesirable behavior that needs
+// 	  to be addressed in some way.
+// 	- Info, general operational information about what's happening inside an
+// 	  application. 'Print' methods should output Info-level information.
+// 	- Debug, usually only enabled when debugging. Add anything useful, but
+// 	  still exclude PII or sensitive data...
+//
+// Each level should include all the log levels above it. To manage the output,
+// this interface also implements a SetLevel(level uint) method that defines
+// the log level of this logger.
+//
+// Compatible logger packages include:
+//
+// 	- "github.com/bdlm/log"
+// 	- "github.com/sirupsen/logrus"
 type Logger interface {
 	// WithFields adds a map of key/value data to the log entry.
 	WithFields(Fields)

model/model.go

@@ -1,8 +1,6 @@
 package model
 
-/*
-ModelType defines a type for use by models.
-*/
+// ModelType defines a type for use by models.
 type ModelType int
 
 const (
@@ -14,14 +12,12 @@ const (
 	ModelTypeHash
 )
 
-/*
-Model is a list or a map of Values.
-
-This interface defines data storage and access methods for data models in
-order to provide a consistent interface for communicating messages between
-instances. This allows several abstractions on and recursions into
-multidimensional untyped data structures.
-*/
+// Model is a list or a map of Values.
+//
+// This interface defines data storage and access methods for data models in
+// order to provide a consistent interface for communicating messages between
+// instances. This allows several abstractions on and recursions into
+// multidimensional untyped data structures.
 type Model interface {
 	// Delete removes a value from this model.
 	Delete(key interface{}) error

model/value.go

@@ -1,9 +1,7 @@
 package model
 
-/*
-Value represents a single data value. Used as an interface to values stored
-in Model nodes.
-*/
+// Value represents a single data value. Used as an interface to values stored
+// in Model nodes.
 type Value interface {
 	// Bool returns the boolean representation of the value of this node, or
 	// an error if the type conversion is not possible.

parser/parser.go

@@ -4,15 +4,13 @@ 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 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.
 type Parser interface {
 	Parse(r io.Reader) (interface{}, error)
 }