/ 
Sub-Information-0.10
River stage one • 1 direct dependent • 1 total dependent
/ Sub::Information

NAME

Sub::Information - Get subroutine information

VERSION

Version 0.10

SYNOPSIS

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.

DESCRIPTION

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.

EXPORT

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);

FUNCTIONS

inspect

my $info = inspect($coderef);

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

METHODS

Class Methods

new

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

Returns a new Sub::Information object.

Instance Methods

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

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

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

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

fullname

my $fullname = $info->fullname;

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

From: 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:

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

From: 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

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.

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

line

my $line_number = $info->line;

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

From : B

file

my $file_name = $info->file;

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

From : B

CAVEATS

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.

AUTHOR

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

BUGS

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.

TODO

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

SEE ALSO

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

THANKS

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

COPYRIGHT & LICENSE

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.