poop

README

💩 poop

The idea of chained or wrapped errors in Go have been around for a long time and have been in the standard library since Go 1.13. However, there seems to be some reluctance in the standard library to capturing caller information. But caller information is kind of awesome. This library is a chained error library with no such hesitation.

Status

Alpha, First Draft, Used by me and me only ... for now.

Installation

go get github.com/kellegous/poop@latest

Usage

Most common use is to simply capture the current caller and wrap an error that was produced by another call.

if err != nil {
	return poop.Chain(err)
}

To chain an and error and add a custom message to the link in the chain,

if err != nil {
	return poop.Chainf(err, "unable to fetch object id=%d", id)
}

To terminate the program due to an error,

if err != nil {
	poop.HitFan(err)
}

Documentation

Index

• Variables
• func Chain(err error) error
• func ChainWith(err error, message string) error
• func ChainWithf(err error, format string, args ...interface{}) error
• func Configure(opts ...ReportOption)
• func Flatten(err error) error
• func HitFan(err error, opts ...ReportOption)
• func IterChain(err error) iter.Seq[error]
• func New(message string) error
• func NewDefaultReporter(opts ...DefaultReporterOption) func(w io.Writer, err error) error
• func Newf(format string, args ...interface{}) error
• func OmitImportPath(f string) string
• func PathBase(path string) string
• func PathLastNSegments(n int) func(path string) string
• func WithColor(c color.Attribute) func(string) string
• type ChainedError
  • func (e *ChainedError) Error() string
  • func (e *ChainedError) Frame() Frame
  • func (e *ChainedError) Message() string
  • func (e *ChainedError) RootCause() error
  • func (e *ChainedError) Unwrap() error
• type DefaultReporterOption
  • func WithFuncFormatter(formatter FuncFormatter) DefaultReporterOption
  • func WithPathFormatter(formatter PathFormatter) DefaultReporterOption
• type DefaultReporterOptions
• type FormattedValue
• type Frame
• type FuncFormatter
  • func NewFuncFormatter(stringFn func(string) string, colorFn func(string) string) FuncFormatter
• type PathFormatter
  • func NewPathFormatter(pathStringFn func(string) string, lineStringFn func(int) string, ...) PathFormatter
• type ReportOption
  • func ExitWithStatus(status int) ReportOption
  • func Panic() ReportOption
  • func UsingReporter(reporter Reporter) ReportOption
• type ReportOptions
• type Reporter
• type SHTF
  • func BeReady(opts ...ReportOption) SHTF

Variables

var DefaultReporter = NewDefaultReporter()

DefaultReporter is the default reporter that is used when no reporter is provided.

Functions

func Chain

func Chain(err error) error

Chain chains the given error. This is the most common way to chain. It captures the caller information, the location where this error is being returned, but doesn't require any other information.

func ChainWith

func ChainWith(err error, message string) error

ChainWith chains the given error with an additional message.

func ChainWithf

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

ChainWithf is identical to ChainWith, but allows formatted messages.

func Configure

func Configure(opts ...ReportOption)

Configure modifies the default reporting options changing the global default behavior of HitFan. This is intended for 1-time configuration in main.

func Flatten

func Flatten(err error) error

Flatten flattens the chain into a single error with the information about the chain in the error message. This is useful in contexts where you need to capture everyting in the string returned via Error, like zap logging, zap.Error(poop.Flatten(err)).

func HitFan

func HitFan(err error, opts ...ReportOption)

HitFan reports the given error and then terminates the program using the report options to control how the error is reported and the mechanism by which the program is terminated.

func IterChain

func IterChain(err error) iter.Seq[error]

IterChain is an iterator of all the errors in the chain.

TODO(kellegous): Since ChainError is not exported, this should be changed to a method on ChainedError.

func New

func New(message string) error

New creates a leaf error with caller information. This is the poop equivalent to `errors.New`.

func NewDefaultReporter

func NewDefaultReporter(opts ...DefaultReporterOption) func(w io.Writer, err error) error

NewDefaultReporter creates a new default reporter with the given options.

func Newf

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

Newf is identical to New, but allows formatted messages.

func OmitImportPath

func OmitImportPath(f string) string

OmitImportPath returns the last segment of the given function name.

func PathBase

func PathBase(path string) string

PathBase returns the base name of the given path.

func PathLastNSegments

func PathLastNSegments(n int) func(path string) string

PathLastNSegments returns a function that returns the last n segments of the given path.

func WithColor

func WithColor(c color.Attribute) func(string) string

WithColor creates a new color function that wraps the given color attribute.

Types

type ChainedError

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

ChainedError represents a link in the causal chain of errors.

func (*ChainedError) Error

func (e *ChainedError) Error() string

func (*ChainedError) Frame

func (e *ChainedError) Frame() Frame

Frame returns the frame information for the caller of the error. This will be the call frame for the chain link.

func (*ChainedError) Message

func (e *ChainedError) Message() string

Message returns the message that was provided when the error was chained. The message is optional and may be empty.

func (*ChainedError) RootCause

func (e *ChainedError) RootCause() error

RootCause returns the first error in the chain.

func (*ChainedError) Unwrap

func (e *ChainedError) Unwrap() error

type DefaultReporterOption

type DefaultReporterOption func(*DefaultReporterOptions)

DefaultReporterOption is a function that modifies the default reporter options.

func WithFuncFormatter

func WithFuncFormatter(formatter FuncFormatter) DefaultReporterOption

WithFuncFormatter sets the function formatter for the default reporter.

func WithPathFormatter

func WithPathFormatter(formatter PathFormatter) DefaultReporterOption

WithPathFormatter sets the path formatter for the default reporter.

type DefaultReporterOptions

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

DefaultReporterOptions is the options for the default reporter.

type FormattedValue

type FormattedValue interface {
	// Format returns the colored, formatted value.
	Format() string

	// Width returns the character width of the value.
	// TODO(kellegous): This doesn't take into account
	// glyphs that are multi-byte but display as a single
	// character.
	Width() int
}

type Frame

type Frame struct {
	Function string
	File     string
	Line     int
}

type FuncFormatter

type FuncFormatter func(function string) FormattedValue

FuncFormatter formats a function name into a formatted value.

func NewFuncFormatter

func NewFuncFormatter(
	stringFn func(string) string,
	colorFn func(string) string,
) FuncFormatter

NewFuncFormatter creates a new FuncFormatter that formats a function name into a formatted value.

type PathFormatter

type PathFormatter func(path string, line int) FormattedValue

PathFormatter formats a path and line number into a formatted value.

func NewPathFormatter

func NewPathFormatter(
	pathStringFn func(string) string,
	lineStringFn func(int) string,
	lineColorFn func(string) string,
	pathColorFn func(string) string,
) PathFormatter

NewPathFormatter creates a new PathFormatter that formats a path and line number into a formatted value.

type ReportOption

type ReportOption func(*ReportOptions)

func ExitWithStatus

func ExitWithStatus(status int) ReportOption

func Panic

func Panic() ReportOption

func UsingReporter

func UsingReporter(reporter Reporter) ReportOption

type ReportOptions

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

type Reporter

type Reporter func(w io.Writer, err error) error

type SHTF

type SHTF interface {
	HitFan(err error)
}

func BeReady

func BeReady(opts ...ReportOption) SHTF

BeReady creates a new SHTF instance with the given options. This allows for the creation of customized reporting behavior in a specific area of code, without affecting the global default behavior.