3 =head1 NAME $RCSfile: Display.pm,v $
5 Simple and consistant display routines for Perl
13 Andrew DeFaria <Andrew@ClearSCM.com>
21 Fri Mar 12 10:17:44 PST 2004
25 $Date: 2013/05/30 15:48:06 $
31 This module seeks to make writing output simpler and more consistant. Messages
32 are classified as display (informational - always displayed), verbose (written
33 only if $verbose is set) and debug (written only if $debug is set). There are
34 also routines for error(s) and warning(s) which support optional parameters for
35 error number and warning number. If error number is specified then the process
39 verbose "$n records processed";
40 verbose2 "Processing record #$recno";
41 warning "Unable to find record", 1;
42 debug "Reached here...";
43 error "Can't continue", 2;
47 This module implements several routines to provide and easy and
48 consistant interface to writing output in Perl. Perl has lots of ways
49 to do such things but these methods seek to be self explainitory and
50 to provide convenient parameters and defaults so as to make coding
53 There are also some other routines, i.e. get_debug, that will return
54 $debug in case you want to execute other Perl code only when
58 foreach (@output_line) {
63 By default these routines write lines complete with the terminating
64 "\n". I find that this is most often what you are doing. There are
65 corresponding <routine>_nolf versions for display and verbose in case
66 you wish to not terminate lines. Or use the new say function.
68 Also, routines like display support a file handle parameter if you
69 wish to say display into a file - Default STDOUT.
71 Both version and debug support levels and have convienence functions:
72 verbose1, debug2. Three levels of conienence functions are supplied
73 although an unlimited amount can be supported directly through
74 verbose/debug. See documentaton for those functions for details.
78 The following routines are exported:
91 use Term::ANSIColor qw(color);
96 debug debug1 debug2 debug3
114 verbose verbose1 verbose2 verbose3
119 my ($me, $verbose, $debug, $trace);
122 $me = $FindBin::Script;
125 $verbose = $ENV{VERBOSE};
126 $debug = $ENV{DEBUG};
127 $trace = $ENV{TRACE};
130 sub display_err ($;$$);
133 my ($msg, $handle, $nolinefeed, $level) = @_;
137 =head2 debug[1-3] ($msg, $handle, $nolinefeed, $level)
139 Write $msg to $handle (default STDERR) with a "\n" unless $nolinefeed
140 is defined. Messages are written only if written if $debug is set and
141 =< $level. $level defaults to 1.
143 debug1, debug2 and debug3 are setup as convienence functions that are
144 equivalent to calling debug with $level set to 1, 2 or 3 respectively
148 =for html <blockquote>
158 File handle to display to (Default: STDERR)
162 If defined no linefeed is displayed at the end of the message.
166 If defined, if $level =< $debug then the debug message is displayed.
170 =for html </blockquote>
174 =for html <blockquote>
182 =for html </blockquote>
195 if (($handle and -t $handle) or (-t *STDERR)) {
196 $msg = color ('cyan')
205 $msg = "$me: DEBUG: $msg";
208 display_err $msg, $handle, $nolinefeed if $debug and $level <= $debug;
214 my ($msg, $handle, $nolinefeed) = @_;
216 debug $msg, $handle, $nolinefeed, 1;
222 my ($msg, $handle, $nolinefeed) = @_;
224 debug $msg, $handle, $nolinefeed, 2;
230 my ($msg, $handle, $nolinefeed) = @_;
232 debug $msg, $handle, $nolinefeed, 2;
238 my ($msg, $handle, $nolinefeed) = @_;
242 =head2 display ($msg, $handle, $nolinefeed)
244 Write $msg to $handle (default STDOUT) with a "\n" unless $nolinefeed
249 =for html <blockquote>
259 File handle to display to (Default: STDOUT)
263 If defined no linefeed is displayed at the end of the message.
267 =for html </blockquote>
271 =for html <blockquote>
279 =for html </blockquote>
284 $handle = *STDOUT unless $handle;
287 print $handle "\n" unless $nolinefeed;
292 sub display_err ($;$$) {
293 my ($msg, $handle, $nolinefeed) = @_;
297 =head2 display_err ($msg, $handle, $nolinefeed)
299 Displays $msg to STDERR
303 =for html <blockquote>
313 File handle to display to (Default: STDOUT)
317 If defined no linefeed is displayed at the end of the message.
321 =for html </blockquote>
325 =for html <blockquote>
333 =for html </blockquote>
338 $handle = *STDERR if !$handle;
341 print $handle "\n" if !$nolinefeed;
346 sub display_error ($;$$$) {
347 my ($msg, $errno, $handle, $nolinefeed) = @_;
351 =head2 display_error ($msg, $errno, $handle, $nolinefeed)
353 Displays colorized $msg to STDERR
357 =for html <blockquote>
367 Error no to display (if any)
371 File handle to display to (Default: STDOUT)
375 If defined no linefeed is displayed at the end of the message.
379 =for html </blockquote>
383 =for html <blockquote>
391 =for html </blockquote>
398 if (($handle and -t $handle) or (-t *STDERR) and ($Config{perl} ne 'ratlperl')) {
399 $msg = color ('cyan')
408 $msg = "$me: ERROR: $msg";
411 if (($handle and -t $handle) or (-t *STDERR) and ($Config{perl} ne 'ratlperl')) {
412 $msg = color ('cyan')
421 $msg = "$me: ERROR #$errno: $msg";
425 display_err $msg, $handle, $nolinefeed;
430 sub display_nolf ($;$) {
431 my ($msg, $handle) = @_;
435 =head2 display_nolf ($msg, $handle)
437 Equivalent of display ($msg, $handle, "nolf").
441 =for html <blockquote>
451 File handle to display to (Default: STDOUT)
455 =for html </blockquote>
459 =for html <blockquote>
467 =for html </blockquote>
471 display $msg, $handle, "nolf";
477 my ($msg, $errno, $handle, $nolinefeed) = @_;
481 =head2 error ($msg, $errno, $handle, $nolinefeed)
483 Write $msg to $handle (default STDERR) with a "\n" unless $nolinefeed
484 is defined. Preface message with "<script name>: ERROR: " so that
485 error messages are clearly distinguishable. If $errno is specified it
486 is included and the process it terminated with the exit status set to
491 =for html <blockquote>
501 File handle to display to (Default: STDOUT)
505 If defined no linefeed is displayed at the end of the message.
509 =for html </blockquote>
513 =for html <blockquote>
521 =for html </blockquote>
525 display_error $msg, $errno, $handle, $nolinefeed;
527 exit $errno if $errno;
542 =for html <blockquote>
546 =for html </blockquote>
550 =for html <blockquote>
558 =for html </blockquote>
575 =for html <blockquote>
579 =for html </blockquote>
583 =for html <blockquote>
591 =for html </blockquote>
608 =for html <blockquote>
612 =for html </blockquote>
616 =for html <blockquote>
624 =for html </blockquote>
642 =for html <blockquote>
648 New value to set $verbose to. If not specified then $verbose is set to
649 1. The only other sensible value would be 0 to turn off verbose.
653 =for html </blockquote>
657 =for html <blockquote>
661 =item Old setting of $verbose
665 =for html </blockquote>
669 my $returnValue = $debug ? $debug : 0;
671 $debug = defined $newValue ? $newValue : 1;
682 Gets $me which is used by error. Module automatically calculates the
683 basename of the script that called it.
695 =for html <blockquote>
703 =for html </blockquote>
717 Sets $me which is used by error. Module automatically calculates the
718 basename of the script that called it.
732 =for html <blockquote>
740 =for html </blockquote>
760 =for html <blockquote>
766 New value to set $trace to. If not specified then $trace is set to
767 1. The only other sensible value would be 0 to turn off trace.
771 =for html </blockquote>
775 =for html <blockquote>
779 =item Old setting of $trace
783 =for html </blockquote>
787 my $returnValue = $trace ? $trace : 0;
789 $trace = defined $newValue ? $newValue : 1;
794 sub set_verbose (;$) {
805 =for html <blockquote>
811 New value to set $verbose to. If not specified then $verbose is set to
812 1. The only other sensible value would be 0 to turn off verbose.
816 =for html </blockquote>
820 =for html <blockquote>
824 =item Old setting of $verbose
828 =for html </blockquote>
832 my $returnValue = $verbose ? $verbose : 0;
834 $verbose = defined $newValue ? $newValue : 1;
840 my ($msg, $type) = @_;
846 Emit trace statements from within a subroutine
850 =for html <blockquote>
856 Optional message to display
860 Optional prefix to message. Used by trace_enter and trace_exit. If not
861 specified the string "In " is used.
865 =for html </blockquote>
869 =for html <blockquote>
873 =item Name of the calling subroutine, if known
877 =for html </blockquote>
884 $msg = $msg ? ": $msg" : '';
887 croak 'Type should be ENTER, EXIT or undef'
888 unless $type eq 'ENTER' ||
892 my $stack = $type eq 'In' ? 1 : 2;
894 my ($package, $filename, $line, $subroutine) = caller ($stack);
897 $subroutine =~ s/^main:://
899 $subroutine = 'main';
903 display color ('cyan')
911 display "$type $subroutine$msg";
917 sub trace_enter (;$) {
924 Emit enter trace for a subroutine
928 =for html <blockquote>
934 Optional message to display along with "ENTER <sub>"
938 =for html </blockquote>
942 =for html <blockquote>
946 =item Name of the calling subroutine, if known
950 =for html </blockquote>
954 return trace $msg, "ENTER";
957 sub trace_exit (;$) {
964 Emit exit trace for a subroutine
968 =for html <blockquote>
974 Optional message to display along with "EXIT <sub>". Useful in
975 distinguishing multiple exit/returns.
979 =for html </blockquote>
983 =for html <blockquote>
991 =for html </blockquote>
1000 sub verbose ($;$$$) {
1001 my ($msg, $handle, $nolinefeed, $level) = @_;
1005 =head2 verbose[1-3] ($msg, $handle, $nolinefeed, $level)
1007 Write $msg to $handle (default STDOUT) with a "\n" unless $nolinefeed
1008 is defined. Messages are written only if written if $verbose is set
1009 and <= $level. $level defaults to 1.
1011 verbose1, verbose2 and verbose3 are setup as convienence functions
1012 that are equivalent to calling verbose with $level set to 1, 2 or 3
1017 =for html <blockquote>
1027 File handle to display to (Default: STDOUT)
1031 If defined no linefeed is displayed at the end of the message.
1035 If defined, if $level <= $verbose then the verbose message is
1040 =for html </blockquote>
1044 =for html <blockquote>
1052 =for html </blockquote>
1059 display $msg, $handle, $nolinefeed if $verbose and $level <= $verbose;
1064 sub verbose1 ($;$$) {
1065 my ($msg, $handle, $nolinefeed) = @_;
1067 verbose $msg, $$handle, $nolinefeed, 1;
1072 sub verbose2 ($;$$) {
1073 my ($msg, $handle, $nolinefeed) = @_;
1075 verbose $msg, $handle, $nolinefeed, 2;
1080 sub verbose3 ($;$$) {
1081 my ($msg, $handle, $nolinefeed) = @_;
1083 verbose $msg, $handle, $nolinefeed, 3;
1088 sub verbose_nolf ($;$) {
1089 my ($msg, $handle) = @_;
1093 =head2 verbose_nolf ($msg, $handle)
1095 Equivalent of verbose ($msg, $handle, "nolf")
1099 =for html <blockquote>
1109 File handle to display to (Default: STDOUT)
1113 =for html </blockquote>
1117 =for html <blockquote>
1125 =for html </blockquote>
1129 verbose $msg, $handle, "nolf";
1134 sub warning ($;$$$) {
1135 my ($msg, $warnno, $handle, $nolinefeed) = @_;
1139 =head2 warning ($msg, $handle, $nolinefeed)
1141 Write $msg to $handle (default STDERR) with a "\n" unless $nolinefeed
1142 is defined. Preface message with "<script name>: WARNING: " so that
1143 warning messages are clearly distinguishable.
1147 =for html <blockquote>
1157 File handle to display to (Default: STDOUT)
1161 If defined no linefeed is displayed at the end of the message.
1165 =for html </blockquote>
1169 =for html <blockquote>
1177 =for html </blockquote>
1184 if (($handle and -t $handle) or (-t *STDERR) and ($Config{perl} ne 'ratlperl')) {
1185 $msg = color ('cyan')
1194 $msg = "$me: WARNING: $msg";
1197 if (($handle and -t $handle) or (-t *STDERR) and ($Config{perl} ne 'ratlperl')) {
1198 $msg = color ('cyan')
1203 . "WARNING #$warnno"
1207 $msg = "$me: WARNING #$warnno: $msg";
1211 display_err $msg, $handle, $nolinefeed;
1220 =head1 CONFIGURATION AND ENVIRONMENT
1222 DEBUG: If set then $debug is set to this level.
1224 VERBOSE: If set then $verbose is set to this level.
1226 TRACE: If set then $trace is set to this level.
1232 L<File::Spec|File::Spec>
1234 L<Term::ANSIColor|Term::ANSIColor>
1236 =head1 INCOMPATABILITIES
1240 =head1 BUGS AND LIMITATIONS
1242 There are no known bugs in this module.
1244 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
1246 =head1 LICENSE AND COPYRIGHT
1248 This Perl Module is freely available; you can redistribute it and/or
1249 modify it under the terms of the GNU General Public License as
1250 published by the Free Software Foundation; either version 2 of the
1251 License, or (at your option) any later version.
1253 This Perl Module is distributed in the hope that it will be useful,
1254 but WITHOUT ANY WARRANTY; without even the implied warranty of
1255 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1256 General Public License (L<http://www.gnu.org/copyleft/gpl.html>) for more
1259 You should have received a copy of the GNU General Public License
1260 along with this Perl Module; if not, write to the Free Software Foundation,
1261 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.