NAME

debug.sh — selectively debug scripts

SYNOPSIS

• $_DEBUG_SH . debug.sh

• DebugOn [-eo] tag ...
• DebugOff [-eo] [rc=rc] tag ...
• Debugging
• DebugAdd tag
• DebugEcho [message]
• DebugLog [message]
• DebugShell tag ...
• DebugTrace message
• Debug tag ...

DESCRIPTION

debug.sh provides the following functions to facilitate flexible run-time tracing of complicated shell scripts.

DebugOn [-eo] tag ...

turns tracing on if any tag is found in DEBUG_SH (a comma separated list of tags).

It turns tracing off if !tag is found in DEBUG_SH.

It sets DEBUG_ON to the tag that caused tracing to be enabled, or DEBUG_OFF if we matched !tag.

If -e option is present, returns 1 if no tag matched.

If -o option is present, tracing is turned off unless there was a matched tag, useful for functions too noisy to tace.

DebugOff [-eo] [rc=rc] tag ...

turns tracing on if any tag matches DEBUG_OFF or off if any tag matches DEBUG_ON. This allows nested functions to not interfere with each other.

The flags -e and -o are ignored, they just allow for symmetry with calls to DebugOn().

The optional rc value will be returned rather than the default of 0. Thus if DebugOff() is the last operation in a function, rc will be the return code of the function.

Debugging

returns true if tracing is enabled. It is useful for bounding complex debug actions, rather than using lots of $DEBUG_DO lines.

DebugAdd tag

Add tag to DEBUG_SH to influence later output, possibly in a child process.

DebugEcho

is just shorthand for:

$DEBUG_DO echo "$@"

DebugLog [message]

If debugging is enabled, output message prefixed with a time-stamp.

DebugShell tag ...

runs an interactive shell if any tag is found in DEBUG_INTERACTIVE, and there is a tty available. The shell used is defined by DEBUG_SHELL or SHELL and defaults to /bin/sh.

DebugTrace message

Debug output can be very noisy, and it can be tricky to align with the script. This function outputs a very noticeable banner indicating the value of DEBUG_ON, and message is passed to DebugLog(), finally the banner is repeated.

Debug tag ...

For backwards compatibility, calls DebugOn() and if that does not turn tracing on, it calls DebugOff() to turn it off.

The variables DEBUG_SKIP and DEBUG_DO are set so as to enable/disable code that should be skipped/run when debugging is turned on. DEBUGGING is the same as DEBUG_SKIP for backwards compatibility and is only set by Debug().

The use of $_DEBUG_SH is to prevent multiple inclusion, though it does no harm in this case.

BUGS

Does not work with some versions of ksh(1). If a function turns tracing on, ksh turns it off when the function returns - useless.

PD ksh works ok ;-)

AUTHOR

debug.sh was written by Simon J Gerraty <sjg@crufty.net>.