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