The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Badger-0.01
River stage one • 4 direct dependents • 7 total dependents
4 ++
/ Badger::Debug

NAME

Badger::Debug - base class mixin module implement debugging methods

SYNOPSIS

    package Badger::Whatever;
    
    use Badger::Debug 'debug';
    
    sub some_method {
        my $self = shift;
        $self->debug("This is a debug message\n");
    }

DESCRIPTION

This mixin module implements a number of methods for debugging.

METHODS

debug($msg1, $msg2, ...)

This method can be used to generate debugging messages.

    $object->debug("Hello ", "World\n");

It prints all argument to STDERR with a prefix indicating the class name, file name and line number from where the debug() method was called.

    [Badger::Example line 42] Hello World

At some point in the future this will be extended to allow you to tie in debug hooks, e.g. to forward to a logging module.

debug_up($n, $msg1, $msg2, ...)

The debug() method generates a message showing the file and line number from where the method was called. The debug_up() method can be used to report the error from somewhere higher up the call stack. This is typically used when you create your own debugging methods, as shown in the following example.

    sub parse {
        my $self = shift;
        
        while (my ($foo, $bar) = $self->get_foo_bar) {
            $self->trace($foo, $bar);               # report line here
            # do something
        }
    }
    
    sub trace {
        my ($self, $foo, $bar) = @_;
        $self->debug_up(2, "foo: $foo  bar: $bar"); # not here
    }

The trace() method calls the debug_up() method telling it to look two levels up in the caller stack instead of the usual one (thus debug_up(1,...) has the same effect as debug(...)). So instead of reporting the line number in the trace() subroutine (which would be the case if we called debug(...) or debug_up(1,...)), it will correctly reporting the line number of the call to trace() in the parse() method.

debug_caller()

Prints debugging information about the current caller.

    sub wibble {
        my $self = shift;
        $self->debug_caller();
    }

dump()

Debugging method which returns a text representation of the object internals.

    print STDERR $object->dump();

dump_hash(\%hash)

Debugging method which returns a text representation of the hash array passed by reference as the first argument.

    print STDERR $object->dump_hash(\%hash);

dump_list(\@list)

Debugging method which returns a text representation of the array passed by reference as the first argument.

    print STDERR $object->dump_list(\@list);

dump_text($text)

Debugging method which returns a truncated and sanitised representation of the text string passed (directly or by reference) as the first argument.

    print STDERR $object->dump_text($text);

dump_data($item)

Debugging method which calls the appropriate dump_hash(), dump_list() or dump_text() method for the item passed as the first argument.

    print STDERR $object->dump_data($item);

dump_data_inline($item)

Wrapper around dump_data() which strips any newlines from the generated output, suitable for a more compact debugging output.

    print STDERR $object->dump_data_inline($item);

enable_colour()

Enables colourful debugging.

PACKAGE VARIABLES

$FORMAT

The debug() method uses the message format in the $FORMAT package variable to generate debugging messages. The default value is:

    [<class> line <line>] <msg>

The <class>, <line> and <msg> markers denote the positions where the class name, line number and debugging message are inserted.

AUTHOR

Andy Wardley http://wardley.org/

COPYRIGHT

Copyright (C) 1996-2008 Andy Wardley. All Rights Reserved.

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