errmark

Documentation

Index

• Variables
• func If(err error, rule Rule, fn func(err error))
• func IfMarked(err error, m *Marker, fn func(err error))
• func Mark(err error, m *Marker) error
• func MarkIf(err error, m *Marker, rule Rule) error
• func MarkShort(err error) error
• func MarkShortIf(err error, rule Rule) error
• func MarkTransient(err error) error
• func MarkTransientIf(err error, rule Rule) error
• func MarkUser(err error) error
• func MarkUserIf(err error, rule Rule) error
• func Marked(err error, m *Marker) bool
• func MarkedShort(err error) bool
• func MarkedTransient(err error) bool
• func MarkedUser(err error) bool
• func Matches(err error, rule Rule) bool
• func Unless(err error, rule Rule, fn func(err error))
• func UnlessMarked(err error, m *Marker, fn func(err error))
• type Marker
  • func NewMarker(name string) *Marker
  • func (m *Marker) Name() string
• type MarkerSet
  • func Markers(err error) *MarkerSet
  • func NewMarkerSet(values ...*Marker) *MarkerSet
  • func (ms *MarkerSet) Has(m *Marker) bool
  • func (ms *MarkerSet) Merge(other *MarkerSet) *MarkerSet
  • func (ms *MarkerSet) Names() []string
• type Rule
  • func RuleAll(rules ...Rule) Rule
  • func RuleAny(rules ...Rule) Rule
  • func RuleExact(want error) Rule
  • func RuleIs(want error) Rule
  • func RuleMarked(m *Marker) Rule
  • func RuleNot(delegate Rule) Rule
  • func RulePredicate(delegate Rule, when func() bool) Rule
  • func RuleType(want interface{}) Rule
• type RuleFunc
  • func (rf RuleFunc) Matches(err error) bool

Variables

var (
	// Short is a Marker for indicating that the representation of an error
	// should be abbreviated. In the case of this package, an error marked Short
	// will have the marker prefixes elided from the error message.
	Short = NewMarker("short")

	// RuleMarkedShort is a Rule that matches an error if that error has been
	// marked Short.
	RuleMarkedShort = RuleMarked(Short)
)

var (
	// Transient is a Marker for indicating that a given error is temporary in
	// nature. This is typically used to ask a client to retry work in the
	// future.
	Transient = NewMarker("transient")

	// RuleMarkedTransient is a Rule that matches an error if that error has
	// been marked Transient.
	RuleMarkedTransient = RuleMarked(Transient)
)

var (
	// User is a Marker for indicating that an error was caused by user action
	// and not by a system error. It is typically used to ask a user to change
	// application input to remedy the problem.
	User = NewMarker("user")

	// RuleMarkedUser is a Rule that matches an error if the error has been
	// marked as a user error.
	RuleMarkedUser = RuleMarked(User)
)

var RuleAlways = RuleAll()

RuleAlways succeeds against every error.

var RuleNever = RuleAny()

RuleNever fails against every error.

Functions

func If

func If(err error, rule Rule, fn func(err error))

If runs a callback function if the given Rule matches the error.

func IfMarked

func IfMarked(err error, m *Marker, fn func(err error))

IfMarked runs a callback function if the error is marked with the given Marker.

func Mark

func Mark(err error, m *Marker) error

Mark marks an error with a particular Marker.

func MarkIf

func MarkIf(err error, m *Marker, rule Rule) error

MarkIf marks an error with a particular Marker if the given Rule matches the error.

func MarkShort

func MarkShort(err error) error

MarkShort marks an error as short.

func MarkShortIf

func MarkShortIf(err error, rule Rule) error

MarkShortIf marks an error as short if the error matches the given Rule.

func MarkTransient

func MarkTransient(err error) error

MarkTransient marks an error as transient.

func MarkTransientIf

func MarkTransientIf(err error, rule Rule) error

MarkTransientIf marks an error as transient if the error matches the given Rule.

func MarkUser

func MarkUser(err error) error

MarkUser marks an error as a user error.

func MarkUserIf

func MarkUserIf(err error, rule Rule) error

MarkUserIf marks an error as a user error if the error matches the given Rule.

func Marked

func Marked(err error, m *Marker) bool

Marked returns true if the given error has had a particular Marker applied.

func MarkedShort

func MarkedShort(err error) bool

MarkedShort returns true if the given error has been marked short.

func MarkedTransient

func MarkedTransient(err error) bool

MarkedTransient returns true if the given error has been marked transient.

func MarkedUser

func MarkedUser(err error) bool

MarkedUser returns true if the given error has been marked as a user error.

func Matches

func Matches(err error, rule Rule) bool

Matches returns true if the given Rule matches the error.

func Unless

func Unless(err error, rule Rule, fn func(err error))

Unless runs a callback function if the given Rule does not match the error.

func UnlessMarked

func UnlessMarked(err error, m *Marker, fn func(err error))

UnlessMarked runs a callback function if the error is not marked with the given Marker.

Types

type Marker

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

Marker represents a named identifier that logically groups one or more arbitrary errors.

Note that Markers are intentionally not comparable by value, that is, NewMarker("foo") != NewMarker("foo"). Markers should generally be declared in package scope.

func NewMarker

func NewMarker(name string) *Marker

NewMarker creates a Marker with the given name.

func (*Marker) Name

func (m *Marker) Name() string

Name returns the supplied name of this marker.

type MarkerSet

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

MarkerSet is a unique collection of Markers.

func Markers

func Markers(err error) *MarkerSet

Markers returns a set of all the markers that are present on the given error.

func NewMarkerSet

func NewMarkerSet(values ...*Marker) *MarkerSet

NewMarkerSet creates a collection of Markers with the given values after deduplicating.

It is valid to work with nil values of *MarkerSet. All methods of the struct check for a nil receiver first.

func (*MarkerSet) Has

func (ms *MarkerSet) Has(m *Marker) bool

Has tests whether this MarkerSet contains the given Marker.

func (*MarkerSet) Merge

func (ms *MarkerSet) Merge(other *MarkerSet) *MarkerSet

Merge combines one MarkerSet with another, retaining only unique Markers. A new MarkerSet is returned (unless either this MarkerSet or the other MarkerSet are empty, in which case the non-empty set is returned directly).

func (*MarkerSet) Names

func (ms *MarkerSet) Names() []string

Names returns a list of names of each unique Marker in this collection in the order they were added to the collection.

type Rule

type Rule interface {
	Matches(err error) bool
}

Rule tests an error against an arbitrary condition.

It is useful for deciding when an error should be marked with a given Marker.

func RuleAll

func RuleAll(rules ...Rule) Rule

RuleAll applies several rules in sequence. If one of the rules returns false, this rule also returns false. Otherwise, this rule returns true.

func RuleAny

func RuleAny(rules ...Rule) Rule

RuleAny applies several rules in sequence. If one of the rules returns true, this rule also returns true. Otherwise, this rule returns false.

func RuleExact

func RuleExact(want error) Rule

RuleExact matches an error if it is exactly the wanted error.

func RuleIs

func RuleIs(want error) Rule

RuleIs matches an error if errors.Is() would return true for the wanted error.

func RuleMarked

func RuleMarked(m *Marker) Rule

RuleMarked matches an error if the error has been marked with the given Marker.

func RuleNot

func RuleNot(delegate Rule) Rule

RuleNot inverts the result of a delegate rule.

func RulePredicate

func RulePredicate(delegate Rule, when func() bool) Rule

RulePredicate evalutes a delegate rule when a predicate is satisfied at the time an error is passed to the rule. It returns false if the predicate is not satisfied.

func RuleType

func RuleType(want interface{}) Rule

RuleType matches an error if errors.As() would return true for a target of a pointer to the type given.

type RuleFunc

type RuleFunc func(err error) bool

RuleFunc allows a function to be used as a Rule.

func (RuleFunc) Matches

func (rf RuleFunc) Matches(err error) bool