NAME

B::LexInfo - Show information about subroutine lexical variables

SYNOPSIS

  use B::ShowLex ();
  my $lexi = B::ShowLex->new;

DESCRIPTION

Perl stores lexical variable names and values inside a padlist within the subroutine. Certain lexicals will maintain certain attributes after the the variable "goes out of scope". For example, when a scalar is assigned a string value, this value remains after the variable has gone out of scope, but is overridden the next time it is assigned to. Lexical Arrays and Hashes will retain their storage space for the maximum number of entries stored at any given point in time.

This module provides methods to record this information, which can be dumped out as-is or to compare two "snapshots". The information learned from these snapshots can be valuable in a number of ways.

METHODS

new

Create a new B::LexInfo object:

 my $lexi = B::LexInfo->new;

cvlexinfo

Create a padlist snapshot from a single subroutine:

  my $info = $lexi->cvlexinfo('Foo::bar');

stash_cvlexinfo

Create a list of padlist snapshots for each subroutine in the given package:

  my $info = $lexi->stash_cvlexinfo('Foo');

dumper

Return a reference to a stringified padlist snapshot:

  print ${ $lexi->dumper($info) }

diff

Compare two padlist snapshots and return the difference:

 my $before = $lexi->stash_cvlexinfo(__PACKAGE__);
 ... let some code run
 my $after = $lexi->stash_cvlexinfo(__PACKAGE__);

 my $diff = B::LexInfo->diff($before, $after);
 print $$diff;

NOTE: This function relies on the diff -u command. You might need to configure $B::LexInfo::TmpDir and/or $B::LexInfo::DiffCmd to values other than the defaults in LexInfo.pm.

cvrundiff

Take a padlist snapshot of a subroutine, run the subroutine with the given arguments, take another snapshot and return a diff of the snapshots.

 my $diff = $lexi->cvrundiff('Foo::bar', "arg1", $arg2);
 print $$diff;

Complete example:

 package Foo;
 use B::LexInfo ();

 sub bar {
     my($string) = @_;
 }

 my $lexi = B::LexInfo->new;
 my $diff = $lexi->cvrundiff('Foo::bar', "a string");
 print $$diff;

Produces:

 --- /tmp/B_LexInfo_1848.before  Mon Jun 28 19:48:41 1999
 +++ /tmp/B_LexInfo_1848.after   Mon Jun 28 19:48:41 1999
 @@ -2,8 +2,10 @@
    {
      'Foo::bar' => {
        '$string' => {
 -        'TYPE' => 'NULL',
 -        'NULL' => '0x80efd58'
 +        'TYPE' => 'PV',
 +        'LEN' => 9,
 +        'PV' => 'a string',
 +        'CUR' => 8
        },
        '__SPECIAL__1' => {
          'TYPE' => 'NULL',

SNAPSHOT INFO

Snapshots are built using Perl structures and stringified using Data::Dumper. Hash key order is sorted and preserved if you you the Tie::IxHash module installed. Entry names are that of the variable itself or __SPECIAL__$n for entries that are used by Perl internally. The key/value pairs for each entry depends on the variable type and state. Docs on that to come, in the meantime, study: http://gisle.aas.no/perl/illguts/

SEE ALSO

B(3), Apache::RegistryLexInfo(3), Devel::Peek(3)

AUTHOR

Doug MacEachern