errs

README

errs -- Error handling for Golang

Package errs implements functions to manipulate error instances. This package is required Go 1.13 or later.

Usage

package main

import (
    "fmt"
    "os"

    "github.com/spiegel-im-spiegel/errs"
)

func checkFileOpen(path string) error {
    file, err := os.Open(path)
    if err != nil {
        return errs.Wrap(
            err,
            "file open error",
            errs.WithContext("path", path),
        )
    }
    defer file.Close()

    return nil
}

func main() {
    if err := checkFileOpen("not-exist.txt"); err != nil {
        fmt.Printf("%v\n", err)             //file open error: open not-exist.txt: no such file or directory
        fmt.Printf("%#v\n", err)            //*errs.Error{Msg:"file open error", Context:map[string]interface {}{"function":"main.checkFileOpen", "path":"not-exist.txt"}, Cause:&os.PathError{Op:"open", Path:"not-exist.txt", Err:0x2}}
        fmt.Printf("%+v\n", err)            //{"Type":"*errs.Error","Msg":"file open error: open not-exist.txt: no such file or directory","Context":{"function":"main.checkFileOpen","path":"not-exist.txt"},"Cause":{"Type":"*os.PathError","Msg":"open not-exist.txt: no such file or directory","Cause":{"Type":"syscall.Errno","Msg":"no such file or directory"}}}
        fmt.Printf("%v\n", errs.Cause(err)) //no such file or directory
    }
}

Documentation

Overview

Package errs implements functions to manipulate error instances.

Index

• func As(err error, target interface{}) bool
• func Cause(err error) error
• func EncodeJSON(err error) string
• func Is(err, target error) bool
• func New(msg string, opts ...ErrorContextFunc) error
• func Unwrap(err error) error
• func Wrap(err error, msg string, opts ...ErrorContextFunc) error
• func WrapWithCause(err, cause error, opts ...ErrorContextFunc) error
• type Error
  • func (e *Error) EncodeJSON() string
  • func (e *Error) Error() string
  • func (e *Error) Format(s fmt.State, verb rune)
  • func (e *Error) GoString() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) MarshalJSON() ([]byte, error)
  • func (e *Error) SetContext(name string, value interface{}) *Error
  • func (e *Error) String() string
  • func (e *Error) Unwrap() error
• type ErrorContextFunc
  • func WithContext(name string, value interface{}) ErrorContextFunc

Examples

• Cause
• EncodeJSON
• Error
• New
• WithContext
• Wrap

Functions

func As

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

As is conpatible with errors.As.

func Cause

func Cause(err error) error

Cause function finds cause error in target error instance.

Example

package main

import (
	"fmt"
	"os"

	"github.com/spiegel-im-spiegel/errs"
)

func main() {
	_, err := os.Open("not-exist.txt")
	fmt.Printf("%v", errs.Cause(err))
}

Output:

no such file or directory

func EncodeJSON

func EncodeJSON(err error) string

EncodeJSON function dumps out error instance with JSON format.

Example

package main

import (
	"fmt"
	"os"

	"github.com/spiegel-im-spiegel/errs"
)

func main() {
	_, err := os.Open("not-exist.txt")
	fmt.Printf("%v", errs.EncodeJSON(err))
}

Output:

{"Type":"*os.PathError","Msg":"open not-exist.txt: no such file or directory","Cause":{"Type":"syscall.Errno","Msg":"no such file or directory"}}

func Is

func Is(err, target error) bool

Is is conpatible with errors.Is.

func New

func New(msg string, opts ...ErrorContextFunc) error

New function returns an error instance with message and context informations.

Example

package main

import (
	"fmt"

	"github.com/spiegel-im-spiegel/errs"
)

func main() {
	fmt.Printf("%+v", errs.New("custom error"))
}

Output:

{"Type":"*errs.Error","Msg":"custom error","Context":{"function":"github.com/spiegel-im-spiegel/errs_test.ExampleNew"}}

func Unwrap

func Unwrap(err error) error

Unwrap is conpatible with errors.Unwrap.

func Wrap

func Wrap(err error, msg string, opts ...ErrorContextFunc) error

Wrap function returns a wrapping error instance with message and context informations.

Example

package main

import (
	"fmt"
	"os"

	"github.com/spiegel-im-spiegel/errs"
)

func main() {
	fmt.Printf("%+v", errs.Wrap(os.ErrInvalid, "wrapper error"))
}

Output:

{"Type":"*errs.Error","Msg":"wrapper error: invalid argument","Context":{"function":"github.com/spiegel-im-spiegel/errs_test.ExampleWrap"},"Cause":{"Type":"*errors.errorString","Msg":"invalid argument"}}

func WrapWithCause

func WrapWithCause(err, cause error, opts ...ErrorContextFunc) error

Wrap function returns a wrapping error instance with message and context informations.

Types

type Error

type Error struct {
	Msg     error
	Cause   error
	Context map[string]interface{}
}

Error type is a implementation of error interface. This type is for wrapping cause error instance.

Example

package main

import (
	"fmt"
	"os"

	"github.com/spiegel-im-spiegel/errs"
)

func main() {
	err := errs.Wrap(
		os.ErrInvalid,
		"wrapper error",
		errs.WithContext("foo1", "bar1"),
	)
	_ = err.(*errs.Error).SetContext("foo2", "bar2")
	fmt.Printf("%+v", err)
}

Output:

{"Type":"*errs.Error","Msg":"wrapper error: invalid argument","Context":{"foo1":"bar1","foo2":"bar2","function":"github.com/spiegel-im-spiegel/errs_test.ExampleError"},"Cause":{"Type":"*errors.errorString","Msg":"invalid argument"}}

func (*Error) EncodeJSON

func (e *Error) EncodeJSON() string

EncodeJSON method returns serialize string of Error with JSON format.

func (*Error) Error

func (e *Error) Error() string

Error method returns error message. This method is a implementation of error interface.

func (*Error) Format

func (e *Error) Format(s fmt.State, verb rune)

Format method returns formatted string of Error instance. This method is a implementation of fmt.Formatter interface.

func (*Error) GoString

func (e *Error) GoString() string

GoString method returns serialize string of Error. This method is a implementation of fmt.GoStringer interface.

func (*Error) Is

func (e *Error) Is(target error) bool

Is method reports whether any error in error's chain matches cause of target error. This method is used in errors.Is function.

func (*Error) MarshalJSON

func (e *Error) MarshalJSON() ([]byte, error)

MarshalJSON method returns serialize string of Error with JSON format. This method is implementation of json.Marshaler interface.

func (*Error) SetContext

func (e *Error) SetContext(name string, value interface{}) *Error

SetContext method sets context information in Error instance

func (*Error) String

func (e *Error) String() string

String method returns error message. This method is a implementation of fmt.Stringer interface.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap method returns cause error in Error instance. This method is used in errors.Unwrap function.

type ErrorContextFunc

type ErrorContextFunc func(*Error)

ErrorContextFunc type is self-referential function type for New and Wrap functions. (functional options pattern)

func WithContext

func WithContext(name string, value interface{}) ErrorContextFunc

WithContext function returns ErrorContextFunc function value. This function is used in New and Wrap functions that represents context (key/value) data.

Example

package main

import (
	"fmt"
	"os"

	"github.com/spiegel-im-spiegel/errs"
)

func main() {
	err := errs.Wrap(
		os.ErrInvalid,
		"wrapper error",
		errs.WithContext("foo", "bar"),
	)
	fmt.Printf("%+v", err)
}

Output:

{"Type":"*errs.Error","Msg":"wrapper error: invalid argument","Context":{"foo":"bar","function":"github.com/spiegel-im-spiegel/errs_test.ExampleWithContext"},"Cause":{"Type":"*errors.errorString","Msg":"invalid argument"}}