errors

README

errors

A drop in replacement for Go's stdlib errors package with support for previous errors.

This module is largely copied-n-pasted from upspin.io/errors. It removes of the various Kinds offered in upspin and adds Location to report the file and line of the invocation of Here().

After grokking upspin.io/errors, the serialization format is simply |---int64(len(v))---|---v---| and repeat. This requires the sender to include all values (even zeroes) and the receiving end to know the order. To add labels/types would be trivial but seems unnecessary as the library also includes the Unserialize func.

To the extent that the errors should be logged or stored in such a way that Unserialize isn't used, Error() allows for the string representation of the error stack (default format is message[[[ = kind] @ location]\n\t]). The "\n\t" can be changed via Sep. There is always json.Marshal() which will do exactly as expected. I've included Encode() which returns a delimiter separated value (DSV) formated string. Think CSV but using unit (31) and field (30) separators (more info). It's esoteric, but that is the purpose for which they were created. Wanna read it? ... | tr "\036\037" "\n,". Again, this most likely won't be used much, but it was fun.

This library allows for arbitrary Kinds. Where upspin defines the error Kinds used within, this library is a drop-in for the stdlib's errors. Thus, the importing context needs to define the Kinds and the string/descr (if any). This lib simply allows for the storage/transfer of the uint8(Kind). Further, upspin serialized Kind as a scalar value with no length (it was only ever always encoded as 1 int64). For now, this library chooses to add a length param simply to keep the serialized format consistent. Admittedly, the extra bytes and flops used aren't strictly necessary.

Documentation

Index

• Constants
• func Encode(e error) string
• func Errorf(format string, args ...interface{}) error
• func Has(err error, k Kind) (error, bool)
• func Is(err error, k Kind) bool
• func New(args ...interface{}) error
• func Serialize(err error, args ...interface{}) []byte
• func Str(text string) error
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Serialize(b []byte) []byte
  • func (e *Error) Unserialize(b []byte) error
• type Kind
• type Location
  • func Here() Location

Constants

const (
	Sep       = "\n\t"
	RecordSep = "\036" // byte(30) || "\x1e" ... is the ascii Record Separator (RS) character
	UnitSep   = "\037" // byte(31) || "\x1e" ... is the ascii Unit Separator (US) character
)

Sep and UnitSep are used to separate/delim fields

Functions

func Encode

func Encode(e error) string

Encode takes the error and DSV encodes is for storage. It's a bit esoteric to use byte(30) and byte(31) as delimeters, but that's why those characters exist. Without type info, this isn't all that useful.

func Errorf

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

Errorf is equivalent to fmt.Errorf, but allows clients to import only this package for all error handling.

func Has

func Has(err error, k Kind) (error, bool)

Has checks to see if the error is of a certain kind. It returns the (matching error, true) or the (nil, false)

func Is

func Is(err error, k Kind) bool

Is checks to see if the error is of a certain kind

func New

func New(args ...interface{}) error

New creates a new Error of our own liking. The `string` args are assumed to be the error message. The `error`/`Error` arg is assumed to be a Prev. The `Location` arg is assumed to be the Location. The `Kind` arg is the Kind of the error.

func Serialize

func Serialize(err error, args ...interface{}) []byte

Serialize writes the entire stack using a binary encoding. The args passed should be the latest (topmost) error and a []byte to populate. The []byte arg will see almost no usage as it's primarily used for the recursive serializing. Although it's certainly not out of the realm of possibility that there is a []byte to be filled.

func Str

func Str(text string) error

Str returns an error that formats as the given text. It is intended to be used as the error-typed argument to the E function.

Types

type Error

type Error struct {
	Err      string   `json:"error,omitempty"`    // this error
	Kind     Kind     `json:"kind,omitempty"`     // the Kind of this error
	Location Location `json:"location,omitempty"` // the location of this error
	Prev     error    `json:"previous,omitempty"` // the previous error
}

Error is an error with an embedded "previous" error and a kind

func (*Error) Error

func (e *Error) Error() string

Error fulfills the error interface. The error stack will be of the format: `message[[[ = kind] @ location]\n\t]`

func (*Error) Serialize

func (e *Error) Serialize(b []byte) []byte

Serialize writes the entire stack using the format 'int64(len)[]bytes(value)'

func (*Error) Unserialize

func (e *Error) Unserialize(b []byte) error

Unserialize reads the byte slice into the receiver, which must be non-nil. The returned error is always nil.

type Kind

type Kind uint8

Kind is a custom int type to communicate the error's Kind.

type Location

type Location string

Location is the name:line of a file. Ideally returned by Here(). In usage it'll give you the file:line of the invocation of Here() to be passed as part of the error.

func Here

func Here() Location

Here return the file:line of calling Here()