Documentation
¶
Overview ¶
This package writes error messages in the conventional format
<Program-Name>: <Sprintf-output><newline>
or the slightly less conventional format
<Program> <Tag>: <Sprintf-output><newline>
where the tag can be a string such as "BUG", "summary", etc.
All messages go to standard error (at least at first; if a write to os.Stderr fails, this package tries system-dependent alternatives).
Most calls into this package will be to two sets of functions, called Warn[If][2] and Die[If][2] hereinafter. Here's a summary of these functions:
- Warn(format, formatArgs)
- Warn2(tag, format, formatArgs)
- WarnIf(skipIfNil, format, formatArgs)
- WarnIf2(skipIfNil, tag, format, formatArgs)
- Die(format, formatArgs)
- Die2(tag, format, formatArgs)
- DieIf(skipIfNil, format, formatArgs)
- DieIf2(skipIfNil, tag, format, formatArgs) where
- format is a format string for use with fmt.Sprintf()
- fmtArgs are arguments for that format string
- tag is a string to go after the program name in the above-mentioned ‘slightly less conventional format’, or "" to use the more conventional format.
- if skipIfNil is nil, WarnIf[2] and DieIf[2] do nothing. There are some special cases:
- WarnIf[2](err, "") is equivalent to WarnIf[2](err, "%s", err)
- DieIf[2](err, "") is equivalent to DieIf[2](err, "%s", err)
- Die("") and Die2(tag, "") call os.Exit() without outputting any message. This package provides three levels of diagnostic:
- the WriteMessage[2] functions are for informational messages
- the Warn[If][2] functions count how many warnings are output
- the Die[If][2] functions call os.Exit()
When calling os.Exit(), the default exit status is 3 if any warnings were reported, or 2 if none were. Programs can call SetExitStatus to change this.
This module has a subpackage named cmdiag_no_prefix which provides wrappers for the Warn[If][2] and Die[If][2] functions. It is intended to be imported without a prefix, like this:
import . "github.com/c12h/command-line-programs/cmdiag/cmdiag_no_prefix" ... err = open_backup(...) DieIf(err, "cannot restore from backup: %s", err)
The idea is that the names of these functions are distinctive enough to not need prefixing.
Dying is Dangerous ¶
WARNING: calling os.Exit() will NOT run deferred functions in the current goroutine, let alone in other goroutines. Therefore, it is strongly recommended that you only call Die[If][2] (1) before doing anything that might create another goroutine or defer any cleanup operations or (2) in main() after getting an error that needs to be reported as fatal. To be explicit: only main(), closely-related functions and setup code should ever call these routines.
Index ¶
- func Die(format string, fmtArgs ...interface{})
- func Die2(tag, format string, fmtArgs ...interface{})
- func DieIf(skipIfNil interface{}, format string, fmtArgs ...interface{})
- func DieIf2(skipIfNil interface{}, tag, format string, fmtArgs ...interface{})
- func GetExitStatus() int
- func GetPrefix() string
- func NumberOfWarnings() int
- func Panic(format string, fmtArgs ...interface{})
- func Panic2(tag, format string, fmtArgs ...interface{})
- func SetExitStatus(newStatus int) int
- func SetPrefix(s string)
- func TidyError(e error) error
- func Warn(format string, fmtArgs ...interface{})
- func Warn2(tag, format string, fmtArgs ...interface{})
- func WarnIf(skipIfNil interface{}, format string, fmtArgs ...interface{})
- func WarnIf2(skipIfNil interface{}, tag, format string, fmtArgs ...interface{})
- func WriteMessage(format string, fmtArgs ...interface{})
- func WriteMessage2(tag, format string, v ...interface{})
- type UntidyError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Die ¶
func Die(format string, fmtArgs ...interface{})
Die writes a fatal error message and calls os.Exit. As a special case, it does not write an error message if the format string is empty.
func Die2 ¶
func Die2(tag, format string, fmtArgs ...interface{})
Die2 writes a fatal error message (if and only if format is non-empty) and calls os.Exit. It takes an optional ‘tag’ argument.
func DieIf ¶
func DieIf(skipIfNil interface{}, format string, fmtArgs ...interface{})
DieIf reports a fatal error and calls os.Exit().
As a special case, DieIf(x,"") is equivalent to DieIf(x,"%s",x).
func DieIf2 ¶
func DieIf2(skipIfNil interface{}, tag, format string, fmtArgs ...interface{})
DieIf2 reports a fatal error and calls os.Exit(). It takes an optional ‘tag’ argument.
As a special case, DieIf2(x,tag,"") is equivalent to DieIf2(x,tag,"%s",x).
func GetExitStatus ¶
func GetExitStatus() int
GetExitStatus returns the base exit status that would be used if a Die[If][2] function reported a fatal error.
func GetPrefix ¶
func GetPrefix() string
GetPrefix returns the string that goes at the start of every diagnostic written by these function.
This string is set to filepath.Base(os.Args[0]) on program start.
func NumberOfWarnings ¶
func NumberOfWarnings() int
NumberOfWarnings returns the number of times a Warn[If][2] call has written a warning. (WarnIf[2] calls with SkipIfNil==nil don’t count.)
func Panic ¶
func Panic(format string, fmtArgs ...interface{})
Panic is a wrapper for the built-in panic() function which produces messages in the same format as Warn(), Die() etc.
func Panic2 ¶
func Panic2(tag, format string, fmtArgs ...interface{})
Panic2 is a wrapper for the built-in panic() function which produces messages in the same format as Warn2(), Die2() etc (ie, it takes an optional ‘tag’ argument).
func SetExitStatus ¶
SetExitStatus sets a new base exit status. It panics on values < 2 or > 124. The new value should usually be an even number.
Any Die[If][2] routine which calls os.Exit() will use the given value, except that if any warning have been reported, they use (value | 1).
func SetPrefix ¶
func SetPrefix(s string)
SetPrefix changes the string that these functions put at the start of every message.
For example, some programs might use
cmdiag.SetMessagePrefix(os.Args[0])
to avoid ambiguity.
func TidyError ¶
TidyError(e) is equivalent to e.Error() except for a few special cases, in which it gives something users of command-line programs will (IMO) find easier to understand.
Currently, TidyError() unwraps (pointers to) os.PathError, os.LinkError and os.SyscallError values. More cases may be added in the future.
func Warn2 ¶
func Warn2(tag, format string, fmtArgs ...interface{})
Warn2 writes a warning message. It takes an optional ‘tag’ argument.
func WarnIf ¶
func WarnIf(skipIfNil interface{}, format string, fmtArgs ...interface{})
WarnIf writes a warning message if (and only if) its first argument is non-nil.
As a special case, WarnIf(x,"") is equivalent to WarnIf(x,"%s",x).
func WarnIf2 ¶
func WarnIf2(skipIfNil interface{}, tag, format string, fmtArgs ...interface{})
WarnIf writes a warning message if (and only if) its first argument is non-nil. It takes an optional ‘tag’ argument.
As a special case, WarnIf2(x,tag,"") is equivalent to WarnIf2(x,tag,"%s",x).
func WriteMessage ¶
func WriteMessage(format string, fmtArgs ...interface{})
WriteMessage writes an informational message (as opposed to a warning or fatal error message).
func WriteMessage2 ¶
func WriteMessage2(tag, format string, v ...interface{})
WriteMessage2 writes an informational message (as opposed to a warning or fatal error message), with an optional tag between the prefix and the ":".
Types ¶
type UntidyError ¶
func (*UntidyError) Error ¶
func (e *UntidyError) Error() string
func (*UntidyError) Unwrap ¶
func (e *UntidyError) Unwrap() error
Source Files