This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade parent from version 0.232 to 0.234
[perl5.git] / cpan / Scalar-List-Utils / lib / Sub / Util.pm
CommitLineData
d81c2d6a
CBW
1# Copyright (c) 2014 Paul Evans <leonerd@leonerd.org.uk>. All rights reserved.
2# This program is free software; you can redistribute it and/or
3# modify it under the same terms as Perl itself.
4
5package Sub::Util;
6
7use strict;
8use warnings;
9
10require Exporter;
11require List::Util; # as it has the XS
12
13our @ISA = qw( Exporter );
14our @EXPORT_OK = qw(
15 prototype set_prototype
16 subname set_subname
17);
18
46274848 19our $VERSION = "1.41";
d81c2d6a
CBW
20$VERSION = eval $VERSION;
21
22=head1 NAME
23
24Sub::Util - A selection of utility subroutines for subs and CODE references
25
26=head1 SYNOPSIS
27
46274848 28 use Sub::Util qw( prototype set_prototype subname set_subname );
d81c2d6a
CBW
29
30=head1 DESCRIPTION
31
32C<Sub::Util> contains a selection of utility subroutines that are useful for
33operating on subs and CODE references.
34
35The rationale for inclusion in this module is that the function performs some
36work for which an XS implementation is essential because it cannot be
37implemented in Pure Perl, and which is sufficiently-widely used across CPAN
38that its popularity warrants inclusion in a core module, which this is.
39
40=cut
41
42=head1 FUNCTIONS
43
44=cut
45
46=head2 prototype
47
48 my $proto = prototype( $code )
49
46274848
SH
50I<Since version 1.40.>
51
d81c2d6a
CBW
52Returns the prototype of the given C<$code> reference, if it has one, as a
53string. This is the same as the C<CORE::prototype> operator; it is included
54here simply for symmetry and completeness with the other functions.
55
56=cut
57
58sub prototype
59{
60 my ( $code ) = @_;
61 return CORE::prototype( $code );
62}
63
64=head2 set_prototype
65
66 my $code = set_prototype $prototype, $code;
67
68I<Since version 1.40.>
69
70Sets the prototype of the function given by the C<$code> reference, or deletes
71it if C<$prototype> is C<undef>. Returns the C<$code> reference itself.
72
73I<Caution>: This function takes arguments in a different order to the previous
74copy of the code from C<Scalar::Util>. This is to match the order of
75C<set_subname>, and other potential additions in this file. This order has
76been chosen as it allows a neat and simple chaining of other
77C<Sub::Util::set_*> functions as might become available, such as:
78
79 my $code =
80 set_subname name_here =>
81 set_prototype '&@' =>
82 set_attribute ':lvalue' =>
83 sub { ...... };
84
85=cut
86
87=head2 subname
88
89 my $name = subname( $code )
90
91I<Since version 1.40.>
92
93Returns the name of the given C<$code> reference, if it has one. Normal named
94subs will give a fully-qualified name consisting of the package and the
95localname separated by C<::>. Anonymous code references will give C<__ANON__>
96as the localname. If a name has been set using L</set_subname>, this name will
97be returned instead.
98
99This function was inspired by C<sub_fullname> from L<Sub::Identify>. The
100remaining functions that C<Sub::Identify> implements can easily be emulated
101using regexp operations, such as
102
103 sub get_code_info { return (subname $_[0]) =~ m/^(.+)::(.+?)$/ }
104 sub sub_name { return (get_code_info $_[0])[0] }
105 sub stash_name { return (get_code_info $_[0])[1] }
106
107I<Users of Sub::Name beware>: This function is B<not> the same as
108C<Sub::Name::subname>; it returns the existing name of the sub rather than
109changing it. To set or change a name, see instead L</set_subname>.
110
111=cut
112
113=head2 set_subname
114
115 my $code = set_subname $name, $code;
116
117I<Since version 1.40.>
118
119Sets the name of the function given by the C<$code> reference. Returns the
120C<$code> reference itself. If the C<$name> is unqualified, the package of the
121caller is used to qualify it.
122
123This is useful for applying names to anonymous CODE references so that stack
124traces and similar situations, to give a useful name rather than having the
125default of C<__ANON__>. Note that this name is only used for this situation;
126the C<set_subname> will not install it into the symbol table; you will have to
127do that yourself if required.
128
129However, since the name is not used by perl except as the return value of
130C<caller>, for stack traces or similar, there is no actual requirement that
131the name be syntactically valid as a perl function name. This could be used to
132attach extra information that could be useful in debugging stack traces.
133
134This function was copied from C<Sub::Name::subname> and renamed to the naming
135convention of this module.
136
137=cut
138
139=head1 AUTHOR
140
141The general structure of this module was written by Paul Evans
142<leonerd@leonerd.org.uk>.
143
144The XS implementation of L</set_subname> was copied from L<Sub::Name> by
145Matthijs van Duin <xmath@cpan.org>
146
147=cut
148
1491;