errs

README

this pkg is from https://github.com/fengjx/go-halo/errs

Documentation

Overview

Example (StackTrace)

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errs.Wrap(e1, "inner")
	e3 := errs.Wrap(e2, "middle")
	return errs.Wrap(e3, "outer")
}

func main() {
	type stackTracer interface {
		StackTrace() errs.StackTrace
	}

	err, ok := errs.Cause(fn()).(stackTracer)
	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/fengjx/go-halo/errs_test.fn
	//	/home/dfc/src/github.com/fengjx/go-halo/errs/example_test.go:47
	// github.com/fengjx/go-halo/errs_test.Example_stackTrace
	//	/home/dfc/src/github.com/fengjx/go-halo/errs/example_test.go:127
}

Index

• func Cause(err error) error
• func Errorf(format string, args ...interface{}) error
• func New(msg string) error
• func Recover()
• func RecoverFunc(fn RecoverHandle)
• func RegisterRecoverHandle(fn RecoverHandle)
• func WithMessage(err error, message string) error
• func WithMessagef(err error, format string, args ...interface{}) error
• func WithStack(err error) error
• func Wrap(err error, message string) error
• func Wrapf(err error, format string, args ...interface{}) error
• type Frame
  • func (f Frame) Format(s fmt.State, verb rune)
  • func (f Frame) MarshalText() ([]byte, error)
• type RecoverHandle
• type Stack
  • func Callers(skip, depth int) *Stack
  • func (s *Stack) Format(st fmt.State, verb rune)
  • func (s *Stack) StackTrace() StackTrace
• type StackTrace
  • func (st StackTrace) Format(s fmt.State, verb rune)

Examples

• Package (StackTrace)
• Cause
• Cause (Printf)
• Errorf (Extended)
• New
• New (Printf)
• WithMessage
• WithStack
• WithStack (Printf)
• Wrap
• Wrap (Extended)
• Wrapf

Functions

func Cause

func Cause(err error) error

Cause 返回根因 error 查找第一个没有实现 causer 的 error，认为是根因

Example

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errs.Wrap(e1, "inner")
	e3 := errs.Wrap(e2, "middle")
	return errs.Wrap(e3, "outer")
}

func main() {
	err := fn()
	fmt.Println(err)
	fmt.Println(errs.Cause(err))

}

Output:

outer: middle: inner: error
error

Example (Printf)

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func main() {
	err := errs.Wrap(func() error {
		return func() error {
			return errors.New("hello world")
		}()
	}(), "failed")

	fmt.Printf("%v", err)

}

Output:

failed: hello world

func Errorf

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

Errorf 根据 format 创建一个 error，同时记录调用栈

Example (Extended)

package main

import (
	"fmt"
)

func main() {
	err := fmt.Errorf("whoops: %s", "foo")
	fmt.Printf("%+v", err)

	// Example output:
	// whoops: foo
	// github.com/fengjx/go-halo/errs_test.ExampleErrorf
	//         /home/dfc/src/github.com/fengjx/go-halo/errs/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/fengjx/go-halo/errs/_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
}

func New

func New(msg string) error

New 根据 msg 创建一个 error，同时记录调用栈

Example

package main

import (
	"errors"
	"fmt"
)

func main() {
	err := errors.New("whoops")
	fmt.Println(err)

}

Output:

whoops

Example (Printf)

package main

import (
	"errors"
	"fmt"
)

func main() {
	err := errors.New("whoops")
	fmt.Printf("%+v", err)

	// Example output:
	// whoops
	// github.com/fengjx/go-halo/errs_test.ExampleNew_printf
	//         /home/dfc/src/github.com/fengjx/go-halo/errs/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/fengjx/go-halo/errs/_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
}

func Recover

func Recover()

Recover recover 处理，打印堆栈 直接defer errs.Recover() 而不能defer func(){errs.Recover()}

func RecoverFunc

func RecoverFunc(fn RecoverHandle)

func RegisterRecoverHandle

func RegisterRecoverHandle(fn RecoverHandle)

RegisterRecoverHandle 自定义的recover处理函数

func WithMessage

func WithMessage(err error, message string) error

WithMessage annotates err with a new message. If err is nil, WithMessage returns nil.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func main() {
	cause := errors.New("whoops")
	err := errs.WithMessage(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops

func WithMessagef

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

WithMessagef annotates err with the format specifier. If err is nil, WithMessagef returns nil.

func WithStack

func WithStack(err error) error

WithStack annotates err with a stack trace at the point WithStack was called. If err is nil, WithStack returns nil.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func main() {
	cause := errors.New("whoops")
	err := errs.WithStack(cause)
	fmt.Println(err)

}

Output:

whoops

Example (Printf)

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func main() {
	cause := errors.New("whoops")
	err := errs.WithStack(cause)
	fmt.Printf("%+v", err)

	// Example Output:
	// whoops
	// github.com/fengjx/go-halo/errs_test.ExampleWithStack_printf
	//         /home/fabstu/go/src/github.com/fengjx/go-halo/errs/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/fengjx/go-halo/errs/_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/fengjx/go-halo/errs_test.ExampleWithStack_printf
	//         /home/fabstu/go/src/github.com/fengjx/go-halo/errs/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/fengjx/go-halo/errs/_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
}

func Wrap

func Wrap(err error, message string) error

Wrap returns an error annotating err with a stack trace at the point Wrap is called, and the supplied message. If err is nil, Wrap returns nil.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func main() {
	cause := errors.New("whoops")
	err := errs.Wrap(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops

Example (Extended)

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errs.Wrap(e1, "inner")
	e3 := errs.Wrap(e2, "middle")
	return errs.Wrap(e3, "outer")
}

func main() {
	err := fn()
	fmt.Printf("%+v\n", err)

	// Example output:
	// error
	// github.com/fengjx/go-halo/errs_test.fn
	//         /home/dfc/src/github.com/fengjx/go-halo/errs/example_test.go:47
	// github.com/fengjx/go-halo/errs_test.ExampleCause_printf
	//         /home/dfc/src/github.com/fengjx/go-halo/errs/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/fengjx/go-halo/errs/_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/fengjx/go-halo/errs_test.fn
	// 	  /home/dfc/src/github.com/fengjx/go-halo/errs/example_test.go:48: inner
	// github.com/fengjx/go-halo/errs_test.fn
	//        /home/dfc/src/github.com/fengjx/go-halo/errs/example_test.go:49: middle
	// github.com/fengjx/go-halo/errs_test.fn
	//      /home/dfc/src/github.com/fengjx/go-halo/errs/example_test.go:50: outer
}

func Wrapf

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

Wrapf returns an error annotating err with a stack trace at the point Wrapf is called, and the format specifier. If err is nil, Wrapf returns nil.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/fengjx/go-halo/errs"
)

func main() {
	cause := errors.New("whoops")
	err := errs.Wrapf(cause, "oh noes #%d", 2)
	fmt.Println(err)

}

Output:

oh noes #2: whoops

Types

type Frame

type Frame struct {
	Frame    runtime.Frame
	File     string
	Function string
	FuncName string
}

func (Frame) Format

func (f Frame) Format(s fmt.State, verb rune)

func (Frame) MarshalText

func (f Frame) MarshalText() ([]byte, error)

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 RecoverHandle

type RecoverHandle func(any, *Stack)

type Stack

type Stack []uintptr

Stack represents a stack of program counters.

func Callers

func Callers(skip, depth int) *Stack

Callers 获取调用站

func (*Stack) Format

func (s *Stack) Format(st fmt.State, verb rune)

func (*Stack) StackTrace

func (s *Stack) StackTrace() StackTrace

StackTrace 转换为 StackTrace

type StackTrace

type StackTrace []*Frame

StackTrace 调用堆栈

func (StackTrace) Format

func (st StackTrace) Format(s fmt.State, verb rune)