Curtis "Ovid" Poe > Sub-Information-0.10 > Sub::Information

Download:
Sub-Information-0.10.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.10   Source  

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.

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.

syntax highlighting: