Update docs + examples

README.md

@@ -22,11 +22,17 @@ errors
 [doc-url]: https://pkg.go.dev/github.com/go-pogo/errors
 
 
-Package `errors` contains additional functions, interfaces and structs for recording stack frames,
-applying basic formatting, working with goroutines, multiple errors and custom error types.
+Package `errors` contains additional functions, interfaces and structs for
+recording stack frames, applying basic formatting, working with goroutines,
+multiple errors and custom error types.
 
-It is inspired by the `golang.org/x/xerrors` package and is designed to be a drop in replacement for
-it, as well as the standard library's `errors` package.
+It is inspired by package `golang.org/x/xerrors` and is designed to be a drop-in
+replacement for it, as well as the standard library's `errors` package.
+
+The `errors.New` and `errors.Errorf` functions create errors whose content is a
+text message and whom can trace stack frames. `errors.Wrap` and `errors.Wrapf`
+create errors by wrapping an existing error with a similar error like
+`errors.New` and `errors.Errorf`.
 
 ```sh
 go get github.com/go-pogo/errors
@@ -36,37 +42,61 @@ go get github.com/go-pogo/errors
 import "github.com/go-pogo/errors"
 ```
 
-## Stack trace
-Every error can track stack trace information. Just wrap it with `errors.WithStack`
-and a complete stack trace is captured.
+## `Msg` and `Kind`
+Instead of defining error messages as global variables, it is possible to define
+them as constants using `errors.Msg`.
 
-```go
-err = errors.WithStack(err)
-```
+	const ErrSomethingWentWrong errors.Msg = "something went wrong"
 
-```text
-some error: something happened:
-    main.doSomething
-       .../errors/examples/2_trace/main.go:17
-    main.someAction
-       .../errors/examples/2_trace/main.go:12
-```
+This same can be done with `errors.Kind`:
+
+	const InvalidOpError errors.Kind = "invalid operation error"
+	err = errors.WithKind(err, InvalidOpError)
+
+	errors.Is(err, InvalidOpError) // true
 
 ## Formatting
-Wrap an existing error with `errors.WithFormatter` to upgrade the error to include basic formatting.
-Formatting is done using `xerrors.FormatError` and thus the same verbs are supported.
+Wrap an existing error with `errors.WithFormatter` to upgrade the error to
+include basic formatting.
+Formatting is done using `xerrors.FormatError` and thus the same verbs are
+supported. Any error created with this package implements the `fmt.Formatter`
+and `xerrors.Formatter` interfaces.
 
-```go
-fmt.Printf("%+v", errors.WithFormatter(err))
+	fmt.Printf("%+v", errors.WithFormatter(err))
+
+## Stack tracing
+Every error can track stack trace information. Just wrap it with
+`errors.WithStack` and a complete stack trace is captured.
+
+	err = errors.WithStack(err)
+
+An `errors.StackTrace` can be retrieved using `errors.GetStackTrace`.
+Printing the error results in a trace similar to:
+
+	invalid character 'i' looking for beginning of value:
+		github.com/go-pogo/errors.ExampleWithStack
+			/path/to/errors/examples_trace_test.go:43
+		github.com/go-pogo/errors.ExampleWithStack.func1
+			/path/to/errors/examples_trace_test.go:40
+
+## Disable stack tracing
+Stack tracing comes with a performance cost. For production environments this
+cost can be undesirable. To disable stack tracing, compile your Go program with
+the "notrace" tag.
+
+```sh
+go build -tags=notrace
 ```
 
-## Catch panics
+## Catching panics
 A convenient function is available to catch panics and store them as an error.
 
-```go
-var err error
-defer errors.CatchPanic(&err)
-```
+	var err error
+	defer errors.CatchPanic(&err)
+
+## Backwards compatibility
+Unwrap, Is, As are backwards compatible with the standard library's `errors`
+package and act the same.
 
 ## Documentation
 Additional detailed documentation is available at [pkg.go.dev][doc-url]

doc.go

@@ -10,35 +10,59 @@ multiple errors and custom error types.
 It is inspired by package golang.org/x/xerrors and is designed to be a drop-in
 replacement for it, as well as the standard library's errors package.
 
-The New and Newf functions create errors whose content is a text message and
-whom can trace stack frames. Wrap and Wrapf create errors by wrapping an
-existing error with a similar error like New and Newf.
+The errors.New and errors.Errorf functions create errors whose content is a
+text message and whom can trace stack frames. errors.Wrap and errors.Wrapf
+create errors by wrapping an existing error with a similar error like
+errors.New and errors.Errorf.
 
-# StackTrace tracing
+# Msg and Kind
 
-Every error can track stack trace information. Just wrap it with errors.WithStack
-and a complete stack trace is captured.
+Instead of defining error messages as global variables, it is possible to define
+them as constants using errors.Msg.
 
-	err = errors.WithStack(err)
+	const ErrSomethingWentWrong errors.Msg = "something went wrong"
 
-Printing the error results in a trace similar to:
+This same can be done with errors.Kind:
 
-	some error: something happened:
-	    main.main
-	        /go-pogo/errors/.examples/3_with_kind/main.go:24
-	    main.doSomething
-	        /go-pogo/errors/.examples/3_with_kind/main.go:20
-	    main.someAction
-	        /go-pogo/errors/.examples/3_with_kind/main.go:16
+	const InvalidOpError errors.Kind = "invalid operation error"
+	err = errors.WithKind(err, InvalidOpError)
+
+	errors.Is(err, InvalidOpError) // true
 
 # Formatting
 
 Wrap an existing error with errors.WithFormatter to upgrade the error to
-include basic formatting. Formatting is done using xerrors.FormatError and
-thus the same verbs are supported.
+include basic formatting.
+Formatting is done using xerrors.FormatError and thus the same verbs are
+supported. Any error created with this package implements the fmt.Formatter
+and xerrors.Formatter interfaces.
 
 	fmt.Printf("%+v", errors.WithFormatter(err))
 
+# Stack tracing
+
+Every error can track stack trace information. Just wrap it with
+errors.WithStack and a complete stack trace is captured.
+
+	err = errors.WithStack(err)
+
+An errors.StackTrace can be retrieved using errors.GetStackTrace.
+Printing the error results in a trace similar to:
+
+	invalid character 'i' looking for beginning of value:
+		github.com/go-pogo/errors.ExampleWithStack
+			/path/to/errors/examples_trace_test.go:43
+		github.com/go-pogo/errors.ExampleWithStack.func1
+			/path/to/errors/examples_trace_test.go:40
+
+# Disable stack tracing
+
+Stack tracing comes with a performance cost. For production environments this
+cost can be undesirable. To disable stack tracing, compile your Go program with
+the "notrace" tag.
+
+	go build -tags=notrace
+
 # Catching panics
 
 A convenient function is available to catch panics and store them as an error.

examples_test.go

@@ -34,7 +34,7 @@ func ExampleMsg() {
 func ExampleWithKind() {
 	const (
 		ErrSomethingWentWrong Msg  = "something went wrong"
-		SomeKindOfError       Kind = "some action error"
+		SomeKindOfError       Kind = "some kind of error"
 	)
 
 	doSomethingElse := func() error {
@@ -47,7 +47,7 @@ func ExampleWithKind() {
 
 	err := doSomething()
 	fmt.Println(err)
-	// Output: some action error: something went wrong
+	// Output: some kind of error: something went wrong
 }
 
 func ExampleAppend() {

format.go

@@ -51,16 +51,16 @@ func FormatError(err error, state fmt.State, verb rune) {
 
 // PrintError prints the error err with the provided Printer and formats and
 // prints the error's stack frames.
-func PrintError(printer Printer, err error) {
+func PrintError(p Printer, err error) {
 	if err == nil {
 		return
 	}
 
-	printer.Print(err.Error())
-	if !printer.Detail() {
+	p.Print(err.Error())
+	if !p.Detail() {
 		return
 	}
 	if stack := GetStackTrace(err); stack != nil {
-		stack.Format(printer)
+		stack.Format(p)
 	}
 }