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 Cause(err error) error
• func EncodeJSON(err error) string
• func New(msg string, opts ...ErrorContextFunc) error
• func Wrap(err error, msg string, opts ...ErrorContextFunc) error
• type Error
  • 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) JSON() string
  • func (e *Error) MarshalJSON() ([]byte, error)
  • func (e *Error) SetContext(name string, value interface{})
  • func (e *Error) String() string
  • func (e *Error) Unwrap() error
• type ErrorContextFunc
  • func WithContext(name, value string) ErrorContextFunc

Examples

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

Functions

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 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 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"}}

Types

type Error

type Error struct {
	//Msg element is error message.
	Msg     string
	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) 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) JSON

func (e *Error) JSON() string

JSON method returns serialize string of Error with JSON format.

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{})

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, value string) 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"}}