errors

Documentation

Index

• func As(err error, target any) bool
• func Is(err error, target error) bool
• func New(msg string, opts ...fudge.Option) error
• func NewWithCause(msg string, cause error, opts ...fudge.Option) error
• func Sentinel(msg string, code string) error
• func Unwrap(err error) error
• func Wrap(err error, msg string, opts ...fudge.Option) error
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Format(s fmt.State, verb rune)
  • func (e *Error) FormatCustom(visit func(message string))
  • func (e *Error) Is(target error) bool
  • func (e *Error) Unwrap() error
• type Frame
  • func (f Frame) Format(s fmt.State, verb rune)
• type KeyValues
  • func (m KeyValues) Format(s fmt.State, verb rune)

Functions

func As

func As(err error, target any) bool

As is the same as the standard library's errors.As.

func Is

func Is(err error, target error) bool

Is is the same as the standard library's errors.Is.

func New

func New(msg string, opts ...fudge.Option) error

New creates a new error with a message and options.

These errors can be used with Is to check for equality but not over gRPC. If that is required then Sentinel should be used. If used in the global scope then no stack trace is attached and these errors must be wrapped with Wrap when they are used in order to attach one.

func NewWithCause

func NewWithCause(msg string, cause error, opts ...fudge.Option) error

NewWithCause creates a new error with a message, cause and options.

This method is intended to be used when the cause is a Fudge error and you don't want to use Wrap which merges the stack trace. Most of the time you want to use Wrap.

func Sentinel

func Sentinel(msg string, code string) error

Sentinel creates a new sentinel error with a message and code.

This method is intended to be used to define global sentinel errors. These errors can be used with Is to check for equality even over gRPC (if the provided gRPC interceptors are used). No stack trace is attached and these errors must be wrapped with Wrap when they are used in order to attach one.

func Unwrap

func Unwrap(err error) error

Unwrap is the same as the standard library's errors.Unwrap.

func Wrap

func Wrap(err error, msg string, opts ...fudge.Option) error

Wrap wraps an existing error with a new message and options and the underlying cause of the error will remain unchanged.

If the error is a

• sentinel Fudge error then it is cloned and a stack trace is added.
• inline Fudge error then the stack trace is extended and/or annotated
• non-Fudge error it is converted to a Fudge error and a trace back is added and the original error is available via the Unwrap method.

Types

type Error

type Error struct {
	// Binary is the name of the executable the error occurred in
	Binary string
	// Message is the optional sentinel message (can be empty)
	Message string
	// Code is the optional sentinel error code (can be empty)
	Code string
	// Cause is the original non-Fudge error (can be nil)
	Cause error
	// Trace is the stack trace
	//
	// contextual messages and key values are attached to individual stack frames
	Trace []Frame
}

Error is a concrete error type containing a stack trace

func (*Error) Error

func (e *Error) Error() string

func (*Error) Format

func (e *Error) Format(s fmt.State, verb rune)

Format implements the fmt.Formatter interface

The following verbs are supported:

%v, %s: print the wrapping messages and error message
%+v, %+s: print the error message and stack trace with wrapping messages
%#v, %#s: print the error message and stack trace with wrapping messages and key values

func (*Error) FormatCustom

func (e *Error) FormatCustom(visit func(message string))

FormatCustom visits each frame context message in reverse order, then the primary error message and then finally the cause.

This is typically what you want to do when formatting the error in a custom way. For more complex formatting you can manually implement this function as all fields on Error are public.

func (*Error) Is

func (e *Error) Is(target error) bool

Is implements the errors.Is interface

A Fudge error is the same as another if they have the same error code. This means that you can only compare to a sentinel error.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap implements the errors.Unwrap interface and returns the original error if possible

type Frame

type Frame struct {
	// File is the file name associated with the frame
	File string
	// function is the function name associated with the frame
	Function string
	// Line is the fine number associated with the frame
	Line int
	// Message is the message associated with the frame (can be empty)
	Message string
	// KeyValues is a map of key-value pairs associated with the frame (can be nil)
	KeyValues KeyValues
}

Frame is a single frame in a stack trace

func (Frame) Format

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

type KeyValues

type KeyValues map[string]string

func (KeyValues) Format

func (m KeyValues) Format(s fmt.State, verb rune)