Filename | /Users/ap13/perl5/lib/perl5/Sub/Install.pm |
Statements | Executed 5245 statements in 13.5ms |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
323 | 5 | 3 | 4.41ms | 11.6ms | __ANON__[:132] | Sub::Install::
323 | 1 | 1 | 4.25ms | 5.85ms | __ANON__[:175] | Sub::Install::
323 | 1 | 1 | 1.60ms | 1.60ms | __ANON__[:187] | Sub::Install::
323 | 1 | 1 | 1.14ms | 1.33ms | _CODELIKE | Sub::Install::
1 | 1 | 1 | 140µs | 169µs | BEGIN@4 | Sub::Install::
1 | 1 | 1 | 73µs | 138µs | BEGIN@190 | Sub::Install::
5 | 5 | 5 | 47µs | 180µs | __ANON__[:284] | Sub::Install::
2 | 2 | 2 | 28µs | 28µs | exporter | Sub::Install::
1 | 1 | 1 | 27µs | 42µs | BEGIN@3 | Sub::Install::
3 | 3 | 1 | 26µs | 29µs | _do_with_warn | Sub::Install::
1 | 1 | 1 | 22µs | 29µs | BEGIN@139 | Sub::Install::
1 | 1 | 1 | 22µs | 36µs | BEGIN@287 | Sub::Install::
1 | 1 | 1 | 18µs | 106µs | BEGIN@6 | Sub::Install::
3 | 3 | 1 | 17µs | 17µs | __ANON__[:176] | Sub::Install::
1 | 1 | 1 | 15µs | 44µs | BEGIN@184 | Sub::Install::
3 | 3 | 1 | 14µs | 14µs | CORE:qr (opcode) | Sub::Install::
2 | 2 | 1 | 12µs | 12µs | _build_public_installer | Sub::Install::
1 | 1 | 1 | 11µs | 18µs | BEGIN@148 | Sub::Install::
3 | 3 | 1 | 11µs | 11µs | _installer | Sub::Install::
1 | 1 | 1 | 6µs | 6µs | BEGIN@7 | Sub::Install::
0 | 0 | 0 | 0s | 0s | __ANON__[:156] | Sub::Install::
0 | 0 | 0 | 0s | 0s | __ANON__[:173] | Sub::Install::
0 | 0 | 0 | 0s | 0s | __ANON__[:250] | Sub::Install::
0 | 0 | 0 | 0s | 0s | _name_of_code | Sub::Install::
0 | 0 | 0 | 0s | 0s | install_installers | Sub::Install::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package Sub::Install; | ||||
2 | |||||
3 | 2 | 44µs | 2 | 56µs | # spent 42µs (27+15) within Sub::Install::BEGIN@3 which was called:
# once (27µs+15µs) by Data::OptList::BEGIN@11 at line 3 # spent 42µs making 1 call to Sub::Install::BEGIN@3
# spent 15µs making 1 call to warnings::import |
4 | 2 | 54µs | 2 | 198µs | # spent 169µs (140+29) within Sub::Install::BEGIN@4 which was called:
# once (140µs+29µs) by Data::OptList::BEGIN@11 at line 4 # spent 169µs making 1 call to Sub::Install::BEGIN@4
# spent 29µs making 1 call to strict::import |
5 | |||||
6 | 2 | 42µs | 2 | 194µs | # spent 106µs (18+88) within Sub::Install::BEGIN@6 which was called:
# once (18µs+88µs) by Data::OptList::BEGIN@11 at line 6 # spent 106µs making 1 call to Sub::Install::BEGIN@6
# spent 88µs making 1 call to Exporter::import |
7 | 2 | 666µs | 1 | 6µs | # spent 6µs within Sub::Install::BEGIN@7 which was called:
# once (6µs+0s) by Data::OptList::BEGIN@11 at line 7 # spent 6µs making 1 call to Sub::Install::BEGIN@7 |
8 | |||||
9 | =head1 NAME | ||||
10 | |||||
11 | Sub::Install - install subroutines into packages easily | ||||
12 | |||||
13 | =head1 VERSION | ||||
14 | |||||
15 | version 0.926 | ||||
16 | |||||
17 | =cut | ||||
18 | |||||
19 | 1 | 1µs | our $VERSION = '0.926'; | ||
20 | |||||
21 | =head1 SYNOPSIS | ||||
22 | |||||
23 | use Sub::Install; | ||||
24 | |||||
25 | Sub::Install::install_sub({ | ||||
26 | code => sub { ... }, | ||||
27 | into => $package, | ||||
28 | as => $subname | ||||
29 | }); | ||||
30 | |||||
31 | =head1 DESCRIPTION | ||||
32 | |||||
33 | This module makes it easy to install subroutines into packages without the | ||||
34 | unslightly mess of C<no strict> or typeglobs lying about where just anyone can | ||||
35 | see them. | ||||
36 | |||||
37 | =head1 FUNCTIONS | ||||
38 | |||||
39 | =head2 install_sub | ||||
40 | |||||
41 | Sub::Install::install_sub({ | ||||
42 | code => \&subroutine, | ||||
43 | into => "Finance::Shady", | ||||
44 | as => 'launder', | ||||
45 | }); | ||||
46 | |||||
47 | This routine installs a given code reference into a package as a normal | ||||
48 | subroutine. The above is equivalent to: | ||||
49 | |||||
50 | no strict 'refs'; | ||||
51 | *{"Finance::Shady" . '::' . "launder"} = \&subroutine; | ||||
52 | |||||
53 | If C<into> is not given, the sub is installed into the calling package. | ||||
54 | |||||
55 | If C<code> is not a code reference, it is looked for as an existing sub in the | ||||
56 | package named in the C<from> parameter. If C<from> is not given, it will look | ||||
57 | in the calling package. | ||||
58 | |||||
59 | If C<as> is not given, and if C<code> is a name, C<as> will default to C<code>. | ||||
60 | If C<as> is not given, but if C<code> is a code ref, Sub::Install will try to | ||||
61 | find the name of the given code ref and use that as C<as>. | ||||
62 | |||||
63 | That means that this code: | ||||
64 | |||||
65 | Sub::Install::install_sub({ | ||||
66 | code => 'twitch', | ||||
67 | from => 'Person::InPain', | ||||
68 | into => 'Person::Teenager', | ||||
69 | as => 'dance', | ||||
70 | }); | ||||
71 | |||||
72 | is the same as: | ||||
73 | |||||
74 | package Person::Teenager; | ||||
75 | |||||
76 | Sub::Install::install_sub({ | ||||
77 | code => Person::InPain->can('twitch'), | ||||
78 | as => 'dance', | ||||
79 | }); | ||||
80 | |||||
81 | =head2 reinstall_sub | ||||
82 | |||||
83 | This routine behaves exactly like C<L</install_sub>>, but does not emit a | ||||
84 | warning if warnings are on and the destination is already defined. | ||||
85 | |||||
86 | =cut | ||||
87 | |||||
88 | sub _name_of_code { | ||||
89 | my ($code) = @_; | ||||
90 | require B; | ||||
91 | my $name = B::svref_2object($code)->GV->NAME; | ||||
92 | return $name unless $name =~ /\A__ANON__/; | ||||
93 | return; | ||||
94 | } | ||||
95 | |||||
96 | # See also Params::Util, to which this code was donated. | ||||
97 | # spent 1.33ms (1.14+192µs) within Sub::Install::_CODELIKE which was called 323 times, avg 4µs/call:
# 323 times (1.14ms+192µs) by Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:132] at line 117, avg 4µs/call | ||||
98 | 323 | 1.53ms | 324 | 192µs | (Scalar::Util::reftype($_[0])||'') eq 'CODE' # spent 191µs making 323 calls to Scalar::Util::reftype, avg 590ns/call
# spent 2µs making 1 call to Scalar::Util::blessed |
99 | || Scalar::Util::blessed($_[0]) | ||||
100 | && (overload::Method($_[0],'&{}') ? $_[0] : undef); | ||||
101 | } | ||||
102 | |||||
103 | # do the heavy lifting | ||||
104 | sub _build_public_installer { | ||||
105 | 4 | 22µs | my ($installer) = @_; | ||
106 | |||||
107 | # spent 11.6ms (4.41+7.19) within Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:132] which was called 323 times, avg 36µs/call:
# 314 times (4.17ms+6.79ms) by Sub::Exporter::default_installer at line 442 of Sub/Exporter.pm, avg 35µs/call
# 3 times (82µs+150µs) by Package::DeprecationManager::import at line 29 of Package/DeprecationManager.pm, avg 77µs/call
# 3 times (44µs+70µs) by Package::DeprecationManager::import at line 37 of Package/DeprecationManager.pm, avg 38µs/call
# 2 times (54µs+97µs) by Sub::Exporter::setup_exporter at line 198 of Sub/Exporter.pm, avg 76µs/call
# once (54µs+79µs) by Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:284] at line 282 | ||||
108 | 2910 | 3.69ms | my ($arg) = @_; | ||
109 | my ($calling_pkg) = caller(0); | ||||
110 | |||||
111 | # I'd rather use ||= but I'm whoring for Devel::Cover. | ||||
112 | for (qw(into from)) { $arg->{$_} = $calling_pkg unless $arg->{$_} } | ||||
113 | |||||
114 | # This is the only absolutely required argument, in many cases. | ||||
115 | Carp::croak "named argument 'code' is not optional" unless $arg->{code}; | ||||
116 | |||||
117 | 323 | 1.33ms | if (_CODELIKE($arg->{code})) { # spent 1.33ms making 323 calls to Sub::Install::_CODELIKE, avg 4µs/call | ||
118 | $arg->{as} ||= _name_of_code($arg->{code}); | ||||
119 | } else { | ||||
120 | 1 | 2µs | Carp::croak # spent 2µs making 1 call to UNIVERSAL::can | ||
121 | "couldn't find subroutine named $arg->{code} in package $arg->{from}" | ||||
122 | unless my $code = $arg->{from}->can($arg->{code}); | ||||
123 | |||||
124 | $arg->{as} = $arg->{code} unless $arg->{as}; | ||||
125 | $arg->{code} = $code; | ||||
126 | } | ||||
127 | |||||
128 | Carp::croak "couldn't determine name under which to install subroutine" | ||||
129 | unless $arg->{as}; | ||||
130 | |||||
131 | 323 | 5.85ms | $installer->(@$arg{qw(into as code) }); # spent 5.85ms making 323 calls to Sub::Install::__ANON__[Sub/Install.pm:175], avg 18µs/call | ||
132 | } | ||||
133 | } | ||||
134 | |||||
135 | # do the ugly work | ||||
136 | |||||
137 | 1 | 100ns | my $_misc_warn_re; | ||
138 | 1 | 0s | my $_redef_warn_re; | ||
139 | # spent 29µs (22+7) within Sub::Install::BEGIN@139 which was called:
# once (22µs+7µs) by Data::OptList::BEGIN@11 at line 145 | ||||
140 | 2 | 32µs | 1 | 4µs | $_misc_warn_re = qr/ # spent 4µs making 1 call to Sub::Install::CORE:qr |
141 | Prototype\ mismatch:\ sub\ .+? | | ||||
142 | Constant subroutine \S+ redefined | ||||
143 | /x; | ||||
144 | 1 | 2µs | $_redef_warn_re = qr/Subroutine\ \S+\ redefined/x; # spent 2µs making 1 call to Sub::Install::CORE:qr | ||
145 | 1 | 60µs | 1 | 29µs | } # spent 29µs making 1 call to Sub::Install::BEGIN@139 |
146 | |||||
147 | 1 | 100ns | my $eow_re; | ||
148 | 1 | 426µs | 2 | 25µs | # spent 18µs (11+7) within Sub::Install::BEGIN@148 which was called:
# once (11µs+7µs) by Data::OptList::BEGIN@11 at line 148 # spent 18µs making 1 call to Sub::Install::BEGIN@148
# spent 7µs making 1 call to Sub::Install::CORE:qr |
149 | |||||
150 | sub _do_with_warn { | ||||
151 | 14 | 36µs | my ($arg) = @_; | ||
152 | my $code = delete $arg->{code}; | ||||
153 | my $wants_code = sub { | ||||
154 | 6 | 25µs | my $code = shift; | ||
155 | # spent 5.85ms (4.25+1.60) within Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:175] which was called 323 times, avg 18µs/call:
# 323 times (4.25ms+1.60ms) by Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:132] at line 131, avg 18µs/call | ||||
156 | 969 | 4.00ms | my $warn = $SIG{__WARN__} ? $SIG{__WARN__} : sub { warn @_ }; ## no critic | ||
157 | local $SIG{__WARN__} = sub { | ||||
158 | my ($error) = @_; | ||||
159 | for (@{ $arg->{suppress} }) { | ||||
160 | return if $error =~ $_; | ||||
161 | } | ||||
162 | for (@{ $arg->{croak} }) { | ||||
163 | if (my ($base_error) = $error =~ /\A($_) $eow_re/x) { | ||||
164 | Carp::croak $base_error; | ||||
165 | } | ||||
166 | } | ||||
167 | for (@{ $arg->{carp} }) { | ||||
168 | if (my ($base_error) = $error =~ /\A($_) $eow_re/x) { | ||||
169 | return $warn->(Carp::shortmess $base_error); | ||||
170 | } | ||||
171 | } | ||||
172 | ($arg->{default} || $warn)->($error); | ||||
173 | }; | ||||
174 | 323 | 1.60ms | $code->(@_); # spent 1.60ms making 323 calls to Sub::Install::__ANON__[Sub/Install.pm:187], avg 5µs/call | ||
175 | }; | ||||
176 | }; | ||||
177 | 1 | 4µs | return $wants_code->($code) if $code; # spent 4µs making 1 call to Sub::Install::__ANON__[Sub/Install.pm:176] | ||
178 | return $wants_code; | ||||
179 | } | ||||
180 | |||||
181 | sub _installer { | ||||
182 | # spent 1.60ms within Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:187] which was called 323 times, avg 5µs/call:
# 323 times (1.60ms+0s) by Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:175] at line 174, avg 5µs/call | ||||
183 | 969 | 1.91ms | my ($pkg, $name, $code) = @_; | ||
184 | 2 | 235µs | 2 | 73µs | # spent 44µs (15+29) within Sub::Install::BEGIN@184 which was called:
# once (15µs+29µs) by Data::OptList::BEGIN@11 at line 184 # spent 44µs making 1 call to Sub::Install::BEGIN@184
# spent 29µs making 1 call to strict::unimport |
185 | *{"$pkg\::$name"} = $code; | ||||
186 | return $code; | ||||
187 | } | ||||
188 | 3 | 20µs | } | ||
189 | |||||
190 | # spent 138µs (73+65) within Sub::Install::BEGIN@190 which was called:
# once (73µs+65µs) by Data::OptList::BEGIN@11 at line 208 | ||||
191 | 5 | 31µs | 1 | 9µs | *_ignore_warnings = _do_with_warn({ # spent 9µs making 1 call to Sub::Install::_do_with_warn |
192 | carp => [ $_misc_warn_re, $_redef_warn_re ] | ||||
193 | }); | ||||
194 | |||||
195 | 3 | 20µs | *install_sub = _build_public_installer(_ignore_warnings(_installer)); # spent 9µs making 1 call to Sub::Install::__ANON__[Sub/Install.pm:176]
# spent 7µs making 1 call to Sub::Install::_build_public_installer
# spent 4µs making 1 call to Sub::Install::_installer | ||
196 | |||||
197 | 1 | 6µs | *_carp_warnings = _do_with_warn({ # spent 6µs making 1 call to Sub::Install::_do_with_warn | ||
198 | carp => [ $_misc_warn_re ], | ||||
199 | suppress => [ $_redef_warn_re ], | ||||
200 | }); | ||||
201 | |||||
202 | 3 | 13µs | *reinstall_sub = _build_public_installer(_carp_warnings(_installer)); # spent 5µs making 1 call to Sub::Install::_build_public_installer
# spent 4µs making 1 call to Sub::Install::__ANON__[Sub/Install.pm:176]
# spent 4µs making 1 call to Sub::Install::_installer | ||
203 | |||||
204 | 2 | 18µs | *_install_fatal = _do_with_warn({ # spent 14µs making 1 call to Sub::Install::_do_with_warn
# spent 3µs making 1 call to Sub::Install::_installer | ||
205 | code => _installer, | ||||
206 | croak => [ $_redef_warn_re ], | ||||
207 | }); | ||||
208 | 1 | 461µs | 1 | 138µs | } # spent 138µs making 1 call to Sub::Install::BEGIN@190 |
209 | |||||
210 | =head2 install_installers | ||||
211 | |||||
212 | This routine is provided to allow Sub::Install compatibility with | ||||
213 | Sub::Installer. It installs C<install_sub> and C<reinstall_sub> methods into | ||||
214 | the package named by its argument. | ||||
215 | |||||
216 | Sub::Install::install_installers('Code::Builder'); # just for us, please | ||||
217 | Code::Builder->install_sub({ name => $code_ref }); | ||||
218 | |||||
219 | Sub::Install::install_installers('UNIVERSAL'); # feeling lucky, punk? | ||||
220 | Anything::At::All->install_sub({ name => $code_ref }); | ||||
221 | |||||
222 | The installed installers are similar, but not identical, to those provided by | ||||
223 | Sub::Installer. They accept a single hash as an argument. The key/value pairs | ||||
224 | are used as the C<as> and C<code> parameters to the C<install_sub> routine | ||||
225 | detailed above. The package name on which the method is called is used as the | ||||
226 | C<into> parameter. | ||||
227 | |||||
228 | Unlike Sub::Installer's C<install_sub> will not eval strings into code, but | ||||
229 | will look for named code in the calling package. | ||||
230 | |||||
231 | =cut | ||||
232 | |||||
233 | sub install_installers { | ||||
234 | my ($into) = @_; | ||||
235 | |||||
236 | for my $method (qw(install_sub reinstall_sub)) { | ||||
237 | my $code = sub { | ||||
238 | my ($package, $subs) = @_; | ||||
239 | my ($caller) = caller(0); | ||||
240 | my $return; | ||||
241 | for (my ($name, $sub) = %$subs) { | ||||
242 | $return = Sub::Install->can($method)->({ | ||||
243 | code => $sub, | ||||
244 | from => $caller, | ||||
245 | into => $package, | ||||
246 | as => $name | ||||
247 | }); | ||||
248 | } | ||||
249 | return $return; | ||||
250 | }; | ||||
251 | install_sub({ code => $code, into => $into, as => $method }); | ||||
252 | } | ||||
253 | } | ||||
254 | |||||
255 | =head1 EXPORTS | ||||
256 | |||||
257 | Sub::Install exports C<install_sub> and C<reinstall_sub> only if they are | ||||
258 | requested. | ||||
259 | |||||
260 | =head2 exporter | ||||
261 | |||||
262 | Sub::Install has a never-exported subroutine called C<exporter>, which is used | ||||
263 | to implement its C<import> routine. It takes a hashref of named arguments, | ||||
264 | only one of which is currently recognize: C<exports>. This must be an arrayref | ||||
265 | of subroutines to offer for export. | ||||
266 | |||||
267 | This routine is mainly for Sub::Install's own consumption. Instead, consider | ||||
268 | L<Sub::Exporter>. | ||||
269 | |||||
270 | =cut | ||||
271 | |||||
272 | # spent 28µs within Sub::Install::exporter which was called 2 times, avg 14µs/call:
# once (14µs+0s) by Data::OptList::BEGIN@100 at line 101 of Data/OptList.pm
# once (14µs+0s) by Sub::Install::BEGIN@287 at line 287 | ||||
273 | 6 | 40µs | my ($arg) = @_; | ||
274 | |||||
275 | my %is_exported = map { $_ => undef } @{ $arg->{exports} }; | ||||
276 | |||||
277 | # spent 180µs (47+133) within Sub::Install::__ANON__[/Users/ap13/perl5/lib/perl5/Sub/Install.pm:284] which was called 5 times, avg 36µs/call:
# once (20µs+133µs) by Class::Load::BEGIN@8 at line 8 of Class/Load.pm
# once (8µs+0s) by Moose::Util::BEGIN@8 at line 8 of Moose/Util.pm
# once (7µs+0s) by Package::DeprecationManager::BEGIN@12 at line 12 of Package/DeprecationManager.pm
# once (6µs+0s) by Moose::Meta::Class::BEGIN@8 at line 8 of Moose/Meta/Class.pm
# once (5µs+0s) by Class::MOP::BEGIN@12 at line 12 of Class/MOP.pm | ||||
278 | 17 | 54µs | my $class = shift; | ||
279 | my $target = caller; | ||||
280 | for (@_) { | ||||
281 | Carp::croak "'$_' is not exported by $class" if !exists $is_exported{$_}; | ||||
282 | 1 | 133µs | install_sub({ code => $_, from => $class, into => $target }); # spent 133µs making 1 call to Sub::Install::__ANON__[Sub/Install.pm:132] | ||
283 | } | ||||
284 | } | ||||
285 | } | ||||
286 | |||||
287 | 1 | 99µs | 2 | 50µs | # spent 36µs (22+14) within Sub::Install::BEGIN@287 which was called:
# once (22µs+14µs) by Data::OptList::BEGIN@11 at line 287 # spent 36µs making 1 call to Sub::Install::BEGIN@287
# spent 14µs making 1 call to Sub::Install::exporter |
288 | |||||
289 | =head1 SEE ALSO | ||||
290 | |||||
291 | =over | ||||
292 | |||||
293 | =item L<Sub::Installer> | ||||
294 | |||||
295 | This module is (obviously) a reaction to Damian Conway's Sub::Installer, which | ||||
296 | does the same thing, but does it by getting its greasy fingers all over | ||||
297 | UNIVERSAL. I was really happy about the idea of making the installation of | ||||
298 | coderefs less ugly, but I couldn't bring myself to replace the ugliness of | ||||
299 | typeglobs and loosened strictures with the ugliness of UNIVERSAL methods. | ||||
300 | |||||
301 | =item L<Sub::Exporter> | ||||
302 | |||||
303 | This is a complete Exporter.pm replacement, built atop Sub::Install. | ||||
304 | |||||
305 | =back | ||||
306 | |||||
307 | =head1 AUTHOR | ||||
308 | |||||
309 | Ricardo Signes, C<< <rjbs@cpan.org> >> | ||||
310 | |||||
311 | Several of the tests are adapted from tests that shipped with Damian Conway's | ||||
312 | Sub-Installer distribution. | ||||
313 | |||||
314 | =head1 BUGS | ||||
315 | |||||
316 | Please report any bugs or feature requests through the web interface at | ||||
317 | L<http://rt.cpan.org>. I will be notified, and then you'll automatically be | ||||
318 | notified of progress on your bug as I make changes. | ||||
319 | |||||
320 | =head1 COPYRIGHT | ||||
321 | |||||
322 | Copyright 2005-2006 Ricardo Signes, All Rights Reserved. | ||||
323 | |||||
324 | This program is free software; you can redistribute it and/or modify it | ||||
325 | under the same terms as Perl itself. | ||||
326 | |||||
327 | =cut | ||||
328 | |||||
329 | 1 | 8µs | 1; | ||
sub Sub::Install::CORE:qr; # opcode |