NAME Display.pm 
Simple and consistant display routines for Perl
VERSION
- Author
-
Andrew DeFaria <Andrew@ClearSCM.com>
- Revision
-
Revision 1.45
- Created
-
Fri Mar 12 10:17:44 PST 2004
- Modified
-
Modifed 2013/05/30 15:48:06
SYNOPSIS
This module seeks to make writing output simpler and more consistant. Messages are classified as display (informational - always displayed), verbose (written only if $verbose is set) and debug (written only if $debug is set). There are also routines for error(s) and warning(s) which support optional parameters for error number and warning number. If error number is specified then the process is also terminated.
display "message";
verbose "$n records processed";
verbose2 "Processing record #$recno";
warning "Unable to find record", 1;
debug "Reached here...";
error "Can't continue", 2;
DESCRIPTION
This module implements several routines to provide and easy and consistant interface to writing output in Perl. Perl has lots of ways to do such things but these methods seek to be self explainitory and to provide convenient parameters and defaults so as to make coding easier.
There are also some other routines, i.e. get_debug, that will return $debug in case you want to execute other Perl code only when debugging:
if (get_debug) {
foreach (@output_line) {
debug $_;
} # foreach
} # if
By default these routines write lines complete with the terminating "\n". I find that this is most often what you are doing. There are corresponding <routine>_nolf versions for display and verbose in case you wish to not terminate lines. Or use the new say function.
Also, routines like display support a file handle parameter if you wish to say display into a file - Default STDOUT.
Both version and debug support levels and have convienence functions: verbose1, debug2. Three levels of conienence functions are supplied although an unlimited amount can be supported directly through verbose/debug. See documentaton for those functions for details.
ROUTINES
The following routines are exported:
debug[1-3] ($msg, $handle, $nolinefeed, $level)
Write $msg to $handle (default STDERR) with a "\n" unless $nolinefeed is defined. Messages are written only if written if $debug is set and =< $level. $level defaults to 1.
debug1, debug2 and debug3 are setup as convienence functions that are equivalent to calling debug with $level set to 1, 2 or 3 respectively
Parameters:
- $msg:
Message to display
- $handle:
File handle to display to (Default: STDERR)
- $nolinefeed:
If defined no linefeed is displayed at the end of the message.
- $level
If defined, if $level =< $debug then the debug message is displayed.
Returns:
- Nothing
display ($msg, $handle, $nolinefeed)
Write $msg to $handle (default STDOUT) with a "\n" unless $nolinefeed is defined.
Parameters:
- $msg:
Message to display
- $handle:
File handle to display to (Default: STDOUT)
- $nolinefeed:
If defined no linefeed is displayed at the end of the message.
Returns:
- Nothing
display_err ($msg, $handle, $nolinefeed)
Displays $msg to STDERR
Parameters:
- $msg:
Message to display
- $handle:
File handle to display to (Default: STDOUT)
- $nolinefeed:
If defined no linefeed is displayed at the end of the message.
Returns:
- Nothing
display_error ($msg, $errno, $handle, $nolinefeed)
Displays colorized $msg to STDERR
Parameters:
- $msg:
Message to display
- $errno
Error no to display (if any)
- $handle:
File handle to display to (Default: STDOUT)
- $nolinefeed:
If defined no linefeed is displayed at the end of the message.
Returns:
- Nothing
display_nolf ($msg, $handle)
Equivalent of display ($msg, $handle, "nolf").
Parameters:
- $msg:
Message to display
- $handle:
File handle to display to (Default: STDOUT)
Returns:
- Nothing
error ($msg, $errno, $handle, $nolinefeed)
Write $msg to $handle (default STDERR) with a "\n" unless $nolinefeed is defined. Preface message with "<script name>: ERROR: " so that error messages are clearly distinguishable. If $errno is specified it is included and the process it terminated with the exit status set to $errno.
Parameters:
- $msg:
Message to display
- $handle:
File handle to display to (Default: STDOUT)
- $nolinefeed:
If defined no linefeed is displayed at the end of the message.
Returns:
- Nothing
get_debug
Returns $debug.
Parameters:
None
Returns:
- $debug
get_trace
Returns $trace.
Parameters:
None
Returns:
- $trace
get_verbose
Returns $verbose.
Parameters:
None
Returns:
- $verbose
set_debug
Sets $debug.
Parameters:
- newValue
New value to set $verbose to. If not specified then $verbose is set to 1. The only other sensible value would be 0 to turn off verbose.
Returns:
- Old setting of $verbose
get_me ($me)
Gets $me which is used by error. Module automatically calculates the basename of the script that called it.
Parameters:
- none
Returns:
- $me
set_me ($me)
Sets $me which is used by error. Module automatically calculates the basename of the script that called it.
Parameters:
- $me
-
String to set $me as
Returns:
- Nothing
set_trace
Sets $trace.
Parameters:
- newValue
New value to set $trace to. If not specified then $trace is set to 1. The only other sensible value would be 0 to turn off trace.
Returns:
- Old setting of $trace
set_verbose
Sets $verbose.
Parameters:
- newValue
New value to set $verbose to. If not specified then $verbose is set to 1. The only other sensible value would be 0 to turn off verbose.
Returns:
- Old setting of $verbose
trace
Emit trace statements from within a subroutine
Parameters:
- msg
Optional message to display
- type
Optional prefix to message. Used by trace_enter and trace_exit. If not specified the string "In " is used.
Returns:
- Name of the calling subroutine, if known
trace_enter
Emit enter trace for a subroutine
Parameters:
- msg
Optional message to display along with "ENTER <sub>"
Returns:
- Name of the calling subroutine, if known
trace_exit
Emit exit trace for a subroutine
Parameters:
- msg
Optional message to display along with "EXIT <sub>". Useful in distinguishing multiple exit/returns.
Returns:
- none
verbose[1-3] ($msg, $handle, $nolinefeed, $level)
Write $msg to $handle (default STDOUT) with a "\n" unless $nolinefeed is defined. Messages are written only if written if $verbose is set and <= $level. $level defaults to 1.
verbose1, verbose2 and verbose3 are setup as convienence functions that are equivalent to calling verbose with $level set to 1, 2 or 3 respectively
Parameters:
- $msg
Message to display
- $handle
File handle to display to (Default: STDOUT)
- $nolinefeed
If defined no linefeed is displayed at the end of the message.
- $level
If defined, if $level <= $verbose then the verbose message is displayed.
Returns:
- Nothing
verbose_nolf ($msg, $handle)
Equivalent of verbose ($msg, $handle, "nolf")
Parameters:
- $msg
Message to display
- $handle
File handle to display to (Default: STDOUT)
Returns:
- Nothing
warning ($msg, $handle, $nolinefeed)
Write $msg to $handle (default STDERR) with a "\n" unless $nolinefeed is defined. Preface message with "<script name>: WARNING: " so that warning messages are clearly distinguishable.
Parameters:
- $msg:
Message to display
- $handle:
File handle to display to (Default: STDOUT)
- $nolinefeed:
If defined no linefeed is displayed at the end of the message.
Returns:
- Nothing
CONFIGURATION AND ENVIRONMENT
DEBUG: If set then $debug is set to this level.
VERBOSE: If set then $verbose is set to this level.
TRACE: If set then $trace is set to this level.
DEPENDENCIES
Perl Modules
INCOMPATABILITIES
None yet...
BUGS AND LIMITATIONS
There are no known bugs in this module.
Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
LICENSE AND COPYRIGHT
This Perl Module is freely available; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This Perl Module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License (http://www.gnu.org/copyleft/gpl.html) for more details.
You should have received a copy of the GNU General Public License along with this Perl Module; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. reserved.