Debug(3) User Contributed Perl Documentation Debug(3)NAMENOCpulse::Debug - custom Perl debug module
SYNOPSIS
use NOCpulse::Debug;
my $debug = new NOCpulse::Debug;
my $literal = $debug->addstream(CONTEXT => 'literal',
LEVEL => 1);
open(LOG, "> /tmp/junklog") or die "Can't open file /tmp/junklog:$!\n";
my $html = $debug->addstream(FILE => \*LOG,
CONTEXT => 'html',
LEVEL => 2);
my $hcomment = $debug->addstream(FILE => '/tmp/junklog2',
CONTEXT => 'html_comment',
LEVEL => 1,
LINENUM => 1,
APPEND => 1);
#- Output text to all streams with debug level <= 2
$debug->dprint(2, "This is a level 2 debugging message");
DESCRIPTION
This module provides methods for debug output that can ultimately be
used in place of standard print statements. The two primary advantages
of this module over standard print are debug "streams" and the
implementation of multiple debug levels. Limited formatted output is
available for HTML applications.
Debug Streams
A Debug Stream is a stream of output that is connected to a file.
The file can be STDOUT, an already opened file handle, or a
filename. Although not recommended, it is possible to have multiple
streams printing to the same file.
Debug Levels
Debug levels allow control over the level of detail of the Debug
output.
CONSTRUCTOR
"new NOCpulse::Debug"
Creates a new Debug object.
METHODS
addstream dprint
flush buffering close
suspend resume active
prefix postfix suffix
timestamps linenumbers level
contents clear_contents
$stream = $debug->addstream( [PARAMS] )
Create a debug output stream to a file.
Optional parameters:
FILE - A filename or open filehandle. Defaults to STDOUT.
LEVEL - The minimum level for this output stream. Only 'dprint'
statements that specify a level greater than or equal to this level
will generate output. (Defaults to 0. Can be adjusted at run-time
with the 'level' method.)
CONTEXT - format of text to be output. The currently supported
contexts are:
'literal' - unformatted text (default)
'html' - literal text surrounded by HTML <pre> tags
'html_comment - literal text surrounded by HTML comment tags
APPEND - When set to non-zero value, output from a debug stream
will be appended to the the specified file. Default is 0.
(Note: This parameter is only effective when the FILE parameter is
a filename. Modes of filehandles opened outside the module are
determined by the opener.)
$stream->dprint( LEVEL, @message )
$debug->dprint( LEVEL, @message )
Print @message to an individual stream or to all active streams in
a debug object. Output will only occur if LEVEL is less than or
equal to each stream's debug level (set with 'addstream' or
'level').
$stream->flush
$debug->flush
Flush the file buffer of a stream or all streams in a debug object.
(Useful when 'tail'ing a file to monitor output.)
$stream->clear_contents
$debug->clear_contents
Clears buffered contents of a stream or all streams in a debug
object. Only meaningful when buffering.
$stream->close
$debug->close
Close an individual stream or all streams in a debug object.
$stream->resume
$stream->suspend
$stream->active
Suspend or resume output to a particular stream, or check to see if
a stream is active.
$stream->prefix($str)
$stream->postfix($str)
$stream->suffix($str)
Fixed output. An output line is composed of:
${prefix}${timestamp}${postfix}${lineno}${message}${suffix}
where any of the above may be undefined or empty. (See
'linenumbers' below for a description of ${lineno}.)
$stream->level($level)
Read or change a debug level at run time. For example, you can do:
$SIG{'USR1'} = sub { $stream->level($stream->level() + 1);
$SIG{'USR2'} = sub { $stream->level($stream->level() - 1);
to allow the users to dynamically change the level of output.
$stream->linenumbers({0|1})
Enable/disable line numbers. If enabled, each output line will
include the line number of the dprint() statement that generated
the output line.
$stream->timestamps( [{0|1|<function>}] )
Prepend each output line with a timestamp. <function>, if
supplied, should be a reference to a function that returns a scalar
timestamp. If called with a function reference, timestamps are
enabled. If called with no arguments, timestamps are enabled with
a default timestamp function (which generates timestamps in the
form 'DD-MM-YY HH24:MI:SS'). Calling 'timestamps' with a 0 or 1
suspends or resumes timestamps without changing the timestamp
function.
$stream->contents
Returns the buffered contents of a stream, all of the output that
has not yet been flushed.
Example
#!/usr/bin/perl
use strict;
use NOCpulse::Debug;
my $verboselogfile = '/var/adm/verboselog';
my $debug = new NOCpulse::Debug;
# Set up a verbose, timestamped stream to a log file
my $verbosestream = $debug->addstream( FILE => $verboselogfile,
APPEND => 1,
CONTEXT => 'literal',
LEVEL => 9);
$verbosestream->timestamps(1);
$verbosestream->suffix("\n"); # End each statement with a newline
# Set up a less verbose stream with line numbers for the user
my $stdout = $debug->addstream( LEVEL => 1 );
# ... stuff happens
$debug->dprint(1, "This is an informative message\n");
$debug->dprint(4, "This is too detailed for the screen:", @debug_info);
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 774:
You can't have =items (as at line 783) unless the first thing after
the =over is an =item
perl v5.14.1 2011-02-18 Debug(3)
