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

File::Spec

Term::ANSIColor

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.

ClearSCM Inc.

NAME Display.pm

VERSION

SYNOPSIS

DESCRIPTION

ROUTINES

debug[1-3] ($msg, $handle, $nolinefeed, $level)

display ($msg, $handle, $nolinefeed)

display_err ($msg, $handle, $nolinefeed)

display_error ($msg, $errno, $handle, $nolinefeed)

display_nolf ($msg, $handle)

error ($msg, $errno, $handle, $nolinefeed)

get_debug

get_trace

get_verbose

set_debug

get_me ($me)

set_me ($me)

set_trace

set_verbose

trace

trace_enter

trace_exit

verbose[1-3] ($msg, $handle, $nolinefeed, $level)

verbose_nolf ($msg, $handle)

warning ($msg, $handle, $nolinefeed)

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

Perl Modules

INCOMPATABILITIES

BUGS AND LIMITATIONS

LICENSE AND COPYRIGHT