Sub::Information - Get subroutine information

Version 0.10

    use Sub::Information as => 'inspect';

    my $code_info = inspect(\&code);
    print $code_info->name;
    print $code_info->package;
    print $code_info->code;
    print $code_info->address;
    # etc.

Typically, if we need to get information about code references, we have to remember which of myriad modules to load. Need to know if it's blessed? Scalar::Util will do that. Package it was declared in: Sub::Identify. Source code: Data::Dump::Streamer. And so on ...

This module integrates those together so that you don't have to remember them.

By default, we export the inspect function. This function, when called on a code reference, will 'inspect' the code reference and return a Sub::Information object. If you already have an inspect function, you can rename the function by specifying as => 'other_func' in the import list. The following are equivalent:

 use Sub::Information;                # exports 'inspect'
 my $info = inspect($coderef);

Or:

 use Sub::Information ();             # don't import anything
 my $info = Sub::Information->new($coderef);

Or:

 use Sub::Information as => 'peek';   # exports 'peek'
 my $info = peek($coderef);

 my $info = inspect($coderef);

Given a code reference, this function returns a new Sub::Information object.

 my $info = Sub::Information->new($coderef);

Returns a new Sub::Information object.

Unless otherwise stated, all methods cache their return values and the modules they rely on are not loaded until needed. Please see the documentation of the original module for more information about how the method behaves.

 my $address = $info->address;

Returns the memory address, in decimal, of the original code reference.

From: Scalar::Util::refaddr

 my $blessed = $info->blessed;

Returns the package name a coderef is blessed into. Returns undef if the coderef is not blessed.

From: Scalar::Util::blessed

 my $source_code = $info->code;

Returns the source code of the code reference. Because of how it's generated, it should be equivalent in functionality to the original code reference, but may appear different. For example:

 sub add_2 { return 2 + shift }
 print inspect(\&add_2)->code;

 __END__
 # output
 $CODE1 = sub {
   use strict 'refs';
   return 2 + shift(@_);
 };

From: Data::Dump::Streamer::Dump

 $info->dump;

Returns the internals information regarding the coderef as generated by Devel::Peek::Dump to STDERR. This method is experimental. Let me know if it doesn't work.

From: Devel::Peek

 my $fullname = $info->fullname;

Returns the fully qualified subroutine name (package + subname) of the coderef.

From: Sub::Identify::sub_fullname

 my $name = $info->name;

Returns the name of the subroutine. If the subroutine is an anonymous subroutine, it may return __ANON__. However, you can name anonymous subroutines with:

 local *__ANON__ = 'name::of::anonymous::subroutine';

From: Sub::Identify::sub_name

 my $package = $info->package;

Returns the name of the package the subroutine was declared in.

From: Sub::Identify::stash_name

 my $variables = $info->variables;

Returns all my variables found in the code reference (whether declared their or outside of the code reference). The return value is a hashref whose keys are the names (with sigils) of the variables and whose values are the values of said variable.

Note that those values will be undefined unless the code is currently "in use" (e.g., you're calling variables() from inside the sub or in a call stack the sub is currently in).

The returned values are not cached.

From: PadWalker::peek_sub

 my $line_number = $info->line;

Returns the approximate line number where the sub was declared. This is experimental.

From : B

 my $file_name = $info->file;

Returns the file name where the sub was declared. This is experimental.

From : B

This is ALPHA code.

* Memory requirements

Some modules, such as Devel::Size, can be very expensive to load. Thus, none are loaded until such time as they are needed.

* Caching

To avoid overhead, we cache all results unless otherwise noted.

* Return values

Returns values are not calculated until such time as they are requested. Thus, it's possible that the value returns is not identical to the value for the code reference at the time the new Sub::Information instance was created.

* Refcount

The Sub::Information instance stores a reference to the coderef, thus incrementing its refcount by 1.

Curtis "Ovid" Poe, <ovid@cpan.org>

Please report any bugs or feature requests to bug-sub-information@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Information. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Probably lots. Send patches, ideas, criticisms, whatever.

Several of the following modules are either used internally or may be of further interest to you.

* B::Deparse

* Devel::Peek

* Devel::Size

* Data::Dump::Streamer

* PadWalker

* Sub::Identify

* Scalar::Util

Much appreciation to Adriano Ferreira for providing two very useful patches.

Copyright 2007 Curtis "Ovid" Poe, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.