erorr

README

go-erorr

Package erorr provides tools for creating and manipulating errors, for the Go programming language.

Documention

Online documentation, which includes examples, can be found at: http://godoc.org/codeberg.org/reiver/go-erorr

History

This package's origin goes back to July 23rd, 2015 and before.

It started off as package manyerrors — which provided a way to combined multiple errors into a single error. Later package fck was created — which provided a way to create const errors (rather than having to use var). Eventually, package fck was renamed to package erorr — and later the concepts from package manyerrors were merged into it. Later, package erorr provides tool for creating error annotations and contextual errors. And, finally, package erorr switched to using Unwrap() error and Unwrap() []error methods to match the conventions in the built-in Golang "errors" package.

Example

Here are some examples.

Core Errors

Create your core errors with source-code similar to the following:

const (
	ErrNilReceiver = erorr.Error("nil receiver")
	ErrNotFound    = erorr.Error("not found")
	ErrUndefined   = erorr.Error("undefined")
)

Notice that a const was used (rather than a var).

Annotated Errors

Create an annotated error with source-code similar to the following:

if nil != err {
	return erorr.Wrap(err, "API request failed.",
		field.String("request-uri", requestURI),
		field.String("service", "monitor"),
	)
}

Contextual Errors

Create a contextual error with source-code similar to the following:

if nil != err {
	return erorr.Wrap("API request failed.",
		field.String("request-uri", requestURI),
		field.String("service", "monitor"),
	)
}

Note that erorr.Stamp() is similar to erorr.Wrap(), with the difference being that, erorr.Stamp() does not wrap another error.

Errorf

The function erorr.Errorf() is also available. For example:

if !isValidID(id) {
	return erorr.Errorf("bad value for id %q", id)
}

Or also, for example:

if nil != err {
	return erorr.Errorf("Uh oh, something bad happened to %s: %w", service, err)
}

Note that a different because this package's erorr.Errorf() function and the fmt.Errorf() in the built-in Go "fmt" package is that the error returned from this package's erorr.Errorf() function will include a call-trace and other annotation and contextual information.

Import

To import package erorr use import code like the follownig:

import "codeberg.org/reiver/go-erorr"

Installation

To install package erorr do the following:

GOPROXY=direct go get https://codeberg.org/reiver/go-erorr

Author

Package erorr was written by Charles Iliya Krempeaux

Documentation

Overview

Core Errors

To create your core errors, use Error. For example:

const (
	ErrNilReceiver = erorr.Error("nil receiver")
	ErrNotFound    = erorr.Error("not found")
	ErrUndefined   = erorr.Error("undefined")
)

Note that you can create errors with Error using `const` (rather than `var`).

Error Annotations

Use Wrap to annotate your core errors and other errors.

if nil != err {
	return erorr.Wrap(err, "API request failed.",
		field.String("request-uri", requestURI),
		field.String("service", "monitor"),
	)
}

Note that error annotations of this type automatically contains a call-trace.

You can also annotate multiple errors:

var errs []error

// ...

return erorr.Wrap(erorr.Errors(errs), "API request failed.",
	field.String("request-uri", requestURI),
	field.String("service", "monitor"),
)

Contextual Errors

Use Stamp to create a contextual error.

if nil != err {
	return erorr.Wrap("API request failed.",
		field.String("request-uri", requestURI),
		field.String("service", "monitor"),
	)
}

Note that Stamp is similar to Wrap, with the difference being that, Stamp does not wrap another error.

Index

• func Errorf(format string, a ...any) error
• func Is(err, target error) bool
• func Stamp(msg string, fields ...field.Field[string]) error
• func Wrap(err error, msg string, fields ...field.Field[string]) error
• type Error
  • func (receiver Error) Error() string
• type Errors
  • func (receiver Errors) Error() string
  • func (receiver Errors) Unwrap() []error
• type StampedError
  • func StampError(msg string, fields ...field.Field[string]) StampedError
  • func (receiver StampedError) CallTrace() string
  • func (receiver StampedError) Error() string
  • func (receiver StampedError) Fields() []field.Field[string]
• type WrappedError
  • func WrapError(err error, msg string, fields ...field.Field[string]) WrappedError
  • func (receiver WrappedError) CallTrace() string
  • func (receiver WrappedError) Error() string
  • func (receiver WrappedError) Fields() []field.Field[string]
  • func (receiver WrappedError) Unwrap() error
• type WrappedErrors
  • func WrapErrors(errs []error, msg string, fields ...field.Field[string]) WrappedErrors
  • func (receiver WrappedErrors) CallTrace() string
  • func (receiver WrappedErrors) Error() string
  • func (receiver WrappedErrors) Fields() []field.Field[string]
  • func (receiver WrappedErrors) Unwrap() []error

Examples

• Errorf (OneError)
• Errorf (TwoErrors)

Functions

func Errorf

func Errorf(format string, a ...any) error

Errorf returns a formatted error.

If an one or more errors are passed in the parameters of Errorf, then they are wrapped. If there is one error, then a WrappedError is returned. If there is more-than one error, then a WrappedErrors is returned. If there are no errors, then a StampedError is returned.

Example (OneError)

const ErrFailure = erorr.Error("failure!")

// ...

var err error = ErrFailure

service := "AuthService"
err = erorr.Errorf("Uh oh, something bad happened to %s: %w", service, err) // <---------

fmt.Printf("error-message: %s\n", err)
fmt.Printf("errors-type: %T\n", err)

Output:

error-message: Uh oh, something bad happened to AuthService: failure!
errors-type: erorr.WrappedError

Example (TwoErrors)

const ErrFailure = erorr.Error("failure!")
const ErrProblem = erorr.Error("problem!")

// ...

service := "AuthService"
err := erorr.Errorf("Uh oh, some bad things happened to %s: %w and %w", service, ErrFailure, ErrProblem) // <---------

fmt.Printf("error-message: %s\n", err)
fmt.Printf("errors-type: %T\n", err)

Output:

error-message: Uh oh, some bad things happened to AuthService: failure! and problem!
errors-type: erorr.WrappedErrors

func Is

func Is(err, target error) bool

Is returns true if the error matches the target, and returns false otherwise.

An error matches the target if the error equals the target, or if any wrapped errors (inside of the error) equals the target.

Example usage:

if erorr.Is(err, io.EOF) {
	// ...
}

func Stamp

func Stamp(msg string, fields ...field.Field[string]) error

Stamp returns a StampedError.

If you are not sure whetherto use StampError or Stamp use Stamp.

func Wrap

func Wrap(err error, msg string, fields ...field.Field[string]) error

Wrap returns a wrapped annotated error, which includes a call-trace and fields.

If `err` is nil then Wrap returns nil.

Example usage:

err := something()
if nil != err {
	return erorr.Wrap(err, "failed to do something",
		field.String("service", "banana"),
	)
}

Types

type Error

type Error string

Error is a simple error type.

Error is implemented in a way such that you can create `const` errors.

For example:

const ErrNilReceiver = erorr.Error("nil receiver")

Use Error for your core errors.

func (Error) Error

func (receiver Error) Error() string

type Errors

type Errors []error

func (Errors) Error

func (receiver Errors) Error() string

func (Errors) Unwrap

func (receiver Errors) Unwrap() []error

Before Go added support for:

Unwrap() []error

This method was called:

Errors() []error

But was renamed.

type StampedError

type StampedError struct {
	// contains filtered or unexported fields
}

StampedError is contextual error.

When a StampedError is created includes a call-trace, and a list of fields.

For example:

err := erorr.Stamp("client is nil",
	field.String("url", url),
)

func StampError

func StampError(msg string, fields ...field.Field[string]) StampedError

StampError returns a StampedError.

If you are not sure whetherto use StampError or Stamp use Stamp.

func (StampedError) CallTrace

func (receiver StampedError) CallTrace() string

func (StampedError) Error

func (receiver StampedError) Error() string

func (StampedError) Fields

func (receiver StampedError) Fields() []field.Field[string]

type WrappedError

type WrappedError struct {
	// contains filtered or unexported fields
}

func WrapError

func WrapError(err error, msg string, fields ...field.Field[string]) WrappedError

func (WrappedError) CallTrace

func (receiver WrappedError) CallTrace() string

func (WrappedError) Error

func (receiver WrappedError) Error() string

func (WrappedError) Fields

func (receiver WrappedError) Fields() []field.Field[string]

func (WrappedError) Unwrap

func (receiver WrappedError) Unwrap() error

type WrappedErrors

type WrappedErrors struct {
	// contains filtered or unexported fields
}

func WrapErrors

func WrapErrors(errs []error, msg string, fields ...field.Field[string]) WrappedErrors

func (WrappedErrors) CallTrace

func (receiver WrappedErrors) CallTrace() string

func (WrappedErrors) Error

func (receiver WrappedErrors) Error() string

func (WrappedErrors) Fields

func (receiver WrappedErrors) Fields() []field.Field[string]

func (WrappedErrors) Unwrap

func (receiver WrappedErrors) Unwrap() []error