errors

README

errors

Documentation

Index

• func Annotate(err error, message string) error
• func Annotatef(err error, format string, args ...interface{}) error
• func As(err error, target interface{}) bool
• func Code(err error) int
• func Errorf(format string, args ...interface{}) error
• func HTTPf(err error, code int, format string, args ...interface{}) error
• func Is(err, target error) bool
• func New(message string) error
• func NewHTTP(err error, code int, message string) error
• func Unwrap(err error) error
• func Wrap(dst, next error) error
• type HTTP

Examples

• Annotate
• Annotatef
• As
• As (Interface)
• Code
• Errorf
• HTTPf
• Is
• New
• NewHTTP
• Unwrap
• Wrap

Functions

func Annotate

func Annotate(err error, message string) error

Annotate annotates the provided error with the specified message. Returns nil if the err argument is nil.

Example

package main

import (
	"fmt"
	"strconv"

	"github.com/adrg/errors"
)

func main() {
	_, err := strconv.Atoi("this will fail")

	// No need to check if the original error is nil.
	// If err is nil, Annotate returns nil.
	err = errors.Annotate(err, "conversion failed")

	fmt.Printf("%s\n", err)  // Print error message only.
	fmt.Printf("%v\n", err)  // Print error chain without stack details.
	fmt.Printf("%+v\n", err) // Print error chain with stack details.
}

func Annotatef

func Annotatef(err error, format string, args ...interface{}) error

Annotatef annotates the provided error according to the format specifier. Returns nil if the err argument is nil.

Example

package main

import (
	"fmt"
	"strings"

	"github.com/adrg/errors"
)

func main() {
	var err error

	email := "alice @example.com"
	if strings.Contains(email, " ") {
		err = errors.New("email address cannot contain spaces")
	}

	// No need to check if the original error is nil.
	// If err is nil, Annotatef returns nil.
	err = errors.Annotatef(err, "invalid email adddress %s", email)

	fmt.Printf("%s\n", err)  // Print error message only.
	fmt.Printf("%v\n", err)  // Print error chain without stack details.
	fmt.Printf("%+v\n", err) // Print error chain with stack details.
}

func As

func As(err error, target interface{}) bool

As checks whether err or any of the errors in its chain is a value of the same type as target. If so, it sets target with the found value and returns true. Otherwise, target is left unchanged and false is returned.

Example

package main

import (
	"fmt"
	"strconv"

	"github.com/adrg/errors"
)

func main() {
	_, err := strconv.Atoi("this will fail")

	// No need to check if the original error is nil.
	// If err is nil, Annotate returns nil.
	err = errors.Annotate(err, "conversion failed")

	nErr := &strconv.NumError{}
	if ok := errors.As(err, &nErr); ok {
		fmt.Printf("error %s: parsing `%s`: %s\n", nErr.Func, nErr.Num, nErr.Err)
	}
}

Example (Interface)

package main

import (
	"fmt"

	"github.com/adrg/errors"
)

func main() {
	err := errors.NewHTTP(nil, 500, "something bad happened")
	err = errors.Annotate(err, "annotated HTTP error interface")

	var nErr errors.HTTP
	if ok := errors.As(err, &nErr); ok {
		fmt.Printf("%s\n", err)        // Print error message only.
		fmt.Printf("%v\n", err)        // Print error chain without stack details.
		fmt.Printf("%+v\n", err)       // Print error chain with stack details.
		fmt.Println(errors.Code(nErr)) // Print error code
	}
}

func Code

func Code(err error) int

Code returns the code of the provided error. Returns 0 if the error has no error code.

Code will return the error code of any error value that satisfies the following interface:

type withCode interface {
    Code() int
}

Example

package main

import (
	"fmt"
	"net/http"

	"github.com/adrg/errors"
)

func main() {
	err := errors.HTTPf(nil, http.StatusNotFound, "invalid endpoint")

	// Print error code.
	fmt.Println(errors.Code(err))
}

func Errorf

func Errorf(format string, args ...interface{}) error

Errorf returns a new error formatted according to the format specifier.

Example

package main

import (
	"fmt"

	"github.com/adrg/errors"
)

func main() {
	err := errors.Errorf("invalid user ID: %d", 0)

	fmt.Printf("%s\n", err)  // Print error message only.
	fmt.Printf("%v\n", err)  // Print error chain without stack details.
	fmt.Printf("%+v\n", err) // Print error chain with stack details.
}

func HTTPf

func HTTPf(err error, code int, format string, args ...interface{}) error

HTTPf returns a new HTTP error which annotates err according to the format specifier and has the provided status code.

Example

package main

import (
	"fmt"
	"net/http"
	"strings"

	"github.com/adrg/errors"
)

func main() {
	validateEmail := func(email string) error {
		if strings.Contains(email, " ") {
			return errors.New("email address cannot contain spaces")
		}

		return nil
	}

	email := "alice @example.com"
	if err := validateEmail(email); err != nil {
		err = errors.HTTPf(err, http.StatusBadRequest, "invalid email %s", email)

		fmt.Printf("%s\n", err)       // Print error message only.
		fmt.Printf("%v\n", err)       // Print error chain without stack details.
		fmt.Printf("%+v\n", err)      // Print error chain with stack details.
		fmt.Println(errors.Code(err)) // Print error code.
	}
}

func Is

func Is(err, target error) bool

Is reports whether err or any of the errors in its chain is equal to target.

Example

package main

import (
	"fmt"

	"github.com/adrg/errors"
)

func main() {
	errInvalid := errors.New("invalid data")

	err := errors.Annotate(errInvalid, "validation failed")
	if errors.Is(err, errInvalid) {
		fmt.Println("err is invalidErr")
	}
}

func New

func New(message string) error

New returns a new error with the specified message.

Example

package main

import (
	"fmt"

	"github.com/adrg/errors"
)

func main() {
	err := errors.New("something bad happened")

	fmt.Printf("%s\n", err)  // Print error message only.
	fmt.Printf("%v\n", err)  // Print error chain without stack details.
	fmt.Printf("%+v\n", err) // Print error chain with stack details.
}

func NewHTTP

func NewHTTP(err error, code int, message string) error

NewHTTP returns a new HTTP error which annotates err with the specified message and has the provided status code.

Example

package main

import (
	"fmt"
	"net/http"
	"strconv"

	"github.com/adrg/errors"
)

func main() {
	_, err := strconv.Atoi("this will fail")
	if err != nil {
		err = errors.NewHTTP(err, http.StatusBadRequest, "invalid data")

		fmt.Printf("%s\n", err)       // Print error message only.
		fmt.Printf("%v\n", err)       // Print error chain without stack details.
		fmt.Printf("%+v\n", err)      // Print error chain with stack details.
		fmt.Println(errors.Code(err)) // Print error code.
	}
}

func Unwrap

func Unwrap(err error) error

Unwrap returns the next error in the error chain. If there is no next error, Unwrap returns nil.

Any error value that satisfies the following interface can be unwrapped:

type wrapper interface {
    Unwrap() error
}

Example

package main

import (
	"fmt"

	"github.com/adrg/errors"
)

func main() {
	err := errors.Annotate(errors.New("first error"), "second error")
	if next := errors.Unwrap(err); next != nil {
		fmt.Printf("%s\n", next)  // Print error message only.
		fmt.Printf("%v\n", next)  // Print error chain without stack details.
		fmt.Printf("%+v\n", next) // Print error chain with stack details.
	}
}

func Wrap

func Wrap(dst, next error) error

Wrap sets next as the next error in the chain of dst, thus making next the direct cause of dst. Returns nil if the dst argument is nil.

Example

package main

import (
	"fmt"
	"strconv"

	"github.com/adrg/errors"
)

func main() {
	errInvalid := errors.New("invalid data")

	_, err := strconv.Atoi("this will fail")
	if err != nil {
		err = errors.Wrap(errInvalid, err)
	}

	fmt.Printf("%s\n", err)  // Print error message only.
	fmt.Printf("%v\n", err)  // Print error chain without stack details.
	fmt.Printf("%+v\n", err) // Print error chain with stack details.
}

Types

type HTTP

type HTTP interface {
	error

	// Code returns the HTTP status code of the error.
	Code() int
}

HTTP represents an HTTP error.