/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/Devel-TraceSubs/blib/lib/Devel/TraceSubs.pm

/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/Devel-TraceSubs/blib/lib/Devel/TraceSubs.pm

NAME
VERSION
SYNOPSIS
DESCRIPTION
METHODS
EXPORT
BUGS
AUTHOR
COPYRIGHT
CREDITS
SEE ALSO

NAME

Devel::TraceSubs - Subroutine wrappers for debugging

VERSION

This document describes version 0.02 of Devel::TraceSubs, released 22 June 2002.

SYNOPSIS

  package foo;
  sub bar { print "foobar\n" }

  package etc;
  sub etc { etc::etc() }

  package main;
  use Devel::TraceSubs;

  sub foo { print "foo\n"; foo::bar() }

  my $pkg = 'main::';

  my $dbg = Devel::TraceSubs->new(
    verbose => 0, 
    pre => '>',
    post => '<',
    level => '~',
    params => 1,
    wrap => ['<!--', '-->'],
  );

  $dbg->untraceables( 'etc::etc::' );

  $dbg->trace(
    'foo::',            # valid
    $pkg,               # valid
    'main',             # invalid -- no trailing colons
    'joe::',            # invalid -- non-existant
    $dbg,               # invalid -- references not allowed
    'Debug::SubWrap::', # invalid -- self-reference not allowed
    *main::,            # invalid -- globs not allowed
    'etc::',            # invalid -- untraceable
  );

Devel::TraceSubs allows you to track the entry and exit of subroutines in a list of namespaces you specify. It will return the proper stack depth, and display parameters passed. Error checking prevents silent failures (err... the ones i know of.) It takes advantage of Hook::LexWrap to do the dirty work of wrapping the subs and return the proper caller context.

NOTE: Using verbose mode with wrap mode will generate a compile-time error. Don't do that!

ALSO NOTE: using level => '-' and pre=> '>' can cause problems with wrap => ['']. Don't do that, either!

METHODS

new()

Create a new instance of a Devel::TraceSubs object. Below is a description of the parameters, passed in hash format: parameter => value

pre =>: (SCALAR) Text specifying subroutine entry. Default value is '>'.
post =>: (SCALAR) Text specifying subroutine exit. Default value is '<'.
level =>: (SCALAR) Text repeated to show the subroutine stack level. Default value is '~'.
verbose =>: ( 1 | 0 ) Include verbose carp information. Verbose mode and wrap mode must not be enabled at the same time. Default is 0.
params =>: ( 1 | 0 ) Display subroutine parameters. If enabled, your subroutine parameters and return values will be displayed. Default is 0.
wrap =>: (ref 'ARRAY' size 2) Text to wrap all logging info. For instance, if [''] is specified, logging info will be wrapped in HTML comment tags. Default is ['',''].
logger =>: (ref 'CODE') Specify your own logging handler. Default logging is handled by &Carp::carp();
time =>: ( 1 | 0 ) Display the time during subroutine entry and exit. Default value is 0.

trace()

Trace all named subs in passed namespaces. Call this method with a list of namespaces in which you want to trace subroutine calls. Returns a list of currently traced namespaces in list context, and space seperated string of currently traced namespaces in scalar context.

untraceables()

Get or set the list of untraceable namespaces. Call this method with a list of namespaces you're having a problem tracing, and Devel::TraceSubs will happily ignore them. Returns list of untraceable namespaces in list context, and number of untraceable namespaces in scalar context. Default list is 'Carp::', 'Data::Dumper::'.

_stack_depth()

Internal use only. Calculates current stack depth. Returns list of stack items in list context, and stack depth in scalar context.

_gen_wrapper()

Internal use only. Generates the subroutine wrappers passed to Hook::LexWrap. Returns a code reference.

_warning()

Internal use only. Returns a warning message using Carp::carp.