NAME

LEOCHARRE::DEBUG - my default debug subroutines

SYNOPSIS

In A.pm

   package A;
   use LEOCHARRE::DEBUG;
   use strict;


   sub new {
      my $class = shift;
      my $self ={};
      bless $self, $class;
      return $self;   
   }

   sub test {
      my $self = shift;
      DEBUG or return 0;
      debug('ok .. i ran.');
      
      debug('ok .. i am more verbose.',2); # shows only if DEBUG level is 2 or more
      
      return 1;
   }

In script.t

   use Test::Simple 'no_plan';
   use strict;
   use A;

   my $o = new A;

   $A::DEBUG = 1;
   ok( $o->test );

   $A::DEBUG = 0;
   ok( !($o->test) );

USING COLOR

requires Term::ANSIColor use color..

   use LEOCHARRE::DEBUG 'use_color';
   DEBUG 1;
   debug('i am gray');

by default we use 'dark' if you want to change..

$LEOCHARRE::DEBUG::USE_COLOR = 'red';

Also..

   use LEOCHARRE::DEBUG;
   $LEOCHARRE::DEBUG::USE_COLOR = 'red';
   debug('i am red'); 

DEBUG()

set and get accessor returns number this is also the debug level. if set to 0, no debug messages are shown.

   print STDERR "oops" if DEBUG;

debug_detect_cliopt()

inspects the @ARGV and if there's a '-d' opt, sets debug to 1

debug()

argument is message, will only print to STDERR if DEBUG is on. optional argument is debug level that must be on for this to print, it is assumed level 1 (DEBUG on) if none passed.

   package My:Mod;
   use LEOCHARRE::DEBUG;
   
   My::Mod::DEBUG = 1;
   
   debug('only show this if DEBUG is on');
   # same as:
   debug('only show this if DEBUG is on',1);
   
   debug('only show this if DEBUG is on',2); # will not show, debug level is 1

   My::Mod::DEBUG = 2;   
   debug('only show this if DEBUG is on',2); # will show, debug level is 2
   debug('only show this if DEBUG is on'); # will also show, debug level is at least 1
   
   debug('only show this if DEBUG is on',3); # will not show, debug level is not 3 or more.
   
   My::Mod::DEBUG = 0; 
   debug('only show this if DEBUG is on'); # will not show, debug is off
   debug('only show this if DEBUG is on',3); # will not show, debug is off

If your message argument does not end in a newline, next message will not be prepended with the subroutine name.

   sub dostuff {
      debug("This is..");

      # ...

      debug("done.\n");

      debug("ok?");      
   }

Would print

   dostuff(), This is.. done.
   dostuff(), ok?

DESCRIPTION

I want to be able in my code to do this

   package My::Module;
   
   sub run {
      print STDERR "ok\n" if DEBUG;
   }     
   
   
   package main;
   
   $My::Module::DEBUG = 1;
   
   My::Module::run();

And I am tired of coding this

   $My::ModuleName::DEBUG = 0;
   sub DEBUG : lvalue { $My::ModuleName::DEBUG }

Using this module the subroutine DEBUG will return true or false, and it can be set via the namespace of the package using it.

NOTES

This package, alike LEOCHARRE::CLI, are under the author's name because the code herein comprises his particular mode of work. These modules are used throughout his works, and in no way interfere with usage of those more general modules.

DEBUG level

If DEBUG is set to at least "1", messages are shown as long as they are debug level 1. If you do not specify a debug level to debug(), 1 is assumed.

   $MYMOD::DEBUG = 0;

Show at least debug() calls with argument 2

   $MYMOD::DEBUG = 2;

Show at least debug() with argument 3

   $MYMOD::DEBUG = 3;

DEBUG tags

What if you want to show only messages that match a tag? If you pass a tag label starting in a letter and specify in DEBUG..

   $MYMOD::DEBUG = 'a';

   debug('hi'); # will not show

   debug('hi','a'); # WILL show

   debug('hi','b'); # will not show
   debug('hi',2); # will not show

SEE ALSO

LEOCHARRE::CLI

AUTHOR

Leo Charre leocharre at cpan dot org