The highest tagged major version is
README
¶
Go library to shorten handling of impossible conditions
must.OK(os.Unsetenv("FOO"))
bs := must.Bytes(json.Marshal(dataStructureDefinedInCode))
defer must.Do(f.Close)
is
if err := os.Unsetenv("FOO"); err != nil {
panic(err)
}
bs, err := json.Marshal(dataStructureDefinedInCode)
if err != nil {
panic(err)
}
defer func() {
if err := f.Close(); err != nil{
panic(err)
}
}()
Why panic?
Go error handling style is practical for majority of errors. However not all errors are meaningful and actionable by the caller, so it does not make sense to surface them.
Go tacitly acknowledges it by providing functions regex.MustCompile and
template.Must in the standard library. This library expands on the same idea.
Where is it useful?
The library is proven to be useful in the following situations:
- Programming errors in all kinds of code, similar to
regex.MustCompile, - Filesystem-related errors in a build system,
- Fatal errors in server-side SaaS code.
The last point needs an explanation.
Unlike CLI tools where errors ought to be handled in a way meaningful to a user who might not know the internals of the application, server-side SaaS applications are run by the SREs or developers who do not need the extra wrapping, and instead require fatal errors to be delivered reliably and with all gory details.
Passing errors up the stack in a regular Go way risks losing the error (by
forgetting to wrap it, or by swallowing it completely), and prevents the
original stacktrace from being surfaced. panicing at the place of fatal error
is reliable and precise.
Is it a good idea to use must everywhere?
Definitely not. Go rules for error handling are well thought-out. Reserve must
for programming errors and impossible conditions.
Legal
Copyright Tectonic Networks, Inc.
Licensed under Apache 2.0 license.
Authors:
Documentation
¶
Overview ¶
Package must is a library to shorten handling of impossible conditions
must.OK(os.Unsetenv("FOO"))
bytes := must.Bytes(json.Marshal(dataStructureDefinedInCode))
defer must.Do(f.Close)
is
if err := os.Unsetenv("FOO"); err != nil {
panic(err)
}
bytes, err := json.Marshal(dataStructureDefinedInCode)
if err != nil {
panic(err)
}
defer func() {
if err := f.Close(); err != nil{
panic(err)
}
}()
Go error handling style is practical for majority of errors. However not all errors are meaningful and actionable by the caller, so it does not make sense to surface them.
Go tacitly acknowledges it by providing functions regex.MustCompile and template.Must in the standard library. This library expands on the same idea.
Index ¶
- func Any(arg interface{}, err error) interface{}
- func BigInt(arg *big.Int, err error) *big.Int
- func Bool(arg bool, err error) bool
- func Bools(arg []bool, err error) []bool
- func Byte(arg byte, err error) byte
- func Bytes(arg []byte, err error) []byte
- func Complex128(arg complex128, err error) complex128
- func Complex128s(arg []complex128, err error) []complex128
- func Complex64(arg complex64, err error) complex64
- func Complex64s(arg []complex64, err error) []complex64
- func Do(fn func() error)
- func ECDSAPrivateKey(arg *ecdsa.PrivateKey, err error) *ecdsa.PrivateKey
- func ECDSAPublicKey(arg *ecdsa.PublicKey, err error) *ecdsa.PublicKey
- func ED25519PrivateKey(arg *ed25519.PrivateKey, err error) *ed25519.PrivateKey
- func ED25519PublicKey(arg *ed25519.PublicKey, err error) *ed25519.PublicKey
- func Float32(arg float32, err error) float32
- func Float32s(arg []float32, err error) []float32
- func Float64(arg float64, err error) float64
- func Float64s(arg []float64, err error) []float64
- func HTMLTemplate(arg *htmltemplate.Template, err error) *htmltemplate.Template
- func HTTPHandler(arg http.Handler, err error) http.Handler
- func HTTPRequest(arg *http.Request, err error) *http.Request
- func HTTPResponse(arg *http.Response, err error) *http.Response
- func HTTPTransport(arg *http.Transport, err error) *http.Transport
- func Hash(arg hash.Hash, err error) hash.Hash
- func IOReadCloser(arg io.ReadCloser, err error) io.ReadCloser
- func IOReader(arg io.Reader, err error) io.Reader
- func IOWriter(arg io.Writer, err error) io.Writer
- func Int(arg int, err error) int
- func Int16(arg int16, err error) int16
- func Int16s(arg []int16, err error) []int16
- func Int32(arg int32, err error) int32
- func Int32s(arg []int32, err error) []int32
- func Int64(arg int64, err error) int64
- func Int64s(arg []int64, err error) []int64
- func Int8(arg int8, err error) int8
- func Int8s(arg []int8, err error) []int8
- func Ints(arg []int, err error) []int
- func NetIP(arg net.IP, err error) net.IP
- func NetListener(arg net.Listener, err error) net.Listener
- func NetURL(arg *url.URL, err error) *url.URL
- func OK(err error)
- func OSFile(arg *os.File, err error) *os.File
- func OSFileInfo(arg os.FileInfo, err error) os.FileInfo
- func OSFileInfos(arg []os.FileInfo, err error) []os.FileInfo
- func RSAPrivateKey(arg *rsa.PrivateKey, err error) *rsa.PrivateKey
- func RSAPublicKey(arg *rsa.PublicKey, err error) *rsa.PublicKey
- func Rune(arg rune, err error) rune
- func Runes(arg []rune, err error) []rune
- func String(arg string, err error) string
- func Strings(arg []string, err error) []string
- func TextTemplate(arg *texttemplate.Template, err error) *texttemplate.Template
- func Time(arg time.Time, err error) time.Time
- func Uint(arg uint, err error) uint
- func Uint16(arg uint16, err error) uint16
- func Uint16s(arg []uint16, err error) []uint16
- func Uint32(arg uint32, err error) uint32
- func Uint32s(arg []uint32, err error) []uint32
- func Uint64(arg uint64, err error) uint64
- func Uint64s(arg []uint64, err error) []uint64
- func Uint8(arg uint8, err error) uint8
- func Uint8s(arg []uint8, err error) []uint8
- func Uintptr(arg uintptr, err error) uintptr
- func Uintptrs(arg []uintptr, err error) []uintptr
- func Uints(arg []uint, err error) []uint
- func X509Certificate(arg *x509.Certificate, err error) *x509.Certificate
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Any ¶
func Any(arg interface{}, err error) interface{}
Any panics on error, returns the first argument otherwise
func Complex128 ¶
func Complex128(arg complex128, err error) complex128
Complex128 panics on error, returns the first argument otherwise
func Complex128s ¶
func Complex128s(arg []complex128, err error) []complex128
Complex128s panics on error, returns the first argument otherwise
func Complex64s ¶
Complex64s panics on error, returns the first argument otherwise
func Do ¶
func Do(fn func() error)
Do calls the function and panics on error.
For use primarily in defer statements.
BAD example:
// f.Close will be called now, must.OK will be called on function exit defer must.OK(f.Close())
GOOD example:
defer must.Do(f.Close)
func ECDSAPrivateKey ¶ added in v0.5.0
func ECDSAPrivateKey(arg *ecdsa.PrivateKey, err error) *ecdsa.PrivateKey
ECDSAPrivateKey panics on error, returns the first argument otherwise
func ECDSAPublicKey ¶ added in v0.5.0
ECDSAPublicKey panics on error, returns the first argument otherwise
func ED25519PrivateKey ¶ added in v0.5.0
func ED25519PrivateKey(arg *ed25519.PrivateKey, err error) *ed25519.PrivateKey
ED25519PrivateKey panics on error, returns the first argument otherwise
func ED25519PublicKey ¶ added in v0.5.0
ED25519PublicKey panics on error, returns the first argument otherwise
func HTMLTemplate ¶ added in v0.5.0
func HTMLTemplate(arg *htmltemplate.Template, err error) *htmltemplate.Template
HTMLTemplate panics on error, returns the first argument otherwise
func HTTPHandler ¶ added in v0.4.0
HTTPHandler panics on error, returns the first argument otherwise
func HTTPRequest ¶ added in v0.3.0
HTTPRequest panics on error, returns the first argument otherwise
func HTTPResponse ¶ added in v0.5.0
HTTPResponse panics on error, returns the first argument otherwise
func HTTPTransport ¶ added in v0.5.0
HTTPTransport panics on error, returns the first argument otherwise
func IOReadCloser ¶
func IOReadCloser(arg io.ReadCloser, err error) io.ReadCloser
IOReadCloser panics on error, returns the first argument otherwise
func NetListener ¶
NetListener panics on error, returns the first argument otherwise
func OSFileInfo ¶
OSFileInfo panics on error, returns the first argument otherwise
func OSFileInfos ¶
OSFileInfos panics on error, returns the first argument otherwise
func RSAPrivateKey ¶ added in v0.5.0
func RSAPrivateKey(arg *rsa.PrivateKey, err error) *rsa.PrivateKey
RSAPrivateKey panics on error, returns the first argument otherwise
func RSAPublicKey ¶ added in v0.5.0
RSAPublicKey panics on error, returns the first argument otherwise
func TextTemplate ¶ added in v0.5.0
func TextTemplate(arg *texttemplate.Template, err error) *texttemplate.Template
TextTemplate panics on error, returns the first argument otherwise
func X509Certificate ¶ added in v0.5.0
func X509Certificate(arg *x509.Certificate, err error) *x509.Certificate
X509Certificate panics on error, returns the first argument otherwise
Types ¶
This section is empty.
Source Files
Directories