erf

package module
v1.3.1 Latest Latest
Warning

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

 Go to latest Published: Mar 4, 2022 License: BSD-3-Clause Imports: 8 Imported by: 2

README

erf

Go Reference

Package erf provides error management with stack trace. Erf is an error type that wraps the underlying error that stores and formats the stack trace. Please see godoc.

Examples

To run any example, please use the command like the following:

cd examples/
go run example1.go

Tests

To run all tests, please use the following command:

go test -v

To run all examples, please use the following command:

go test -v -run=^Example

To run all benchmarks, please use the following command:

go test -v -run=^Benchmark -bench=.

Documentation

Overview

Package erf provides error management with stack trace.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultPCSize defines max length of Erf program counters in PC() method.
	DefaultPCSize = int(uintptr(os.Getpagesize()) / unsafe.Sizeof(uintptr(0)))
)

Functions

func Errorf 

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

Errorf is similar with Newf except that it returns the error interface instead of the Erf pointer.

func PC added in v1.0.0 

func PC(size, skip int) []uintptr

PC returns program counters by using runtime.Callers.

func Wrap 

func Wrap(err error) error

Wrap wraps the given error as the underlying error and returns a new Erf object as the error interface. Wrap is similar with Newf("%w", err) except that it returns nil if err is nil.

func Wrapp added in v1.1.3 

func Wrapp(perr *error)

Wrapp wraps the error in the given pointer and returns a new Erf object onto the given pointer. Wrapp is similar with Newf("%w", err) except that it returns to perr and doesn't affect if perr or *perr is nil.

Types

type Erf 

type Erf struct {
	// contains filtered or unexported fields
}

Erf is an error type that wraps the underlying error that stores and formats the stack trace.

Example 
package main

import (
	"fmt"

	"github.com/goinsane/erf"
)

func main() {
	e := erf.New("an example erf error")
	err := erf.Errorf("we have an example error: %w", e)

	fmt.Println("just show the first error message without padding and indent.")
	fmt.Printf("%v\n\n", err)

	fmt.Println("list all error messages by using indent and show StackTrace of errors by using format '%+s'.")
	fmt.Printf("%x\n\n", err)

	fmt.Println("list all error messages by using indent and show StackTrace of errors by using format '% s'.")
	fmt.Printf("% x\n\n", err)

	fmt.Println("list all error messages by using indent and show StackTrace of errors by using format '%#s'.")
	fmt.Printf("%#x\n\n", err)

	fmt.Println("list all error messages by using indent and show StackTrace of errors by using format '% #s'.")
	fmt.Printf("% #x\n\n", err)

	fmt.Println("show the first error message by using indent and show the StackTrace of error by using format '%+s'.")
	fmt.Printf("%X\n\n", err)

	fmt.Println("show the first error message by using indent and show the StackTrace of error by using format '% s'.")
	fmt.Printf("% X\n\n", err)

	fmt.Println("show the first error message by using indent and show the StackTrace of error by using format '%#s'.")
	fmt.Printf("%#X\n\n", err)

	fmt.Println("show the first error message by using indent and show the StackTrace of error by using format '% #s'.")
	fmt.Printf("% #X\n\n", err)

	fmt.Println("don't show any error messages, just show all of StackTrace of errors.")
	fmt.Printf("%-x\n\n", err)

	fmt.Println("don't show the error message, just show the StackTrace of the first error.")
	fmt.Printf("%-X\n\n", err)

	fmt.Println("padding 2, indent 1 by default. padding char '\\t'.")
	fmt.Printf("%2x\n\n", err)

	fmt.Println("padding 2, indent 3. padding char '\\t'.")
	fmt.Printf("%2.3x\n\n", err)

	fmt.Println("padding 0 by default, indent 3. padding char '\\t'.")
	fmt.Printf("%.3x\n\n", err)

	fmt.Println("padding 2, indent 2 by default. padding char ' '.")
	fmt.Printf("% 2x\n\n", err)

	fmt.Println("padding 2, indent 3. padding char ' '.")
	fmt.Printf("% 2.3x\n\n", err)

	fmt.Println("padding 0 by default, indent 3. padding char ' '.")
	fmt.Printf("% .3x\n\n", err)
}

Output:

func New 

func New(text string) *Erf

New creates a new Erf object with the given text.

func Newf 

func Newf(format string, args ...interface{}) *Erf

Newf creates a new Erf object with the given format and args. It panics if an any arg is nil.

func (*Erf) Arg 

func (e *Erf) Arg(index int) interface{}

Arg returns an argument value on the given index. It panics if index is out of range.

func (*Erf) Args 

func (e *Erf) Args() []interface{}

Args returns all argument values. It returns nil if Erf didn't create with formatting functions.

func (*Erf) Attach 

func (e *Erf) Attach(tags ...string) *Erf

Attach attaches tags to arguments, if arguments are given. If tag is "", it passes attaching tag to corresponding argument. It panics for given errors: 

tags are already attached
number of tags is more than args
tag already defined

func (*Erf) Attach2 added in v1.2.0 

func (e *Erf) Attach2(tags ...string) error

Attach2 is similar with Attach except that it returns the error interface instead of the Erf pointer.

func (*Erf) Copy added in v1.3.0 

func (e *Erf) Copy() *Erf

Copy creates a shallow copy of Erf.

func (*Erf) CopyByTop added in v1.3.0 

func (e *Erf) CopyByTop(top int) *Erf

CopyByTop creates a shallow copy of Erf that copies program counters downward from the argument top. If the argument top is out of range, it panics.

func (*Erf) Error 

func (e *Erf) Error() string

Error is implementation of error.

func (*Erf) Fmt 

func (e *Erf) Fmt() string

Fmt returns the format argument of the formatting functions (Newf, Errorf or Wrap) that created Erf.

func (*Erf) Format 

func (e *Erf) Format(f fmt.State, verb rune)

Format is implementation of fmt.Formatter. Format lists error messages and appends StackTrace's for underlying Erf and all of wrapped Erf's, line by line with given format.

For '%v' (also '%s'): 

%v       just show the first error message without padding and indent.

For '%x' and '%X': 

%x       list all error messages by using indent and show StackTrace of errors by using format '%+s'.
%+x      similar with '%x', also shows tags.
% x      list all error messages by using indent and show StackTrace of errors by using format '% s'.
%#x      list all error messages by using indent and show StackTrace of errors by using format '%#s'.
% #x     list all error messages by using indent and show StackTrace of errors by using format '% #s'.
%X       show the first error message by using indent and show the StackTrace of error by using format '%+s'.
%+X      similar with '%X', also shows tags.
% X      show the first error message by using indent and show the StackTrace of error by using format '% s'.
%#X      show the first error message by using indent and show the StackTrace of error by using format '%#s'.
% #X     show the first error message by using indent and show the StackTrace of error by using format '% #s'.
%-x      don't show any error messages, just show all of StackTrace of errors.
%-X      don't show the error message, just show the StackTrace of the first error.
%4x      same with '%x', padding 4, indent 1 by default.
%.3x     same with '%x', padding 0 by default, indent 3.
%4.3x    same with '%x', padding 4, indent 3.
%4.x     same with '%x', padding 4, indent 0.
% 4x     same with '% x', padding 4, indent 2 by default.
% .3x    same with '% x', padding 0 by default, indent 3.
% 4.3x   same with '% x', padding 4, indent 3.
% 4.x    same with '% x', padding 4, indent 0.
%#4.3x   same with '%#x', padding 4, indent 3.
% #4.3x  same with '% #x', padding 4, indent 3.

func (*Erf) Len 

func (e *Erf) Len() int

Len returns the length of all arguments.

func (*Erf) PC 

func (e *Erf) PC() []uintptr

PC returns all program counters.

func (*Erf) PCLen added in v1.2.2 

func (e *Erf) PCLen() int

PCLen returns the length of all program counters.

func (*Erf) StackTrace 

func (e *Erf) StackTrace() *StackTrace

StackTrace returns a StackTrace of Erf.

func (*Erf) Tag 

func (e *Erf) Tag(tag string) interface{}

Tag returns an argument value on the given tag. It returns nil if tag is not found.

func (*Erf) TagIndex added in v1.2.3 

func (e *Erf) TagIndex(tag string) int

TagIndex returns index of an argument on the given tag. It returns -1 if tag is not found.

func (*Erf) Tags added in v1.2.0 

func (e *Erf) Tags() []string

Tags returns all tags sequentially. It returns nil if tags are not attached.

func (*Erf) TagsLen added in v1.2.2 

func (e *Erf) TagsLen() int

TagsLen returns the length of all tags.

func (*Erf) Unwrap 

func (e *Erf) Unwrap() error

Unwrap returns the underlying error.

func (*Erf) UnwrapAll added in v1.2.1 

func (e *Erf) UnwrapAll() []error

UnwrapAll returns all errors using Unwrap method. The first element in the returned value is e.

type StackCaller 

type StackCaller struct {
	runtime.Frame
}

StackCaller stores the information of stack caller. StackCaller can format given information as string by using Format or String methods.

Example 
package main

import (
	"fmt"

	"github.com/goinsane/erf"
)

func main() {
	e := erf.New("an example erf error")
	sc := e.StackTrace().Caller(0)

	fmt.Println("just show function and entry without padding and indent.")
	fmt.Printf("%s\n\n", sc)

	fmt.Println("show file path, line and pc. padding char '\\t', default padding 0, default indent 1.")
	fmt.Printf("%+s\n\n", sc)

	fmt.Println("use file name as file path.")
	fmt.Printf("%#s\n\n", sc)

	fmt.Println("padding 2, indent 1 by default.")
	fmt.Printf("%#2s\n\n", sc)

	fmt.Println("padding 2, indent 3.")
	fmt.Printf("%#2.3s\n\n", sc)

	fmt.Println("show file path, line and pc. padding char ' ', default padding 0, default indent 2.")
	fmt.Printf("% s\n\n", sc)

	fmt.Println("use file name as file path.")
	fmt.Printf("% #s\n\n", sc)

	fmt.Println("padding 2, indent 2 by default.")
	fmt.Printf("% #2s\n\n", sc)

	fmt.Println("padding 2, indent 3.")
	fmt.Printf("% #2.3s\n\n", sc)
}

Output:

func (StackCaller) Format 

func (c StackCaller) Format(f fmt.State, verb rune)

Format is implementation of fmt.Formatter.

For '%s' (also '%v'): 

%s       just show function and entry without padding and indent.
%+s      show file path, line and pc. padding char '\t', default padding 0, default indent 1.
% s      show file path, line and pc. padding char ' ', default padding 0, default indent 2.
%+ s     exact with '% s'.
%#s      same with '%+s', use file name as file path.
%+#s     exact with '%#s'.
% #s     same with '% s', use file name as file path.
%+4s     same with '%+s', padding 4, indent 1 by default.
%+.3s    same with '%+s', padding 0 by default, indent 3.
%+4.3s   same with '%+s', padding 4, indent 3.
%+4.s    same with '%+s', padding 4, indent 0.
% 4s     same with '% s', padding 4, indent 2 by default.
% .3s    same with '% s', padding 0 by default, indent 3.
% 4.3s   same with '% s', padding 4, indent 3.
% 4.s    same with '% s', padding 4, indent 0.
%#4.3s   same with '%#s', padding 4, indent 3.
% #4.3s  same with '% #s', padding 4, indent 3.

func (StackCaller) String 

func (c StackCaller) String() string

String is implementation of fmt.Stringer. It is synonym with fmt.Sprintf("%s", c).

type StackTrace 

type StackTrace struct {
	// contains filtered or unexported fields
}

StackTrace stores the information of stack trace.

Example 
package main

import (
	"fmt"

	"github.com/goinsane/erf"
)

func main() {
	e := erf.New("an example erf error")
	st := e.StackTrace()

	fmt.Println("default")
	fmt.Printf("%s\n\n", st)

	fmt.Println("show file path, line and pc. padding char '\\t', default padding 0, default indent 1.")
	fmt.Printf("%+s\n\n", st)

	fmt.Println("show file path, line and pc. padding char ' ', default padding 0, default indent 2.")
	fmt.Printf("% s\n\n", st)
}

Output:

func NewStackTrace 

func NewStackTrace(pc ...uintptr) *StackTrace

NewStackTrace creates a new StackTrace object.

func (*StackTrace) Caller 

func (t *StackTrace) Caller(index int) StackCaller

Caller returns a StackCaller on the given index. It panics if index is out of range.

func (*StackTrace) Duplicate 

func (t *StackTrace) Duplicate() *StackTrace

Duplicate duplicates the StackTrace object.

func (*StackTrace) Format 

func (t *StackTrace) Format(f fmt.State, verb rune)

Format is implementation of fmt.Formatter. Format lists all StackCaller's in StackTrace line by line with given format.

func (*StackTrace) Len 

func (t *StackTrace) Len() int

Len returns the length of the length of all Caller's.

func (*StackTrace) PC 

func (t *StackTrace) PC() []uintptr

PC returns program counters.

func (*StackTrace) String 

func (t *StackTrace) String() string

String is implementation of fmt.Stringer. It is synonym with fmt.Sprintf("%s", t).

type WrappedError 

type WrappedError interface {
	error
	Unwrap() error
}

WrappedError is an interface to simulate GoLang's wrapped errors.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.