gperr

README

gperr

gperr is an error interface that supports nested structure and subject highlighting.

Usage

gperr.Error

The error interface.

gperr.New

Like errors.New, but returns a gperr.Error.

gperr.Wrap

Like fmt.Errorf("%s: %w", message, err), but returns a gperr.Error.

gperr.Error.Subject

Returns a new error with the subject prepended to the error message. The main subject is highlighted.

err := gperr.New("error message")
err = err.Subject("bar")
err = err.Subject("foo")

Output:

foo > bar: error message

gperr.Error.Subjectf

Like gperr.Error.Subject, but formats the subject with fmt.Sprintf.

gperr.PrependSubject

Prepends the subject to the error message like gperr.Error.Subject.

err := gperr.New("error message")
err = gperr.PrependSubject(err, "foo")
err = gperr.PrependSubject(err, "bar")

Output:

bar > foo: error message

gperr.Error.With

Adds a new error to the error chain.

err := gperr.New("error message")
err = err.With(gperr.New("inner error"))
err = err.With(gperr.New("inner error 2").With(gperr.New("inner inner error")))

Output:

error message:
  • inner error
  • inner error 2
    • inner inner error

gperr.Error.Withf

Like gperr.Error.With, but formats the error with fmt.Errorf.

gperr.Error.Is

Returns true if the error is equal to the given error.

gperr.Builder

A builder for gperr.Error.

builder := gperr.NewBuilder("foo")
builder.Add(gperr.New("error message"))
builder.Addf("error message: %s", "foo")
builder.AddRange(gperr.New("error message 1"), gperr.New("error message 2"))

Output:

foo:
  • error message
  • error message: foo
  • error message 1
  • error message 2

gperr.Builder.Build

Builds a gperr.Error from the builder.

When to return gperr.Error

• When you want to return multiple errors
• When the error has a subject

Documentation

Index

• func Collect[T any, Err error, Arg any, Func func(Arg) (T, Err)](eb *Builder, fn Func, arg Arg) T
• func IsJSONMarshallable(err error) bool
• func LogDebug(msg string, err error, logger ...*zerolog.Logger)
• func LogError(msg string, err error, logger ...*zerolog.Logger)
• func LogFatal(msg string, err error, logger ...*zerolog.Logger)
• func LogPanic(msg string, err error, logger ...*zerolog.Logger)
• func LogWarn(msg string, err error, logger ...*zerolog.Logger)
• func PrependSubject(subject string, err error) error
• type Builder
  • func NewBuilder(about ...string) *Builder
  • func NewBuilderWithConcurrency(about ...string) *Builder
  • func (b *Builder) About() string
  • func (b *Builder) Add(err error)
  • func (b *Builder) AddFrom(other *Builder, flatten bool)
  • func (b *Builder) AddRange(errs ...error)
  • func (b *Builder) Addf(format string, args ...any)
  • func (b *Builder) Adds(err string)
  • func (b *Builder) EnableConcurrency()
  • func (b *Builder) Error() Error
  • func (b *Builder) ForEach(fn func(error))
  • func (b *Builder) HasError() bool
  • func (b *Builder) String() string
• type Error
  • func Errorf(format string, args ...any) Error
  • func Join(errors ...error) Error
  • func New(message string) Error
  • func Unwrap(err error) Error
  • func Wrap(err error, message ...string) Error
• type MultilineError
  • func Multiline() *MultilineError
  • func (m *MultilineError) AddLines(lines ...any) *MultilineError
  • func (m *MultilineError) Addf(format string, args ...any) *MultilineError
  • func (m *MultilineError) Adds(s string) *MultilineError
  • func (err *MultilineError) Error() string
  • func (err *MultilineError) Is(other error) bool
  • func (err MultilineError) Subject(subject string) Error
  • func (err *MultilineError) Subjectf(format string, args ...any) Error
  • func (err *MultilineError) Unwrap() []error
  • func (err MultilineError) With(extra error) Error
  • func (err MultilineError) Withf(format string, args ...any) Error

Functions

func Collect

func Collect[T any, Err error, Arg any, Func func(Arg) (T, Err)](eb *Builder, fn Func, arg Arg) T

func IsJSONMarshallable

func IsJSONMarshallable(err error) bool

func LogDebug

func LogDebug(msg string, err error, logger ...*zerolog.Logger)

func LogError

func LogError(msg string, err error, logger ...*zerolog.Logger)

func LogFatal

func LogFatal(msg string, err error, logger ...*zerolog.Logger)

func LogPanic

func LogPanic(msg string, err error, logger ...*zerolog.Logger)

func LogWarn

func LogWarn(msg string, err error, logger ...*zerolog.Logger)

func PrependSubject

func PrependSubject(subject string, err error) error

Types

type Builder

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

func NewBuilder

func NewBuilder(about ...string) *Builder

NewBuilder creates a new Builder.

If about is not provided, the Builder will not have a subject and will expand when adding to another builder.

func NewBuilderWithConcurrency

func NewBuilderWithConcurrency(about ...string) *Builder

func (*Builder) About

func (b *Builder) About() string

func (*Builder) Add

func (b *Builder) Add(err error)

Add adds an error to the Builder.

adding nil is no-op.

func (*Builder) AddFrom

func (b *Builder) AddFrom(other *Builder, flatten bool)

func (*Builder) AddRange

func (b *Builder) AddRange(errs ...error)

func (*Builder) Addf

func (b *Builder) Addf(format string, args ...any)

func (*Builder) Adds

func (b *Builder) Adds(err string)

func (*Builder) EnableConcurrency

func (b *Builder) EnableConcurrency()

func (*Builder) Error

func (b *Builder) Error() Error

func (*Builder) ForEach

func (b *Builder) ForEach(fn func(error))

func (*Builder) HasError

func (b *Builder) HasError() bool

func (*Builder) String

func (b *Builder) String() string

type Error

type Error interface {
	error

	// Is is a wrapper for errors.Is when there is no sub-error.
	//
	// When there are sub-errors, they will also be checked.
	Is(other error) bool
	// With appends a sub-error to the error.
	With(extra error) Error
	// Withf is a wrapper for With(fmt.Errorf(format, args...)).
	Withf(format string, args ...any) Error
	// Subject prepends the given subject with a colon and space to the error message.
	//
	// If there is already a subject in the error message, the subject will be
	// prepended to the existing subject with " > ".
	//
	// Subject empty string is ignored.
	Subject(subject string) Error
	// Subjectf is a wrapper for Subject(fmt.Sprintf(format, args...)).
	Subjectf(format string, args ...any) Error
}

func Errorf

func Errorf(format string, args ...any) Error

func Join

func Join(errors ...error) Error

func New

func New(message string) Error

func Unwrap

func Unwrap(err error) Error

func Wrap

func Wrap(err error, message ...string) Error

Wrap wraps message in front of the error message.

type MultilineError

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

func Multiline

func Multiline() *MultilineError

func (*MultilineError) AddLines

func (m *MultilineError) AddLines(lines ...any) *MultilineError

func (*MultilineError) Addf

func (m *MultilineError) Addf(format string, args ...any) *MultilineError

func (*MultilineError) Adds

func (m *MultilineError) Adds(s string) *MultilineError

func (*MultilineError) Error

func (err *MultilineError) Error() string

func (*MultilineError) Is

func (err *MultilineError) Is(other error) bool

func (MultilineError) Subject

func (err MultilineError) Subject(subject string) Error

func (*MultilineError) Subjectf

func (err *MultilineError) Subjectf(format string, args ...any) Error

func (*MultilineError) Unwrap

func (err *MultilineError) Unwrap() []error

func (MultilineError) With

func (err MultilineError) With(extra error) Error

func (MultilineError) Withf

func (err MultilineError) Withf(format string, args ...any) Error