errstack

README

errstack

a cumulative container for go language errors

A common idiom in go is for a function to return 'error or 'nil', where 'error' is an object that implements the error interface.

This return value may be passed up a chain of calling functions until some caller wants to deal with it.

see http://blog.golang.org/error-handling-and-go

It is often useful for intervening functions to add information to the error before passing it on.

for example:

func UseObject() {
	if object, err := FetchObject(); err != nil  {
		log.Fatalf("UseObject could not FetchObject: %s", err)
	}
}

func FetchOject() (Object, error) {
	if err := CreateObject(); err != nil  {
		nil, fmt.Errorf("FetchObject count not CreateObject: %s", err)
	}
}

func CreatObject() (Object, error) {
	file, err := os.Open("invalid path"); err != nil {
		return nil, err
	}
}

This idiom suffers from two drawbacks: 1) It's hard to maintain a consistent format 2) there are cases where a calling function wants to examine the original error.

That's is what errstack is for:

func UseObject() {
	if object, err := FetchObject(); err != nil  {
		if pathError, ok := err.Root().(*os.PathError); ok {
			// do something special for PathError
		}
		log.Fatalf("UseObject could not FetchObject: %s", err)
	}
}

func FetchOject() (Object, error) {
	if err := CreateObject(); err != nil  {
		return nil, errstack.Push(err, "FetchObject")
	}
}

func CreatObject() (Object, error) {
	if file, err := os.Open("invalid path"); err != nil {
		return nil, errstack.Push(err, "CreateObject")
	}
}

INSTALL

go get github.com/SpiderOak/errstack

import github.com/SpiderOak/errstack

FUNCTIONS

// Push starts a new stack or appends message to the existing stack
func Push(err error, message string) error

// Pushf starts a new stack or appends a formatted message to the existing stack
func Pushf(err error, format string, params ...[]string) error

// PushN starts a new stack or appends the name of the calling function to the
// existing stack
func PushN(err error) error

// PushNf starts a new stack or appends the name of the calling function
// concatenated with a formatted message to the existing stack
func PushNf(err error, format string, params ...[]string) error

TYPES

// ErrStack represents a 'stack' of errors
type ErrStack interface {
    // implement the error interface
    error

    // Root returns the original error
    Root() error

    // Stack returns a slice of strings that are in the order of the call stack.
    // The final string is the output of Error() from the root error
    Stack() []string

    // Join returns a string made by joining the
    Join(sep string) string
}

Documentation

Overview

 errstack is a package that manages a cumulative 'stack' of go errors

   A common idiom in go is for a function to return 'error or 'nil',
   where 'error' is an object that implements the error interface.

   This return value may be passed up a chain of calling functions until
   some caller wants to deal with it.

   see http://blog.golang.org/error-handling-and-go

   It is often useful for intervening functions to add information to the
   error before passing it on.

   for example:

       func UseObject() {
			if object, err := FetchObject(); err != nil  {
				log.Fatalf("UseObject could not FetchObject: %s", err)
			}
       }

       func FetchOject() (Object, error) {
			if err := CreateObject(); err != nil  {
				fmt.Errorf("FetchObject count not CreateObject: %s", err)
			}
       }

       func CreatObject() (Object, error) {
			file, err := os.Open("invalid path"); err != nil {
				return err
			}
       }

    This idiom suffers from two drawbacks: 1) It's hard to maintain a
    consistennt format and 2) therre are cases where a calling function
    wants to examine the original error.

    This is what errstack is for:

       func UseObject() {
			if object, err := FetchObject(); err != nil  {
				if pathError, ok := err.Root().(*os.PathError); ok {
					// do something special for PathError
				}
				log.Fatalf("UseObject could not FetchObject: %s", err)
			}
       }

       func FetchOject() (Object, error) {
			if err := CreateObject(); err != nil  {
				return errstat.Push(err, "FetchObject")
			}
       }

       func CreatObject() (Object, error) {
			if file, err := os.Open("invalid path"); err != nil {
				return errstat.Push(err, "CreateObject")
			}
       }

Index

• func Push(err error, message string) error
• func PushN(err error) error
• func PushNf(err error, format string, params ...interface{}) error
• func Pushf(err error, format string, params ...interface{}) error
• type ErrStack

Functions

func Push

func Push(err error, message string) error

Push starts a new stack or appends message to the existing stack

func PushN

func PushN(err error) error

PushN starts a new stack or appends the name of the calling function to the existing stack

func PushNf

func PushNf(err error, format string, params ...interface{}) error

PushNf starts a new stack or appends the name of the calling function concatenated with a formatted message to the existing stack

func Pushf

func Pushf(err error, format string, params ...interface{}) error

Pushf starts a new stack or appends a formatted message to the existing stack

Types

type ErrStack

type ErrStack interface {
	// implement the error interface
	error

	// Root returns the original error
	Root() error

	// Stack returns a slice of strings that are in the order of the call stack.
	// The final string is the output of Error() from the root error
	Stack() []string

	// Join returns a string made by joining the
	Join(sep string) string
}

ErrStack represents a 'stack' of errors