Linux Certif

Toute la documentation sur la certification Linux LPI

NOCpulse::Debug.3pm

NAME

NOCpulse::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 775:

You can't have =items (as at line 784) unless the first thing after the =over is an =item