NAME

Debug::Easy - A Handy Debugging Module With Colorized Output and Formatting

SYNOPSIS

 use Debug::Easy;

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

'LogLevel' is the maximum level to report, and ignore the rest. The method names correspond to their loglevels, when outputting 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 logging methods:

 ERR       = Error
 WARN      = Warning
 NOTICE    = Notice
 INFO      = Information
 VERBOSE   = Special version of INFO that does not output any
             Logging headings.  Very useful for verbose modes in your
             scripts.
 DEBUG     = Level 1 Debugging messages
 DEBUGMAX  = Level 2 Debugging messages (typically more terse)

The 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.

 $debug->ERR(        ['Error message']);
 $debug->ERROR(      ['Error message']);
 $debug->WARN(       ['Warning message']);
 $debug->WARNING(    ['Warning message']);
 $debug->NOTICE(     ['Notice message']);
 $debug->INFO(       ['Information and VERBOSE mode message']);
 $debug->INFORMATION(['Information and VERBOSE mode message']);
 $debug->DEBUG(      ['Level 1 Debug message']);
 $debug->DEBUGMAX(   ['Level 2 (terse) Debug message']);

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

 $debug->INFO(\@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.

Generally all you need are the defaults and you are ready to go.

EXPORTABLE VARIABLES

@Levels

 A simple list of all the acceptable debug levels to pass as "LogLevel" in the {new} method.  Not normally needed for coding, more for reference.  Only exported if requested.

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.
    
     NOTE:  It has been asked "Why have two debugging levels?"  Well, I have had many times where I would like to see what a script is doing without it showing what I consider garbage overhead it may generate.  This is simply because the part of the code you are debugging you may not need such a high level of detail.  I use 'DEBUGMAX' to show me absolutely everything.  Such as Data::Dumper output.  Besides, anyone asking that question obviously hasn't dealt with complex data conversion scripts.
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".
Prefix [pattern]

This is global

A string that is parsed into the output prefix.

DEFAULT: '%Date% %Time% %Benchmark% %Loglevel%[%Subroutine%][%Lastline%] '

 %Date%       = Date (Uses format of "DateStamp" below)
 %Time%       = Time (Uses format of "TimeStamp" below)
 %Epoch%      = Epoch (Unix epoch)
 %Benchmark%  = Benchmark - The time it took between the last benchmark display
                of this loglevel.  If in an INFO level message, it benchmarks
                the time until the next INFO level message.  The same rule is
                true for all loglevels.
 %Loglevel%   = Log Level
 %Lines%      = Line Numbers of all nested calls
 %Module%     = Module and subroutine of call (can be a lot of stuff!)
 %Subroutine% = Just the last subroutine
 %Lastline%   = Just the last line number
 %PID%        = Process ID
 %date%       = Just Date (typically used internally only, use %Date%)
 %time%       = Just time (typically used internally only, use %Time%)
 %epoch%      = Unix epoch (typically used internally only, use %Epoch%)
 %Filename%   = Script Filename (parsed $0)
 %Fork%       = Running in parent or child?
     P = Parent
     C = Child
 %Thread%     = Running in Parent or Thread
     P   = Parent
     T## = Thread # = Thread ID
[loglevel]-Prefix [pattern]

You can define a prefix for a specific log level.

 ERR-Prefix
 WARN-Prefix
 NOTICE-Prefix
 INFO-Prefix
 DEBUG-Prefix
 DEBUGMAX-Prefix

If one of these are not defined, then the global value is used.

TimeStamp [pattern]

(See Log::Fast for specifics on these)

I suggest you just use Prefix above, but here it is anyway.

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]

I suggest you just use Prefix above, but here it is anyway.

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.
FileHandle
 File handle to write log messages.
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(['yellow'],              '[NOTICE ]'),
         'INFO'     => colored(['black on_white'],      '[ INFO  ]'),
         'DEBUG'    => colored(['bold green'],          '[ DEBUG ]'),
         'DEBUGMAX' => colored(['bold black on_green'], '[DEBUGMX]'),
      }

debug

NOTE: This is a legacy method for backwards compatibility. Please use the direct methods instead.

The parameters must be passed in the order given

LEVEL
 The log level with which this message is to be triggered
MESSAGE(S)
 A string or a reference to a list of strings to output line by line.

ERR or ERROR

Sends ERROR level debugging output to the log. Errors are always shown.

MESSAGE

Either a single string or a reference to a list of strings

WARN or WARNING

If the log level is WARN or above, then these warnings are logged.

MESSAGE

Either a single string or a reference to a list of strings

NOTICE or ATTENTION

If the loglevel is NOTICE or above, then these notices are logged.

MESSAGE

Either a single string or a reference to a list of strings

INFO or INFORMATION

If the loglevel is INFO (or VERBOSE) or above, then these information messages are displayed.

MESSAGE

Either a single string or a reference to a list of strings

DEBUG

If the Loglevel is DEBUG or above, then basic debugging messages are logged. DEBUG is intended for basic program flow messages for easy tracing. Best not to place variable contents in these messages.

MESSAGE

Either a single string or a reference to a list of strings

DEBUGMAX

If the loglevel is DEBUGMAX, then all messages are shown, and terse debugging messages as well. Typically DEBUGMAX is used for variable dumps and detailed data output for heavy tracing. This is a very "noisy" log level.

MESSAGE

Either a single string or a reference to a list of strings

CAVEATS

Since it is possible to duplicate the object in a fork or thread, the output formatting may be mismatched between forks and threads due to the automatic padding adjustment of the subroutine name field.

Ways around this are to separately create a Debug::Easy object in each fork or thread, and have them log to separate files.

The "less" pager is the best for viewing log files generated by this module. It's switch "-r" allows you to see them in all their colorful glory.

INSTALLATION

To install this module, run the following commands:

 perl Build.PL
 ./Build
 ./Build test
 ./Build install

OR you can use the old ExtUtils::MakeMaker method:

 perl Makefile.PL
 make
 make test
 make install

AUTHOR

Richard Kelsch <rich@rk-internet.com>

Copyright 2013-2018 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 2.00 (June 13, 2018)

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:

  • RT: CPAN's request tracker (report bugs here)

    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Debug-Easy

  • AnnoCPAN: Annotated CPAN documentation

    http://annocpan.org/dist/Debug-Easy

  • CPAN Ratings

    http://cpanratings.perl.org/d/Debug-Easy

    Not exactly a reliable and fair means of rating modules. Modules are updated and improved over time, and what may have been a poor or mediocre review at version 0,04, may not remotely apply to current or later versions. It applies ratings in an arbitrary manner with no ability for the author to add their own rebuttals or comments to the review, especially should the review be malicious or inapplicable.

    More importantly, issues brought up in a mediocre review may have been addressed and improved in later versions, or completely changed to allieviate that issue.

    So, check the reviews AND the version number when that review was written.

  • Search CPAN

    http://search.cpan.org/dist/Debug-Easy/

AUTHOR COMMENTS

Earlier versions of this module (pre version 1.0), were difficult to code with, and not "Easy" as the name implied. Version 1.x+ has addressed the issues brought forward by some users (and reviewers), and has made the module truely easy to use.

Version 2.0 promises to be even simpler, with fewer prerequisites on installation. Specifically the requirement for "Log::Fast" will be removed, and this module will exclusively handle logging, as I believe it should.

I coded this module because it filled a gap when I was working for a major chip manufacturing company. It gave the necessary output the other coders asked for, and fulfilled a need. It has grown far beyond those days, and I use it every day in my coding work.

If you have any features you wish added, or functionality improved or changed, then I welcome them, and will very likely incorporate them sooner than you think.

LICENSE AND COPYRIGHT

Copyright 2013-2018 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.