view release on metacpan or  search on metacpan

lib/Devel/TraceVars.pm  view on Meta::CPAN

=head1 SYNOPSIS

    $ perl -d:TraceVars[+MODE[OPTIONS]] program [arguments]

Where MODE can be C<modules> or C<custom>.

If C<modules> mode is selected then the output will only include the lines
that are provided by the given modules.

Modules can be added by separating them by commas C<,>. By default the module
C<main> is assumed to be included. Optionally, the wildcard C<*> can be used
to indicate any module that matches the given pattern. Thus, the entry
C<Net::SSH::*> will match all modules that start with Net::SSH.

B<NOTE:> The wild card handling works only if it's used as the last character. 
Using the following pattern I<Net::*::Perl> isn't supported yet.

If C<non-cpan> is used then output will exclude all files that are provided by
CPAN. At present, a module is considered to be provided by CPAN if the module
is loaded from the Perl include path as designated by $Config{installarchlib}.

If no mode is specified then all output lines are printed.

Examples:

C<perl -d:TraceVars script.pl>

Prints all lines.

C<perl -d:TraceVars+modules script.pl>

Defaults to print only all lines of the package C<main> which usually means all
lines in the main program. The package C<main> is the default package used by
perl when no package is specified in the code.

C<perl -d:TraceVars+modules,Net::SSH,Digest::* script.pl>

Prints only information from the module C<Net::SSH>, and from any module whose
name starts with C<Digest>.

C<perl -d:TraceVars+noncpan script.pl>

Prints only lines that are provided by  perl files that aren't stored in the
default folder where all CPAN modules are installed.

=head1 DESCRIPTION

If you run your program with C<perl -d:TraceVars program>, this module
will print the current line of code being executed to standard error
just before each line is executed. The contents of all scalar variables will
be evaluated and displayed as well. All leading and trailing spaces will be
removed from each line.

=cut

package Devel::TraceVars;

use strict;
use Data::Dumper;
use PadWalker qw(peek_my);
use Config;


##
# Variables
##

our $VERSION = '0.03';


#
#
#This is the main closure used to include/exclude modules from the output.
#
#This closure will receive as arguments:
#  $package
#  $filename
#  $line
#
my $ACCEPT_CLOSURE = sub { return 1; };


##
# Methods
##


=head1 METHODS

The following methods are available.

=cut


=head2 import

Called by perl when this module is first loaded.

=cut

sub import {
	my $module = shift;
	
	# Stop if there are no arguments
	return unless @_;
	
	# The execution mode
	my $mode = lc shift;
	
	# Check which Execution mode is requested
	if ($mode eq 'modules') {
		
		# Modules to accept
		my %modules = map { $_ => 1 } ('main', @_);
		
		$ACCEPT_CLOSURE = sub {
			my ($package, $filename, $line) = @_;

			# Keep only if module is in the list of known modules
			return 1 if $modules{$package};