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

NAME

Debug::LTrace - Perl extension to locally trace subroutine calls

VERSION

Version 0.01

SYNOPSIS

    use Debug::LTrace;

    {   
        
        my $tracer = Debug::LTrace->new('tsub'); # create local tracer
        tsub(1); # Tracing is on while $tracer is alive
        
    }   
    
    tsub(2); # Here tracing is off
    
    sub tsub {shift}

    #or  

    perl -MDebug::LTrace='*' yourprogram.pl # trace all subroutines in package main

DESCRIPTION

Debug::LTrace instruments subroutines to provide tracing information upon every call and return. Using Debug::LTrace does not require any changes to your sources. The trace information is output using the standard warn() function.

It was inspired by Debug::Trace, but introduces new features such as

  • Lexically scoped tracing

  • Implements tracing in such way that the standard caller function works correctly

  • Enable package tracing (using '*' syntax)

  • Nice output formatting

  • More debug information (time of execution, call context...)

Also Debug::LTrace supports Debug::Trace syntax (modifiers are not supported yet).

Devel::TraceCalls - Powerful CPAN module but too complex API and not so convenient as Debug::LTrace

Some useful examples:

from command line:
    # Trace "foo" and "bar" subroutines
    perl -MDebug::LTrace=foo,bar yourprogram.pl 

    # Trace all subroutines in current package ( "main" )
    perl -MDebug::LTrace='*' yourprogram.pl 
    
    # Trace all subroutines in package "SomeModule" and "AnotherModule::foo"
    perl -MDebug::LTrace='SomeModule::*, AnotherModule::foo' yourprogram.pl
the same in code:
    # Trace "foo", "bar" subroutines in current package (can be not "main")
    use Debug::LTrace qw/foo bar/;  

    # Trace all subroutines in current package (can be not "main")
    use Debug::LTrace qw/*/; 
    
    # Trace all subroutines in package "SomeModule" and "AnotherModule::foo"
    use Debug::LTrace qw/SomeModule::* AnotherModule::foo/;
local tracing (is on only when $tracer is alive):
    # Trace foo, bar subroutines in current package (can be not "main")
    my $tracer = Debug::LTrace->new( 'foo',  'bar' );  
    
    # Trace all subroutines in current package (can be not "main")
    my $tracer = Debug::LTrace->new('*'); 
    
    # Trace all subroutines in package SomeModule and AnotherModule::foo
    my $tracer = Debug::LTrace->new('SomeModule::*', 'AnotherModule::foo');

Output trace log using custom function

Debug::LTrace outputs trace log using standart warn function. So you can catch SIGWARN with this code:

    $SIG{__WARN__} = sub {
        if ( $_[0] =~ /^TRACE/ ) {
            goto &custum_sub
        } else {
            print STDERR @_;  
        }
    }

METHODS

Debug::LTrace->new($sub [, $sub2, $sub3 ...] );

$sub can be fully-qualified subroutine name like SomePackage::foo and will enable tracing for subroutine SomePackage::foo

$sub can be short subroutine name like foo willl enable tracing for subroutine foo in current namespace

$sub can be fully-qualified mask like SomePackage::* will enable tracing for all subroutines in SomePackage namespace including improrted ones

TODO

  • improve Debug::LTrace compatibility (add modifiers support)

  • enabling tracing for whole tree of modules

  • callback support to handle debug output

AUTHOR

"koorchik", <"koorchik at cpan.org">

BUGS

Please report any bugs or feature requests to bug-debug-ltrace at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Debug-LTrace. 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::LTrace

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 "koorchik".

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

SEE ALSO

Debug::Trace, Devel::TraceCalls, Hook::LexWrap, Devel::Symdump