Documentation
¶
Overview ¶
Package errors is heavily inspired by "github.com/pkg/errors"
Example (StackTrace) ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func fn() error {
e1 := errors.New("error")
e2 := errors.Wrapf(e1, "inner")
e3 := errors.Wrapf(e2, "middle")
return errors.Wrapf(e3, "outer")
}
func main() {
err, ok := errors.Cause(fn()).(errors.WithStackTrace)
if !ok {
panic("oops, err does not implement stackTracer")
}
st := err.StackTrace()
fmt.Printf("%+v", st[0:2]) // top two frames
// Example output:
// github.com/VirtusLab/go-extended/pkg/errors_test.fn
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:47
// github.com/VirtusLab/go-extended/pkg/errors_test.Example_stackTrace
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:127
}
Output:
Index ¶
- func Cause(err error) error
- func Errorf(format string, args ...interface{}) error
- func FormatCauseAndStack(err error, f *Stack, s fmt.State, verb rune)
- func New(message string) error
- func Wrap(e error) error
- func Wrapf(e error, format string, args ...interface{}) error
- type Frame
- type Stack
- type StackTrace
- type WithCause
- type WithStackTrace
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cause ¶
Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface:
type causer interface {
Cause() error
}
If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.
Example ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func fn() error {
e1 := errors.New("error")
e2 := errors.Wrapf(e1, "inner")
e3 := errors.Wrapf(e2, "middle")
return errors.Wrapf(e3, "outer")
}
func main() {
err := fn()
fmt.Println(err)
fmt.Println(errors.Cause(err))
}
Output: outer: middle: inner: error error
Example (Printf) ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func main() {
err := errors.Wrapf(func() error {
return func() error {
//lint:ignore S1039 the test introduces it on purpose
return errors.Errorf("hello %s", fmt.Sprintf("world"))
}()
}(), "failed")
fmt.Printf("%v", err)
}
Output: failed: hello world
func Errorf ¶
Errorf returns a new error with the supplied formatted message and stack trace. It records the stack trace at the point it was called.
Example (Extended) ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func main() {
err := errors.Errorf("whoops: %s", "foo")
fmt.Printf("%+v", err)
// Example output:
// whoops: foo
// github.com/VirtusLab/go-extended/pkg/errors_test.ExampleErrorf
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:101
// testing.runExample
// /home/dfc/go/src/testing/example.go:114
// testing.RunExamples
// /home/dfc/go/src/testing/example.go:38
// testing.(*M).Run
// /home/dfc/go/src/testing/testing.go:744
// main.main
// /github.com/VirtusLab/go-extended/pkg/errors/_test/_testmain.go:102
// runtime.main
// /home/dfc/go/src/runtime/proc.go:183
// runtime.goexit
// /home/dfc/go/src/runtime/asm_amd64.s:2059
}
Output:
func FormatCauseAndStack ¶
FormatCauseAndStack helps to implement fmt.Formatter used by Sprint(f) or Fprint(f) etc. Use for custom error implementations with Cause and StackFormatter
Example ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
type ErrCustom struct {
stack *errors.Stack
s string
}
func (e *ErrCustom) Error() string {
return e.s
}
func (e *ErrCustom) Format(s fmt.State, verb rune) {
errors.FormatCauseAndStack(e, e.stack, s, verb)
}
func (e *ErrCustom) StackTrace() errors.StackTrace {
return e.stack.StackTrace()
}
func NewErrCustom(s string) *ErrCustom {
return &ErrCustom{
stack: errors.Callers(),
s: s,
}
}
func main() {
err := NewErrCustom("whoops")
fmt.Println(err)
}
Output: whoops
Example (Printf) ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
type ErrCustom struct {
stack *errors.Stack
s string
}
func (e *ErrCustom) Error() string {
return e.s
}
func (e *ErrCustom) Format(s fmt.State, verb rune) {
errors.FormatCauseAndStack(e, e.stack, s, verb)
}
func (e *ErrCustom) StackTrace() errors.StackTrace {
return e.stack.StackTrace()
}
func NewErrCustom(s string) *ErrCustom {
return &ErrCustom{
stack: errors.Callers(),
s: s,
}
}
func main() {
err := NewErrCustom("whoops")
fmt.Printf("%+v", err)
// Example output:
// whoops
// github.com/VirtusLab/go-extended/pkg/errors_test.ExampleFormatCauseAndStack_prints
// /home/dfc/go/src/github.com/VirtusLab/go-extended/pkg/errors/custom_test.go:41
// testing.runExample
// /home/dfc/go/src/testing/example.go:121
// testing.runExamples
// /home/dfc/go/src/testing/example.go:45
// testing.(*M).Run
// /home/dfc/go/src/testing/testing.go:1073
// main.main
// _testmain.go:108
// runtime.main
// /home/dfc/go/src/runtime/proc.go:200
// runtime.goexit
// /home/dfc/go/src/runtime/asm_amd64.s:1337
}
Output:
func New ¶
New returns a new error with the supplied message and a stack trace. It records the stack trace at the point it was called.
Example ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func main() {
err := errors.New("whoops")
fmt.Println(err)
}
Output: whoops
Example (Printf) ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func main() {
err := errors.New("whoops")
fmt.Printf("%+v", err)
// Example output:
// whoops
// github.com/VirtusLab/go-extended/pkg/errors_test.ExampleNew_printf
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:17
// testing.runExample
// /home/dfc/go/src/testing/example.go:114
// testing.RunExamples
// /home/dfc/go/src/testing/example.go:38
// testing.(*M).Run
// /home/dfc/go/src/testing/testing.go:744
// main.main
// /github.com/VirtusLab/go-extended/pkg/errors/_test/_testmain.go:106
// runtime.main
// /home/dfc/go/src/runtime/proc.go:183
// runtime.goexit
// /home/dfc/go/src/runtime/asm_amd64.s:2059
}
Output:
func Wrap ¶
Wrap wraps a given error with a stack trace. Please note the error type will change when wrapped. It records the stack trace at the point it was called.
Example ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func main() {
cause := errors.New("whoops")
err := errors.Wrap(cause)
fmt.Println(err)
}
Output: whoops
Example (Extended) ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func fn() error {
e1 := errors.New("error")
e2 := errors.Wrapf(e1, "inner")
e3 := errors.Wrapf(e2, "middle")
return errors.Wrapf(e3, "outer")
}
func main() {
err := fn()
fmt.Printf("%+v\n", err)
// Example output:
// error
// github.com/VirtusLab/go-extended/pkg/errors_test.fn
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:47
// github.com/VirtusLab/go-extended/pkg/errors_test.ExampleCause_printf
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:63
// testing.runExample
// /home/dfc/go/src/testing/example.go:114
// testing.RunExamples
// /home/dfc/go/src/testing/example.go:38
// testing.(*M).Run
// /home/dfc/go/src/testing/testing.go:744
// main.main
// /github.com/VirtusLab/go-extended/pkg/errors/_test/_testmain.go:104
// runtime.main
// /home/dfc/go/src/runtime/proc.go:183
// runtime.goexit
// /home/dfc/go/src/runtime/asm_amd64.s:2059
// github.com/VirtusLab/go-extended/pkg/errors_test.fn
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:48: inner
// github.com/VirtusLab/go-extended/pkg/errors_test.fn
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:49: middle
// github.com/VirtusLab/go-extended/pkg/errors_test.fn
// /home/dfc/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:50: outer
}
Output:
Example (Printf) ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func main() {
cause := errors.New("whoops")
err := errors.Wrap(cause)
fmt.Printf("%+v", err)
// Example Output:
// whoops
// github.com/VirtusLab/go-extended/pkg/errors_test.ExampleWithStack_printf
// /home/fabstu/go/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:55
// testing.runExample
// /usr/lib/go/src/testing/example.go:114
// testing.RunExamples
// /usr/lib/go/src/testing/example.go:38
// testing.(*M).Run
// /usr/lib/go/src/testing/testing.go:744
// main.main
// github.com/VirtusLab/go-extended/pkg/errors/_test/_testmain.go:106
// runtime.main
// /usr/lib/go/src/runtime/proc.go:183
// runtime.goexit
// /usr/lib/go/src/runtime/asm_amd64.s:2086
// github.com/VirtusLab/go-extended/pkg/errors_test.ExampleWithStack_printf
// /home/fabstu/go/src/github.com/VirtusLab/go-extended/pkg/errors/example_test.go:56
// testing.runExample
// /usr/lib/go/src/testing/example.go:114
// testing.RunExamples
// /usr/lib/go/src/testing/example.go:38
// testing.(*M).Run
// /usr/lib/go/src/testing/testing.go:744
// main.main
// github.com/VirtusLab/go-extended/pkg/errors/_test/_testmain.go:106
// runtime.main
// /usr/lib/go/src/runtime/proc.go:183
// runtime.goexit
// /usr/lib/go/src/runtime/asm_amd64.s:2086
}
Output:
func Wrapf ¶
Wrapf wraps a given error with a formatted message and a stack trace. Please note the error type will change when wrapped. It records the stack trace at the point it was called.
Example ¶
package main
import (
"fmt"
"github.com/VirtusLab/go-extended/pkg/errors"
)
func main() {
cause := errors.New("whoops")
err := errors.Wrapf(cause, "oh noes")
fmt.Println(err)
cause = errors.New("whoops")
err = errors.Wrapf(cause, "oh noes #%d", 2)
fmt.Println(err)
// Example output:
// oh noes: whoops
// oh noes #2: whoops
}
Output:
Types ¶
type Frame ¶
type Frame uintptr
Frame represents a program counter inside a stack frame. For historical reasons if Frame is interpreted as a uintptr its value represents the program counter + 1.
func (Frame) Format ¶
Format formats the frame according to the fmt.Formatter interface.
%s source file %d source line %n function name %v equivalent to %s:%d
Format accepts flags that alter the printing of some verbs, as follows:
%+s function name and path of source file relative to the compile time
GOPATH separated by \n\t (<funcName>\n\t<path>)
%+v equivalent to %+s:%d
func (Frame) MarshalText ¶
MarshalText formats a stacktrace Frame as a text string. The output is the same as that of fmt.Sprintf("%+v", f), but without newlines or tabs.
type Stack ¶
type Stack []uintptr
Stack represents a stack of program counters.
func (*Stack) StackTrace ¶
func (s *Stack) StackTrace() StackTrace
StackTrace creates a StackTrace for this Stack
type StackTrace ¶
type StackTrace []Frame
StackTrace is stack of Frames from innermost (newest) to outermost (oldest).
func (StackTrace) Format ¶
func (st StackTrace) Format(s fmt.State, verb rune)
Format formats the stack of Frames according to the fmt.Formatter interface.
%s lists source files for each Frame in the stack %v lists the source file and line number for each Frame in the stack
Format accepts flags that alter the printing of some verbs, as follows:
%+v Prints filename, function, and line number for each Frame in the stack.
type WithCause ¶
type WithCause interface {
// Cause returns the error that caused this error
Cause() error
}
WithCause represents an error that was caused by another error
type WithStackTrace ¶
type WithStackTrace interface {
// StackTrace returns a stack trace for this error
StackTrace() StackTrace
}
WithStackTrace represents an error with a stack trace
Source Files
Click to show internal directories.
Click to hide internal directories.