README
¶
relay
go get github.com/codemodus/relay
Package relay provides a simple mechanism for relaying control flow based upon whether a checked error is nil or not.
Usage
func CodedFns(handler ...func(error)) (CodedCheckFunc, CodedTripFunc)
func DefaultHandler() func(error)
func Fns(handler ...func(error)) (CheckFunc, TripFunc)
func Handle()
type CheckFunc
type CodedCheckFunc
type CodedError
func (ce *CodedError) Error() string
func (ce *CodedError) ExitCode() int
type CodedTripFunc
func CodedTripFn(ck CodedCheckFunc) CodedTripFunc
type ExitCoder
type Relay
func New(handler ...func(error)) *Relay
func (r *Relay) Check(err error)
func (r *Relay) CodedCheck(code int, err error)
type TripFunc
func TripFn(ck CheckFunc) TripFunc
Setup
import (
"github.com/codemodus/relay"
)
func main() {
r := relay.New()
defer relay.Handle()
err := fail()
r.Check(err)
// prints "{cmd_name}: {err_msg}" to stderr
// calls os.Exit with code set as 1
}
Setup (Custom Handler)
h := func(err error) {
fmt.Println(err)
fmt.Println("extra message")
}
r := relay.New(h)
defer relay.Handle()
err := fail()
r.Check(err)
fmt.Println("should not print")
// Output:
// always fails
// extra message
Setup (Eased Usage)
ck := relay.New().Check
defer relay.Handle()
err := fail()
ck(err)
// prints "{cmd_name}: {err_msg}" to stderr
// calls os.Exit with code set as 1
Setup (Coded Check)
ck := relay.New().CodedCheck
defer relay.Handle()
err := fail()
ck(3, err)
// prints "{cmd_name}: {err_msg}" to stderr
// calls os.Exit with code set as first arg to r.CodedCheck ("ck")
Setup (Trip Function)
ck := relay.New().Check
trip := relay.TripFn(ck)
defer relay.Handle()
n := three()
if n != 2 {
trip("must receive %v: %v is invalid", 2, n)
}
fmt.Println("should not print")
// prints "{cmd_name}: {trip_msg}" to stderr
// calls os.Exit with code set as 1
Setup (Eased Usage - Check and Trip)
ck, trip := relay.Fns()
defer relay.Handle()
err := mightFail()
ck(err)
n := three()
if n != 2 {
trip("must receive %v: %v is invalid", 2, n)
}
fmt.Println("should not print")
// prints "{cmd_name}: {trip_msg}" to stderr
// calls os.Exit with code set as 1
More Info
Background
https://github.com/golang/go/issues/32437#issuecomment-510214015
Documentation
View the GoDoc
Benchmarks
N/A
Documentation
¶
Overview ¶
Package relay provides a simple mechanism for relaying control flow based upon whether a checked error is nil or not.
Example ¶
package main
import (
"errors"
"github.com/codemodus/relay"
)
func main() {
r := relay.New()
defer relay.Handle()
err := fail()
r.Check(err)
// prints "{cmd_name}: {err_msg}" to stderr
// calls os.Exit with code set as 1
}
func fail() error {
return errors.New("always fails")
}
Output:
Example (CustomHandler) ¶
Override default error handler.
package main
import (
"errors"
"fmt"
"github.com/codemodus/relay"
)
func main() {
h := func(err error) {
fmt.Println(err)
fmt.Println("extra message")
}
r := relay.New(h)
defer relay.Handle()
err := fail()
r.Check(err)
fmt.Println("should not print")
}
func fail() error {
return errors.New("always fails")
}
Output: always fails extra message
Example (EasedUsage) ¶
Store check method for convenience.
package main
import (
"errors"
"github.com/codemodus/relay"
)
func main() {
ck := relay.New().Check
defer relay.Handle()
err := fail()
ck(err)
// prints "{cmd_name}: {err_msg}" to stderr
// calls os.Exit with code set as 1
}
func fail() error {
return errors.New("always fails")
}
Output:
Example (ExitCode) ¶
package main
import (
"errors"
"github.com/codemodus/relay"
)
func main() {
ck := relay.New().CodedCheck
defer relay.Handle()
err := fail()
ck(3, err)
// prints "{cmd_name}: {err_msg}" to stderr
// calls os.Exit with code set as first arg to r.CodedCheck ("ck")
}
func fail() error {
return errors.New("always fails")
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CodedFns ¶
func CodedFns(handler ...func(error)) (CodedCheckFunc, CodedTripFunc)
CodedFns setups a new Relay and returns both a CodedCheckFunc and CodedTripFunc or caller convenience.
Example ¶
package main
import (
"fmt"
"github.com/codemodus/relay"
)
func main() {
ck, trip := relay.CodedFns()
defer relay.Handle()
err := mightFail()
ck(3, err)
n := three()
if n != 2 {
trip(4, "must receive %v: %v is invalid", 2, n)
}
fmt.Println("should not print")
// prints "{cmd_name}: {trip_msg}" to stderr
// calls os.Exit with code set as first arg to "trip"
}
func three() int {
return 3
}
func mightFail() error {
return nil
}
Output:
func DefaultHandler ¶
func DefaultHandler() func(error)
DefaultHandler returns an error handler that prints "{cmd_name}: {err_msg}" to stderr and then call os.Exit. If the handled error happens to satisfy the ExitCoder interface, that value will be used as the exit code. Otherwise, 1 will be used.
func Fns ¶
Fns setups a new Relay and returns both a CheckFunc and TripFunc for caller convenience.
Example ¶
package main
import (
"fmt"
"github.com/codemodus/relay"
)
func main() {
ck, trip := relay.Fns()
defer relay.Handle()
err := mightFail()
ck(err)
n := three()
if n != 2 {
trip("must receive %v: %v is invalid", 2, n)
}
fmt.Println("should not print")
// prints "{cmd_name}: {trip_msg}" to stderr
// calls os.Exit with code set as 1
}
func three() int {
return 3
}
func mightFail() error {
return nil
}
Output:
Types ¶
type CheckFunc ¶
type CheckFunc func(err error)
CheckFunc implementations should verify if an error is not nil.
type CodedCheckFunc ¶
CodedCheckFunc implementations should verify if an error is not nil, and pass through an exit code via wrapping error to final handling.
type CodedError ¶
CodedError is a simple implementaion of the ExitCoder interface.
func (*CodedError) Error ¶
func (ce *CodedError) Error() string
Error satisfies the error interface.
func (*CodedError) ExitCode ¶
func (ce *CodedError) ExitCode() int
ExitCode satisfies the ExitCoder interface.
type CodedTripFunc ¶
TripFunc implementations should immediately set off final handling using the format and optional args provided, and pass through an exit code via wrapping error.
func CodedTripFn ¶
func CodedTripFn(ck CodedCheckFunc) CodedTripFunc
CodedTripFn wraps the provided CodedCheckFunc so that it is a CodedTripFunc.
Example ¶
package main
import (
"fmt"
"github.com/codemodus/relay"
)
func main() {
ck := relay.New().CodedCheck
trip := relay.CodedTripFn(ck)
defer relay.Handle()
n := three()
if n != 2 {
trip(4, "must receive %v: %v is invalid", 2, n)
}
fmt.Println("should not print")
// prints "{cmd_name}: {trip_msg}" to stderr
// calls os.Exit with code set as first arg to "trip"
}
func three() int {
return 3
}
Output:
type ExitCoder ¶
type ExitCoder interface {
ExitCode() int
}
ExitCoder describes any type that can return an error code.
type Relay ¶
type Relay struct {
// contains filtered or unexported fields
}
Relay tracks an error and a related error handler.
func (*Relay) Check ¶
Check will do nothing if the error argument is nil. Otherwise, it kicks-off an event (i.e. the relay is "tripped") and should be handled by a deferred call to Handle().
func (*Relay) CodedCheck ¶
CodedCheck will do nothing if the error argument is nil. Otherwise, it kicks-off an event (i.e. the relay is "tripped") and should be handled by a deferred call to Handle(). Any provided error will be wrapped in a codedError instance in order to trigger special behavior in the default error handler.
type TripFunc ¶
type TripFunc func(format string, args ...interface{})
TripFunc implementations should immediately set off final handling using the format and optional args provided.
func TripFn ¶
TripFn wraps the provided CheckFunc so that it is a TripFunc.
Example ¶
package main
import (
"fmt"
"github.com/codemodus/relay"
)
func main() {
ck := relay.New().Check
trip := relay.TripFn(ck)
defer relay.Handle()
n := three()
if n != 2 {
trip("must receive %v: %v is invalid", 2, n)
}
fmt.Println("should not print")
// prints "{cmd_name}: {trip_msg}" to stderr
// calls os.Exit with code set as 1
}
func three() int {
return 3
}
Output:
Source Files