cldiag

Documentation

Overview

Package cldiag reports warnings, fatal errors, etc for command-line programs.

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("") calls 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 Warn[If][2] calls wrote anything, or 2 if none did. Programs can call SetExitStatus to change this. Exception: Die("") exits with status 1 if any warnings were reported, or 0 if no warnings have been issued.

This module has a subpackage named cldiag_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-utils/cldiag/cldiag_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
  • func (e *UntidyError) Error() string
  • func (e *UntidyError) Unwrap() error

Functions

func Die

func Die(format string, fmtArgs ...interface{})

Die writes a fatal error message and calls os.Exit.

As a special case, if the format string is empty, Die() calls os.Exit() without writing anything, using status code 0 if no Warn[If][2] calls wrote diagnostics, or 1 otherwise.

func Die2

func Die2(tag, format string, fmtArgs ...interface{})

Die2 writes a fatal error message 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

func SetExitStatus(newStatus int) int

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

cldiag.SetMessagePrefix(os.Args[0])

to avoid ambiguity.

func TidyError

func TidyError(e error) error

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 Warn

func Warn(format string, fmtArgs ...interface{})

Warn writes a warning message.

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

type UntidyError struct {
	OriginalError error
	BaseError     error
	TrimStart     int
}

func (*UntidyError) Error

func (e *UntidyError) Error() string

func (*UntidyError) Unwrap

func (e *UntidyError) Unwrap() error