AnonymousFox

//usr/local/share/man/man3/Sub::Identify.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Sub::Identify 3"
.TH Sub::Identify 3 "2017-04-11" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sub::Identify \- Retrieve names of code references
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 12
\&    use Sub::Identify \*(Aq:all\*(Aq;
\&    my $subname = sub_name( $some_coderef );
\&    my $packagename = stash_name( $some_coderef );
\&    # or, to get all at once...
\&    my $fully_qualified_name = sub_fullname( $some_coderef );
\&    defined $subname
\&        and say "this coderef points to sub $subname in package $packagename";
\&    my ($file, $line) = get_code_location( $some_coderef );
\&    $file
\&        and say "this coderef is defined at line $line in file $file";
\&    is_sub_constant( $some_coderef )
\&        and say "this coderef points to a constant subroutine";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Sub::Identify\*(C'\fR allows you to retrieve the real name of code references.
.PP
It provides six functions, all of them taking a code reference.
.PP
\&\f(CW\*(C`sub_name\*(C'\fR returns the name of the code reference passed as an
argument (or \f(CW\*(C`_\|_ANON_\|_\*(C'\fR if it's an anonymous code reference),
\&\f(CW\*(C`stash_name\*(C'\fR returns its package, and \f(CW\*(C`sub_fullname\*(C'\fR returns the
concatenation of the two.
.PP
\&\f(CW\*(C`get_code_info\*(C'\fR returns a list of two elements, the package and the
subroutine name (in case of you want both and are worried by the speed.)
.PP
In case of subroutine aliasing, those functions always return the
original name.
.PP
\&\f(CW\*(C`get_code_location\*(C'\fR returns a two-element list containing the file
name and the line number where the subroutine has been defined.
.PP
\&\f(CW\*(C`is_sub_constant\*(C'\fR returns a boolean value indicating whether the
subroutine is a constant or not.
.SS "Pure-Perl version"
.IX Subsection "Pure-Perl version"
By default \f(CW\*(C`Sub::Identify\*(C'\fR tries to load an \s-1XS\s0 implementation of the
\&\f(CW\*(C`get_code_info\*(C'\fR, \f(CW\*(C`get_code_location\*(C'\fR and (on perl versions 5.16.0 and later)
\&\f(CW\*(C`is_sub_constant\*(C'\fR functions, for speed; if that fails, or if the environment
variable \f(CW\*(C`PERL_SUB_IDENTIFY_PP\*(C'\fR is defined to a true value, it will fall
back to a pure perl implementation, that uses perl's introspection mechanism,
provided by the \f(CW\*(C`B\*(C'\fR module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sub::Util, part of the module distribution Scalar::List::Utils
since version 1.40. Since this will be a core module starting with perl
5.22.0, it is encouraged to migrate to Sub::Util when possible.
.PP
Sub::Name
.SH "SOURCE"
.IX Header "SOURCE"
A git repository for the sources is at <https://github.com/rgs/Sub\-Identify>.
.SH "LICENSE"
.IX Header "LICENSE"
(c) Rafael Garcia-Suarez (rgs at consttype dot org) 2005, 2008, 2012, 2014, 2015
.PP
This program is free software; you may redistribute it and/or modify it under
the same terms as Perl itself.