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 ...
Scalar::Util
Sub::Identify
Data::Dump::Streamer
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:
inspect
Sub::Information
as => 'other_func'
use Sub::Information; # exports 'inspect' my $info = inspect($coderef);
Or:
use Sub::Information (); # don't import anything my $info = Sub::Information->new($coderef);
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.
new
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.
address
my $address = $info->address;
Returns the memory address, in decimal, of the original code reference.
From: Scalar::Util::refaddr
Scalar::Util::refaddr
blessed
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
Scalar::Util::blessed
code
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
Data::Dump::Streamer::Dump
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.
Devel::Peek::Dump
From: Devel::Peek
Devel::Peek
fullname
my $fullname = $info->fullname;
Returns the fully qualified subroutine name (package + subname) of the coderef.
From: Sub::Identify::sub_fullname
Sub::Identify::sub_fullname
name
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:
__ANON__
local *__ANON__ = 'name::of::anonymous::subroutine';
From: Sub::Identify::sub_name
Sub::Identify::sub_name
package
my $package = $info->package;
Returns the name of the package the subroutine was declared in.
From: Sub::Identify::stash_name
Sub::Identify::stash_name
variables
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.
my
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).
variables()
The returned values are not cached.
From: PadWalker::peek_sub
PadWalker::peek_sub
line
my $line_number = $info->line;
Returns the approximate line number where the sub was declared. This is experimental.
From : B
B
file
my $file_name = $info->file;
Returns the file name where the sub was declared. This is experimental.
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>
<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.
bug-sub-information@rt.cpan.org
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::Size
PadWalker
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.
To install Sub::Information, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sub::Information
CPAN shell
perl -MCPAN -e shell install Sub::Information
For more information on module installation, please visit the detailed CPAN module installation guide.