must

Documentation

Overview

Package must provides a handful of functions to express fatal assertions in Go programs. It is meant to alleviate cumbersome error handling and reporting when the only course of action is to fail the program. Package must is intended to be used by top-level binaries (i.e., in main packages); it should rarely be used elsewhere.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/grailbio/base/must"
)

func main() {
	must.Func = func(depth int, v ...interface{}) {
		fmt.Print(v...)
		fmt.Print("\n")
	}

	must.Nil(errors.New("unexpected condition"))
	must.Nil(nil)
	must.Nil(errors.New("some error"))
	must.Nil(errors.New("i/o error"), "reading file")

	must.True(false)
	must.True(true, "something happened")
	must.True(false, "a condition failed")

}

Output:

unexpected condition
some error
reading file: i/o error
must: assertion failed
a condition failed

Index

• Variables
• func Never(v ...interface{})
• func Neverf(format string, v ...interface{})
• func Nil(v interface{}, args ...interface{})
• func Nilf(v interface{}, format string, args ...interface{})
• func True(b bool, v ...interface{})
• func Truef(x bool, format string, v ...interface{})

Examples

• Package

Variables

var Func func(int, ...interface{}) = func(depth int, v ...interface{}) {
	s := fmt.Sprint(v...)

	_ = log.Output(depth+1, log.Error, s)
	panic(s)
}

Func is the function called to report an error and interrupt execution. Func is typically set to a function that logs the message and halts execution, e.g. by panicking. It should be set before any potential calls to functions in the must package. Func is passed the call depth of the caller of the must function, e.g. the caller of Nil. This can be used to annotate messages.

The default implementation logs the message with github.com/grailbio/base/log at the Error level and then panics.

Functions

func Never

func Never(v ...interface{})

Never asserts that it is never called. If it is, it formats a message in the manner of fmt.Sprint and calls Func.

func Neverf

func Neverf(format string, v ...interface{})

Neverf asserts that it is never called. If it is, it formats a message in the manner of fmt.Sprintf and calls Func.

func Nil

func Nil(v interface{}, args ...interface{})

Nil asserts that v is nil; v is typically a value of type error. If v is not nil, Nil formats a message in hte manner of fmt.Sprint and calls must.Func. Nil also suffixes the message with the fmt.Sprint-formatted value of v.

func Nilf

func Nilf(v interface{}, format string, args ...interface{})

Nilf asserts that v is nil; v is typically a value of type error. If v is not nil, Nilf formats a message in hte manner of fmt.Sprintf and calls must.Func. Nilf also suffixes the message with the fmt.Sprint-formatted value of v.

func True

func True(b bool, v ...interface{})

True is a no-op if the value b is true. If it is false, True formats a message in the manner of fmt.Sprint and calls Func.

func Truef

func Truef(x bool, format string, v ...interface{})

Truef is a no-op if the value b is true. If it is false, True formats a message in the manner of fmt.Sprintf and calls Func.