Reimplementation and new API (#1)

* Updates.

* Reimplement and simplify.

* Checkpoint.

* Numerous changes.

* Use Modver 2.6.1 in CI.

* Unexport the wrapped-error type. Export a Stacker interface instead.

* Add Walk.

* More test coverage.

* Fix doc.

* Add ErrSkip.

* Make Stacker easier for other types to implement.

* Mention tree traversal in package doc.

.github/workflows/go.yml

@@ -0,0 +1,36 @@
+name: Tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.21
+
+      - name: Unit tests
+        run: go test -coverprofile=cover.out ./...
+
+      - name: Send coverage
+        uses: shogo82148/actions-goveralls@v1
+        with:
+          path-to-profile: cover.out
+
+      - name: Modver
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: bobg/modver@v2.6.1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          pull_request_url: https://github.com/${{ github.repository }}/pull/${{ github.event.number }}

LICENSE

@@ -1,23 +1,21 @@
-Copyright (c) 2015, Dave Cheney <dave@cheney.net>
-All rights reserved.
+MIT License
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+Copyright (c) 2024 Bob Glickstein
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Readme.md

@@ -0,0 +1,64 @@
+# Errors - drop-in replacement for the stdlib errors package that adds wrapping and call stacks
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/bobg/errors.svg)](https://pkg.go.dev/github.com/bobg/errors)
+[![Go Report Card](https://goreportcard.com/badge/github.com/bobg/errors)](https://goreportcard.com/report/github.com/bobg/errors)
+[![Tests](https://github.com/bobg/errors/actions/workflows/go.yml/badge.svg)](https://github.com/bobg/errors/actions/workflows/go.yml)
+[![Coverage Status](https://coveralls.io/repos/github/bobg/errors/badge.svg?branch=master)](https://coveralls.io/github/bobg/errors?branch=master)
+
+This is errors,
+a drop-in replacement for [the standard Go errors package](https://pkg.go.dev/errors).
+It adds an API for wrapping an error with a caller-specified message and a snapshot of the call stack.
+It also adds a function for traversing an error’s tree of wrapped sub-errors.
+
+This module began as a fork of the venerable [github.com/pkg/errors](https://github.com/pkg/errors).
+That module’s GitHub repository has been frozen for a long time and has not kept up with changes to the standard library.
+(For example, it does not export [the Join function](https://pkg.go.dev/errors#Join) added in Go 1.20.)
+
+This is now a brand-new implementation with a different API.
+
+## Usage
+
+When you write code that handles an error from a function call by returning the error to your caller,
+it’s a good practice to “wrap” the error with context from your callsite first.
+The Go standard library lets you do this like so:
+
+```go
+if err := doThing(...); err != nil {
+  return fmt.Errorf("doing thing: %w", err)
+}
+```
+
+The resulting error still “is” `err`
+(in the sense of [errors.Is](https://pkg.go.dev/errors#Is))
+but is now wrapped with context about how `err` was produced −
+to wit, “doing thing.”
+
+This library lets you do the same thing like this:
+
+```go
+if err := doThing(...); err != nil {
+  return errors.Wrap(err, "doing thing")
+}
+```
+
+This approach has a couple of benefits over wrapping with `fmt.Errorf` and `%w`.
+First, as a convenience, `Wrap` returns `nil` if its error argument is `nil`.
+So if `doThing` is the last thing that happens in your function,
+you can safely write:
+
+```go
+err := doThing(...)
+return errors.Wrap(err, "doing thing")
+```
+
+This will correctly return `nil` when `doThing` succeeds.
+
+Second, errors produced by this package contain a snapshot of the call stack from the moment the error was created.
+This can be retrieved with the `Stack` function.
+
+Note that diligent error wrapping often makes the stack trace superfluous.
+As errors work their way up the stack
+it’s possible to decorate them with enough extra context
+to understand exactly where and why the error occurred.
+But you can’t always rely on diligent error wrapping,
+and you can’t always wait for an error to propagate all the way up the call stack before reporting it.