README
¶
serr - special error implementations
serr originally stood for stream-error but it is only special handling for errors.
Documentation
¶
Index ¶
- func DeepFrames(err error) iter.Seq[iter.Seq[runtime.Frame]]
- func Frames(err error) iter.Seq[runtime.Frame]
- func Gather(errs ...error) error
- func GatherChecked(errs ...error) error
- func GatherPrefixed(errs []PrefixErr) error
- func GatherUnchecked(errs ...error) error
- func Pc(err error) []uintptr
- func Prefix(prefix string, err error) error
- func PrefixUnchecked(prefix string, err error) error
- func PrintStack(w io.Writer, err error) error
- func UnwrapStackErr(err error) error
- func WithStack(err error) error
- func WithStackOpt(err error, opt *WrapStackOpt) error
- type PrefixErr
- type WrapStackOpt
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DeepFrames ¶ added in v0.6.0
DeepFrames returns an iterator over iterator of [runtime.Frame]s embedded in err. If err is wrapped with WithStack or WithStackOpt, then iterator yields frames using embedded pc. If err is wrapped twice or more, then iterator yields those nested frames.
func Frames ¶ added in v0.5.0
Frames returns an iterator over runtime.Frame using pc embedded to err. The iterator yields nothing if err has not been wrapped by WithStack or WithStackOpt.
func Gather ¶ added in v0.4.0
Gather wraps errors into single error, removing nil values from errs.
If all errors are nil or len(errs) == 0, Gather returns nil.
The returned error, if not a nil, implements fmt.Formatter which prints wrapped errors using given flags and verbs. Each error is separated by ", ". If the returned error itself should be prefixed with a message, use with Prefix.
errs is retained by returned error. Callers should not mutate errs after NewMultiErrorChecked returns.
func GatherChecked ¶ added in v0.4.0
GatherChecked is like Gather but keeps nil errors in errs.
func GatherPrefixed ¶ added in v0.4.0
GatherPrefixed is like GatherChecked but also errors are prefixed by Prefix.
If ordering of errs does not matter just build errs by ToPairs.
Example ¶
ExampleGatherPrefixed shows main use case of this module.
GatherPrefixed concatenates multiple errors with prefix added to each error. GatherPrefixed returns non-nil error only when at least a single non nil error is given. It also keeps nil error in the returned error for better readability and consistency.
package main
import (
"errors"
"fmt"
"github.com/ngicks/go-common/serr"
)
func main() {
err := serr.GatherPrefixed(
serr.ToPairs(
map[string]error{
"0=": nil,
"1=": nil,
},
nil,
),
)
fmt.Printf("nil if every error is nil = %v\n", err)
err = serr.GatherPrefixed(
serr.ToPairs(
map[string]error{
"0=": errors.New("foo"),
"1=": nil,
"2=": errors.New("baz"),
},
nil,
),
)
fmt.Printf("at least a non nil error = %v\n", err)
fmt.Printf("verbs propagates = %#v\n", err)
}
Output: nil if every error is nil = <nil> at least a non nil error = 0=foo, 1=<nil>, 2=baz verbs propagates = 0=&errors.errorString{s:"foo"}, 1=<nil>, 2=&errors.errorString{s:"baz"}
func GatherUnchecked ¶ added in v0.4.0
GatherUnchecked is like Gather but keeps nil errors and always returns a non-nil error when all errs are nil or even len(errs) == 0.
func Pc ¶ added in v0.5.0
Pc retrieves slice of pc from err The slice is nil if err has not been wrapped by WithStack or WithStackOpt.
func Prefix ¶ added in v0.4.0
Prefix prefixes err with prefix. It returns nil if err is nil.
The returned error, if not a nil, implements fmt.Formatter which prints prefix and the wrapped error using given flags and verbs.
func PrefixUnchecked ¶ added in v0.4.0
PrefixUnchecked is like Prefix but always returned non nil error.
func PrintStack ¶ added in v0.5.0
PrintStack writes each stack frame information retrieved from err into w.
func UnwrapStackErr ¶ added in v0.6.0
UnwrapStackErr unwraps an error which has been wrapped with WithStack (or WithStackOpt) first found in err's chain. If the unwrapped error is also wrapped with WithStack, then functions like PrintStack works for nested stack frames.
func WithStack ¶ added in v0.5.0
WithStack adds stacktrace information to err using runtime.Callers.
WithStack wraps err only when it has not yet been wrapped. The depth of the stack trace is limited to 64. To control these behavior, use WithStackOpt.
func WithStackOpt ¶ added in v0.6.0
func WithStackOpt(err error, opt *WrapStackOpt) error
WithStackOpt is like WithStack but allows to control behavior by opt. See doc comment on WrapStackOpt for detail. Passing nil to opt works as if pointer of zero value is passed.
Types ¶
type WrapStackOpt ¶ added in v0.6.0
type WrapStackOpt struct {
// If false, [WithStackOpt] returns err without doing anything if err has already been wrapped with [WithStack] or [WithStackOpt].
// Otherwise it always wraps the error.
Override bool
// Depth defines max number of pc.
// If Depth is less than or equals to 0, it [WithStackOpt] works as if 2048 is passed.
Depth int
// Skip is passed to [runtime.Callers].
// If Skip is less than 1(skipping runtime.Callers), default value 3 is used instead.
Skip int
}
Source Files
Directories