gitea/vendor/gopkg.in/warnings.v0/warnings.go

195 lines
5.4 KiB
Go
Raw Normal View History

// Package warnings implements error handling with non-fatal errors (warnings).
//
// A recurring pattern in Go programming is the following:
//
// func myfunc(params) error {
// if err := doSomething(...); err != nil {
// return err
// }
// if err := doSomethingElse(...); err != nil {
// return err
// }
// if ok := doAnotherThing(...); !ok {
// return errors.New("my error")
// }
// ...
// return nil
// }
//
// This pattern allows interrupting the flow on any received error. But what if
// there are errors that should be noted but still not fatal, for which the flow
// should not be interrupted? Implementing such logic at each if statement would
// make the code complex and the flow much harder to follow.
//
// Package warnings provides the Collector type and a clean and simple pattern
// for achieving such logic. The Collector takes care of deciding when to break
// the flow and when to continue, collecting any non-fatal errors (warnings)
// along the way. The only requirement is that fatal and non-fatal errors can be
// distinguished programmatically; that is a function such as
//
// IsFatal(error) bool
//
// must be implemented. The following is an example of what the above snippet
// could look like using the warnings package:
//
// import "gopkg.in/warnings.v0"
//
// func isFatal(err error) bool {
// _, ok := err.(WarningType)
// return !ok
// }
//
// func myfunc(params) error {
// c := warnings.NewCollector(isFatal)
// c.FatalWithWarnings = true
// if err := c.Collect(doSomething()); err != nil {
// return err
// }
// if err := c.Collect(doSomethingElse(...)); err != nil {
// return err
// }
// if ok := doAnotherThing(...); !ok {
// if err := c.Collect(errors.New("my error")); err != nil {
// return err
// }
// }
// ...
// return c.Done()
// }
//
// For an example of a non-trivial code base using this library, see
// gopkg.in/gcfg.v1
//
// Rules for using warnings
//
// - ensure that warnings are programmatically distinguishable from fatal
// errors (i.e. implement an isFatal function and any necessary error types)
// - ensure that there is a single Collector instance for a call of each
// exported function
// - ensure that all errors (fatal or warning) are fed through Collect
// - ensure that every time an error is returned, it is one returned by a
// Collector (from Collect or Done)
// - ensure that Collect is never called after Done
//
// TODO
//
// - optionally limit the number of warnings (e.g. stop after 20 warnings) (?)
// - consider interaction with contexts
// - go vet-style invocations verifier
// - semi-automatic code converter
//
package warnings // import "gopkg.in/warnings.v0"
import (
"bytes"
"fmt"
)
// List holds a collection of warnings and optionally one fatal error.
type List struct {
Warnings []error
Fatal error
}
// Error implements the error interface.
func (l List) Error() string {
b := bytes.NewBuffer(nil)
if l.Fatal != nil {
fmt.Fprintln(b, "fatal:")
fmt.Fprintln(b, l.Fatal)
}
switch len(l.Warnings) {
case 0:
// nop
case 1:
fmt.Fprintln(b, "warning:")
default:
fmt.Fprintln(b, "warnings:")
}
for _, err := range l.Warnings {
fmt.Fprintln(b, err)
}
return b.String()
}
// A Collector collects errors up to the first fatal error.
type Collector struct {
// IsFatal distinguishes between warnings and fatal errors.
IsFatal func(error) bool
// FatalWithWarnings set to true means that a fatal error is returned as
// a List together with all warnings so far. The default behavior is to
// only return the fatal error and discard any warnings that have been
// collected.
FatalWithWarnings bool
l List
done bool
}
// NewCollector returns a new Collector; it uses isFatal to distinguish between
// warnings and fatal errors.
func NewCollector(isFatal func(error) bool) *Collector {
return &Collector{IsFatal: isFatal}
}
// Collect collects a single error (warning or fatal). It returns nil if
// collection can continue (only warnings so far), or otherwise the errors
// collected. Collect mustn't be called after the first fatal error or after
// Done has been called.
func (c *Collector) Collect(err error) error {
if c.done {
panic("warnings.Collector already done")
}
if err == nil {
return nil
}
if c.IsFatal(err) {
c.done = true
c.l.Fatal = err
} else {
c.l.Warnings = append(c.l.Warnings, err)
}
if c.l.Fatal != nil {
return c.erorr()
}
return nil
}
// Done ends collection and returns the collected error(s).
func (c *Collector) Done() error {
c.done = true
return c.erorr()
}
func (c *Collector) erorr() error {
if !c.FatalWithWarnings && c.l.Fatal != nil {
return c.l.Fatal
}
if c.l.Fatal == nil && len(c.l.Warnings) == 0 {
return nil
}
// Note that a single warning is also returned as a List. This is to make it
// easier to determine fatal-ness of the returned error.
return c.l
}
// FatalOnly returns the fatal error, if any, **in an error returned by a
// Collector**. It returns nil if and only if err is nil or err is a List
// with err.Fatal == nil.
func FatalOnly(err error) error {
l, ok := err.(List)
if !ok {
return err
}
return l.Fatal
}
// WarningsOnly returns the warnings **in an error returned by a Collector**.
func WarningsOnly(err error) []error {
l, ok := err.(List)
if !ok {
return nil
}
return l.Warnings
}