The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Debug-Easy-0.12
River stage zero No dependents
1 ++
/ Debug::Easy

NAME

Debug::Easy - A Handy Debugging Module

SYNOPSIS

 use Debug::Easy;

 my $debug = Debug::Easy->new( 'LogLevel' => 'DEBUG', 'Color' => 1 );

 # The first parameter to pass to the object is the line number.
 # Typically this is the Perl internal variable '__LINE__'.
 #
 # $debug_level is the maximum level to report, and ignore the rest.
 # It must be the second parameter passed to the object, when outputing
 # a specific message.  This identifies to the module what type of
 # message it is.
 #
 # The following is a list, in order of level, of the parameter to
 # pass to the debug method:
 #
 #  ERR       = Error
 #  WARN      = Warning
 #  NOTICE    = Notice
 #  INFO      = Information
 #  VERBOSE   = Special version of INFO that does not output any
 #              Logging headings and goes to STDOUT instead of STDERR.
 #              Very useful for verbose modes in your scripts.
 #  DEBUG     = Level 1 Debugging messages
 #  DEBUGMAX  = Level 2 Debugging messages
 #  DEBUGWAIT = Level 3 Debugging where execution is halted until a key
 #              is pressed (EXPERIMENTAL!!)
 #
 # The third parameter is either a string or a reference to an array
 # of strings to output as multiple lines.
 #
 # Each string can contain newlines, which will also be split into
 # a separate line and formatted accordingly.

 my $debug_level = 'NOTICE';

 $debug->debug(__LINE__,$debug_level,"Message");

 $debug->debug(__LINE__,'ERR',      ['Error message']);
 $debug->debug(__LINE__,'WARN',     ['Warning message']);
 $debug->debug(__LINE__,'NOTICE',   ['Notice message']);
 $debug->debug(__LINE__,'INFO',     ['Information and VERBOSE mode message']);
 $debug->debug(__LINE__,'DEBUG',    ['Level 1 Debug message']);
 $debug->debug(__LINE__,'DEBUGMAX', ['Level 2 Debug message']);
 $debug->debug(__LINE__,'DEBUGWAIT',['Level 3 Debug message with wait']);

 my @messages = (
    'First Message',
    'Second Message','
    "Third Message First Line\nThird Message Second Line"
 );

 $debug->debug(__LINE__,$debug_level,\@messages);

DESCRIPTION

This module makes it easy to add debugging features to your code, Without having to re-invent the wheel. It uses STDERR and ANSI color Formatted text output, as well as indented and multiline text formatting, to make things easy to read. NOTE: It is generally defaulted to output in a format for viewing on wide terminals!

Benchmarking is automatic, to make it easy to spot bottlenecks in code. It automatically stamps from where it was called, and makes debug coding so much easier, without having to include the location of the debugging location in your debug message. This is all taken care of for you.

It also allows multiple output levels from errors only, to warnings, to notices, to verbose information, to full on debug output. All of this fully controllable by the coder.

It is essentially a smart wrapper on top of Log::Fast to enhance it.

EXPORTABLE VARIABLES

@Levels

 A simple list of all the acceptable debug levels to pass to the {debug} method,
 and the {new} method.

METHODS

new

The parameter names are case insensitive as of Version 0.04.

LogLevel [level]

This adjusts the global log level of the Debug object. It requires a string.

ERR (default)

This level shows only error messages and all other messages are not shown.

WARN

This level shows error and warning messages. All other messages are not shown.

NOTICE

This level shows error, warning, and notice messages. All other messages are not shown.

INFO

This level shows error, warning, notice, and information messages. Only debug level messages are not shown.

VERBOSE

This level can be used as a way to do "Verbose" output for your scripts. It ouputs INFO level messages without logging headers and on STDOUT instead of STDERR.

DEBUG

This level shows error, warning, notice, information, and level 1 debugging messages. Level 2 Debug messages are not shown.

DEBUGMAX

This level shows all messages up to level 2 debugging messages.

DEBUGWAIT

This level shows all messages, but also waits for a keypress.

Color [boolean] (Not case sensitive)
0, Off, or False (Off)
 This turns off colored output.  Everything is plain text only.
1, On, or True (On - Default)
 This turns on colored output.  This makes it easier to spot all of
 the different types of messages throughout a sea of debug output.
 You can read the output with Less, and see color, by using it's
 switch "-r".
TimeStamp [pattern]

Make this an empty string to turn it off, otherwise:

%T
 Formats the timestamp as HH:MM:SS.  This is the default for the
 timestamp.
%S
 Formats the timestamp as seconds.milliseconds.  Normally not needed,
 as the benchmark is more helpful.
%T %S
 Combines both of the above.  Normally this is just too much, but here
 if you really want it.
DateStamp [pattern]

Make this an empty string to turn it off, otherwise:

%D
 Formats the datestamp as YYYY-MM-DD.  It is the default, and the only
 option.
Type
 Output type. Possible values are: 'fh' (output to any already open
 filehandle) and 'unix' (output to syslog using UNIX socket).
fh
 When set to 'fh', you have to also set {FileHandle} to any open filehandle
 (like "\*STDERR", which is the default).
unix
 When set to 'unix', you have to also set {FileHandle} to a path pointing to an
 existing unix socket (typically it's '/dev/log').
FileHandle
 File handle to write log messages if {Type} set to 'fh' (which is the default).

 Syslog's UNIX socket path to write log messages if {Type} set to 'unix'.
ANSILevel
 Contains a hash reference describing the various colored debug level labels

 The default definition (using Term::ANSIColor) is as follows:
      'ANSILevel' => {
     'ERR'       => colored(['white on_red'],       '[ ERROR ]'),
     'WARN'      => colored(['black on_yellow'],    '[WARNING]'),
     'NOTICE'    => colored(['black on_magenta'],   '[NOTICE ]'),
     'INFO'      => colored(['white on_black'],     '[ INFO  ]'),
     'DEBUG'     => colored(['bold green on_black'],'[ DEBUG ]'),
     'DEBUGMAX'  => colored(['bold green on_black'],'[-DEBUG-]'),
     'DEBUGWAIT' => colored(['bold green on_black'],'[*DEBUG*]')
  }

debug

The parameters must be passed in the order given

LINE
 The line number with which the debug was called.  Typically '__LINE__'
LEVEL
 The log level with which this message is to be triggered
MESSAGE(S)
 A string or list of strings to output line by line.

AUTHOR

Richard Kelsch <rich@rk-internet.com>

Copyright 2013 Richard Kelsch, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

Version 0.12 (November 27, 2014)

BUGS

Please report any bugs or feature requests to bug-easydebug at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=EasyDebug. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Debug::Easy

You can also look for information at:

ACKNOWLEDGEMENTS

The author of Log::Fast. A very fine module, without which, this module would be much larger.

LICENSE AND COPYRIGHT

Copyright 2013 Richard Kelsch.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.