errors

package module
Version: v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 30, 2019 License: BSD-3-Clause Imports: 7 Imported by: 0

README

GoDoc Go Report Card Build Status tag release

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

View Source
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

Variables

This section is empty.

Functions

func Encode added in v0.0.5

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 added in v0.0.7

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 added in v0.0.7

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 added in v0.0.2

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 added in v0.0.2

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 added in v0.0.2

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

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

func (*Error) Unserialize added in v0.0.5

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 added in v0.0.5

type Kind uint8

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

type Location added in v0.0.4

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 added in v0.0.4

func Here() Location

Here return the file:line of calling Here()

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL