NAME

    DBG - A collection of debugging functions

VERSION

    version v0.4.1

SYNOPSIS

      package Foo::Bar::Baz;
      use DBG;
    
      ...
      dbg "log this $message";
      ...
      png;                  # do I ever get here?
      ...
      trc;                  # how did I get here?
      ...
      dmp $obj;             # what is this?
      ...
      cyc $obj;             # does this have reference cycles?
      ...
      my $ts = ts;          # get me the current time
      ...
      rt $ts, ts;           # how long did that take?
      ...
      prp "is it so", $val; # prints message plus "yes" or "no"
      ...
      pkg $obj, 'doit';     # prints package providing obj's doit method
      ...

DESCRIPTION

    This is just a collection of functions useful for debugging. Instead of
    adding

      use Data::Dumper;
      use B::Deparse;
      use Devel::Size qw(total_size);

    and so forth you can just type

      use DBG;

    at the top of the script. If you're using git, or another version
    control system with similar functionality, you can write a simple
    pre-commit hook to prevent yourself from committing debugging lines to
    the repository. Once you've deleted the use DBG; line you can find all
    the other stuff you may have left in by trying to compile the code and
    looking at the errors.

    All functions have short names to make debugging quick(er).

    All debugging messages are printed both to the screen and to a log. The
    log will be ~/DBG.log unless otherwise specified. See $ENV{DBG_LOG}.
    This facilitates examining debugging output at one's leisure without
    having to visually cull away any other output produced by the program.

    All debugging functions are exported by default.

    A timestamp will be printed before any debugging output to facilitate
    distinguising one debugging session from another.

FUNCTIONS

 ts(;$) -- "get timestamp"

    Returns a DateTime-based timestamp. The optional argument is a label
    for the timestamp. The label will be accessible via the timestamp's
    text method.

      my $t = ts 'foo';
      say $t->text;  # foo
      say $t;        # 2014-05-31T22:31:52

 rt($$) -- "report timestamp"

    Report time difference. This function expects two objects generated by
    the ts function, the earlier first. It returns the second timestamp to
    facilitate the

       my $ts = ts;
       # some code
       $ts = rt $ts, ts

    pattern.

    The report will vary according to whether the first timestamp holds a
    label.

      my $t1 = ts 'foo';
      my $t2 = rt $t1, ts 'bar';
      sleep 1;
      my $t3 = rt $t2, ts;
      sleep 61;
      rt $t3, ts;
    
      # timestamp foo
      #     negligible time elapsed
      # timestamp bar
      #     1 second
      # 1 minute
      # 1 second

 trc() -- "trace"

    Prints a stack trace, skipping its own frame. Each line of the trace is
    formatted as

      frame number) code name (file:line)

    This involves munging the frames as returned by caller so instead of
    saying "you got here when called from here" it says simply "you are
    here". The next line says how you got here. That is, the code name is
    the name of the code you're in, not the code that just called you. I
    simply find this easier to follow.

      sub foo   { bar() }
      sub bar   { baz() }
      sub baz   { plugh() }
      sub plugh { trc }
      foo();
    
      # TRACE
      # 1) main::plugh (test.pl:11)
      # 2) main::baz (test.pl:10)
      # 3) main::bar (test.pl:9)
      # 4) main::foo (test.pl:8)
      # END TRACE

 dmp($) -- "dump"

    Prints a pretty data dump. This uses a combination of Perl::Tidy and
    Data::Dumper.

      my $r = { a => [qw(1 2 3)], c => { d => undef, egg => [ {}, {} ] } };
      dmp $r;
    
      # {
      #     a => [ '1', '2', '3' ],
      #     c => {
      #         d   => undef,
      #         egg => [ {}, {} ]
      #     }
      # }

 dbg($) -- "debug"

    Prints a message to the debugging log.

      dbg 'foo';  # foo

 png(;$) -- "ping"

    Prints a ping message to the debugging log. If optional argument is
    true, just prints "in code <code name> -- <optional arg>", where code
    name is the name of the function or method minus the package. If the
    optional argument is just "1", it is not suffixed to the ping message.

      sub foo { png }
      sub bar { png 1 }
      sub baz { png 'la la la la la' }
      foo();
      bar();
      baz();
    
      # PING main::foo (test.pl:11)
      # in code bar
      # in code baz -- la la la la la

 cyc($) -- "cycles"

    Checks for cycles in a reference, teeing out the entire object graph.
    This is like a condensed dump concerning itself only with references.

      my $a = {};
      my $b = { b => $a };
      my $c = { c => $b };
      $a->{a} = $c;
      cyc $a;
    
      # HASH (140416464744656 <- base)
      #    HASH (140416464745304 <- 140416464744656)
      #       HASH (140416464744992 <- 140416464745304)
      #          HASH (140416464744656 <- 140416464744992) -- ref count: 2

 prp($$) -- "property"

    Takes a message and a scalar to be evaluated as a boolean and submits
    this to dbg as "$message? yes/no".

      prp 'true', 1;
      prp 'true', 0;
    
      # true? yes
      # true? no

 cnm($;$) -- "code name"

      cnm $ua->can('request');  # LWP::UserAgent::request

    Converts a code reference to the place in the source code it comes
    from. This uses B::svref_2object to do its magic. Sometimes it will
    provide the file and line number, sometimes not.

    If the optional second parameter is provided, the information is only
    returned, not teed out.

 pkg($$;$) -- "package"

    Determines the package providing a method to an object. The first
    parameter is the object and the second the method name. Unless the
    optional third parameter is true, the file and line are also provided.

      my $d = DateTime->now;
      pkg $d, 'ymd';
    
      # package: DateTime; file: /Users/houghton/perl5/lib/perl5/darwin-thread-multi-2level/DateTime.pm; line: 820
    
      pkg $d, 'ymd', 1;
    
      # DateTime

 sz($;$) -- "size"

    Tees out the size of a scalar. If two arguments are given, the first is
    taken as a label and the second the scalar.

      sz {};         # 128
      sz 'foo', {};  # foo 128

    This delegates to the total_size function in Devel::Size. If you do not
    have Devel::Size, the sz will only emit a warning that it requires
    Devel::Size.

 mtd($;$) -- "method"

    Dumps out a sorted list of the object's method names, fully qualified.
    If the optional parameter is provided, it also lists where the code for
    each method can be found.

      my $d = DateTime->now;
      mtd $d;
    
      # Class: DateTime
      # [
      #     'DateTime::DefaultLanguage',
      #     'DateTime::DefaultLocale',
      #     'DateTime::INFINITY',
      #     'DateTime::MAX_NANOSECONDS',
      #     ...                           # many lines omitted
      # ]
    
      mtd $d, 1;
    
      # Class: DateTime
      # UNIVERSAL::DOES
      # DefaultLanguage                 : /Users/houghton/perl5/lib/perl5/darwin-thread-multi-2level/DateTime.pm  106
      # DefaultLocale                   : /Users/houghton/perl5/lib/perl5/darwin-thread-multi-2level/DateTime.pm  106
      # INFINITY                        : /Users/houghton/perl5/lib/perl5/constant.pm  30
      # MAX_NANOSECONDS                 : /Users/houghton/perl5/lib/perl5/darwin-thread-multi-2level/Class/MOP/Mixin/HasMethods.pm  131
      # ...

 inh($) -- "inheritance"

    Takes an object or class and prints out a sorted list of all the
    classes in that object or class's inheritance tree.

      package Plugh;
      package Foo;
      our @ISA = qw(Plugh);
      package Bar;
      package Baz;
      our @ISA = qw(Foo Bar);
      package main;
    
      inh 'Baz';
    
      # Classes in the inheritance hierarchy of Baz:
      #   Bar
      #   Baz
      #   Foo
      #   Plugh

 dpr -- "deparse"

    Takes a code reference and any optional parameters to pass to
    B::Deparse. Tees out the result of deparsing this reference.

      my $foo = sub { print "foo\n" };
      ...
      dpr $foo;    # what is this mystery code ref?
    
      # {
      #     use warnings;
      #     use strict 'refs';
      #     print "foo\n";
      # }

 flt($;$) -- "flatten"

    Takes a parameter and flattens it. For an ordinary scalar this just
    means it returns it. For containers -- hash or array references -- it
    returns copies with flattened values. Anything blessed it stringifies.

      flt { bar => 1, baz => DateTime->now };
    
      # {
      #     'bar' => 1,
      #     'baz' => '2014-05-31T21:04:07'
      # };

    This is useful for dumping hashes containing huge objects whose innards
    you don't need to see.

    If the optional second parameter is provided, the information is only
    returned, not also dumped out via dmp.

VARIABLES

  $ENV{DBG_LOG}

    If the DBG_LOG environment variable is set and is not equal to 0, this
    will be understood as the file into which debugging output should be
    dumped. If it is set to 0, the debugging output will only be sent to
    STDERR. If it is undefined, the log will be ~/DBG.log.

  $ENV{DBG_ON}

    If the DBG_ON environment variable is set, its boolean value will be
    used to determine the value of $DBG::ON.

  $ENV{DBG_HEADER}

    If the DBG_HEADER environment variable is set, its boolean value will
    be used to determine the value of $DBG::HEADER.

  $DBG::ON

    If $DBG::ON is true, which it is by default, all debugging code is
    executed. If it is false, debugging code is ignored (aside from the
    initial timestamp). The state of $ON can be manipulated
    programmatically or set by the $ENV{DBG_ON} environment variable. This
    can be used to constrain debugging output to a particular section of a
    program. For instance, one may set debugging to off and then locally
    set it to one within a particular method.

      sub foo {
          local $DBG::ON = 1;
          my self = shift;
          ...
      }

  $DBG::HEADER

    Unless $DBG::HEADER is false, a timestamp and process ID will be logged
    for a debugging process. The header is not printed until the first
    debugging line is logged, so this need not be set in a BEGIN block.

PRE-COMMIT HOOK

    You probably don't want debugging code, at least not that associated
    with DBG, getting into your repository. Here's a sample git pre-commit
    hook script for screening it out:

      my $rx = qr/
        ( (?&line){0,3} (?&dbg) (?&line){0,3} )
        (?(DEFINE)
          (?<line> ^.*?(?:\R|\z) )
          (?<dbg>  ^\+\s*use\s+DBG\b.*?(?:\R|\z) )
        )
      /mx;
      my $text = `git diff --staged`;
      if ( my @matches = $text =~ /$rx/g ) {
          @matches = grep defined, @matches;
          exit 0 unless @matches;
          print STDERR "DBG lines: \n\n" . join "\n", @matches;
          print STDERR "\nRun with --no-verify if you want to skip the DBG check.\n";
          print STDERR "Aborting commit.\n";
          exit 1;
      }
      exit 0;

AUTHOR

    Grant Street Group <developers@grantstreet.com>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2014 - 2020 by Grant Street Group.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)