blib/lib/B/Hooks/AtRuntime.pm

filter: Statementstmt 100% 65 / 65 Branchbran 91.6% 11 / 12 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 17 / 17 Podpod 40.0% 2 / 5 totaltotal 95.9% 95 / 99 CC 7 SCAR 5.3
CC
7
Cov
99%
__ANON__
3.0
find_hooks
3.0
BEGIN
2.0
CRAP 1.7
« Build ↑ Summary tlib/t/D.pm »
1 package B::Hooks::AtRuntime;
2  
3 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 7 ▶use XSLoader;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 7 ▶use Sub::Name "subname";
Subroutine BEGIN: called CC=1 SCAR=0.0
8 7 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 7 ▶use parent "Exporter::Tiny";
Subroutine BEGIN: called CC=1 SCAR=0.0
11 7 our @EXPORT = qw/at_runtime/;
12 7 our @EXPORT_OK = qw/at_runtime after_runtime lex_stuff/;
13  
14 BEGIN {
15 7 ▶ our $VERSION = "6";
Subroutine BEGIN: called CC=1 SCAR=0.0
16 7 XSLoader::load __PACKAGE__, $VERSION;
17 }
18  
19 use constant USE_FILTER =>
20 defined $ENV{PERL_B_HOOKS_ATRUNTIME}
21 7 ▶ ? $ENV{PERL_B_HOOKS_ATRUNTIME} eq "filter"
Branch: 1 branch
BranchTrueFalseTotal
defined $ENV{'PERL_B_HOOKS_ATRUNTIME'} ? : 1 6 7
22 7 ▶ : not defined &lex_stuff;
Subroutine BEGIN: called CC=2 SCAR=6.9
23  
24 7 if (USE_FILTER) {
25 require Filter::Util::Call;
26  
27 # This isn't an exact replacement: it inserts the text at the start
28 # of the next line, rather than immediately after the current BEGIN.
29 #
30 # In theory I could use B::Hooks::Parser, which aims to emulate
31 # lex_stuff on older perls, but that uses a source filter to ensure
32 # PL_linebuf has some extra space in it (since it can't be
33 # reallocated without adjusting pointers we can't get to). This
34 # means BHP::setup needs to be called at least one source line
35 # before we want to insert any text (so the filter has a chance to
36 # run), which makes it precisely useless for our purposes :(.
37  
38 7 ▶ no warnings "redefine";
Subroutine BEGIN: called CC=1 SCAR=0.0
39 *lex_stuff = subname "lex_stuff", sub {
40 55 ▶ my ($str) = @_;
Subroutine __ANON__: called CC=3 SCAR=11.0
41  
42 55 ▶ compiling_string_eval() and croak
Branch: 1 branch
BranchTrueFalseTotal
compiling_string_eval() and croak("Can't stuff into a string eval") 0 55 55
43 "Can't stuff into a string eval";
44  
45 55 ▶ if (defined(my $extra = remaining_text())) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $extra = remaining_text())) 1 54 55
46 1 $extra =~ s/\n+\z//;
47 1 carp "Extra text '$extra' after call to lex_stuff";
48 }
49  
50 Filter::Util::Call::filter_add(sub {
51 55 ▶ $_ = $str;
Subroutine __ANON__: called CC=1 SCAR=0.0
52 55 Filter::Util::Call::filter_del();
53 55 return 1;
54 55 });
55 };
56 }
57  
58 7 my @Hooks;
59  
60 sub replace_hooks {
61 196 ▶ my ($new) = @_;
Subroutine replace_hooks: called CC=2 SCAR=6.9
Pod undocumented
62  
63 # By deleting the stash entry we ensure the only ref to the glob is
64 # through the optree it was compiled into. This means that if that
65 # optree is ever freed, the glob will disappear along with anything
66 # closed over by the user's callbacks.
67 196 delete $B::Hooks::AtRuntime::{hooks};
68  
69 7 ▶ no strict "refs";
Subroutine BEGIN: called CC=1 SCAR=0.0
70 196 ▶ $new and *{"hooks"} = $new;
Branch: 1 branch
BranchTrueFalseTotal
$new and *{"hooks";} = $new 99 97 196
71 }
72  
73 sub clear {
74 98 ▶ my ($depth) = @_;
Subroutine clear: called CC=1 SCAR=0.0
Pod undocumented
75 98 $Hooks[$depth] = undef;
76 98 replace_hooks $Hooks[$depth - 1];
77 }
78  
79 sub find_hooks {
80 118 ▶ USE_FILTER and compiling_string_eval() and croak
Subroutine find_hooks: called CC=3 SCAR=11.0
Pod undocumented
81 "Can't use at_runtime from a string eval";
82  
83 116 ▶ my $depth = count_BEGINs()
Branch: 1 branch
BranchTrueFalseTotal
my $depth = count_BEGINs() or croak("You must call at_runtime at compile time") 3 115 118
84 or croak "You must call at_runtime at compile time";
85  
86 114 my $hk;
87 114 ▶ unless ($hk = $Hooks[$depth]) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($hk = $Hooks[$depth]) 52 63 115
88 # Close over an array of callbacks so we don't need to keep
89 # stuffing text into the buffer.
90 98 my @hooks;
91 98 $hk = $Hooks[$depth] = \@hooks;
92 98 replace_hooks $hk;
93  
94 # This must be all on one line, so we don't mess up perl's idea
95 # of the current line number.
96 98 lex_stuff(q{B::Hooks::AtRuntime::run(@B::Hooks::AtRuntime::hooks);} .
97 "BEGIN{B::Hooks::AtRuntime::clear($depth)}");
98 }
99  
100 114 return $hk;
101 }
102  
103 sub at_runtime (&) {
104 109 ▶ my ($cv) = @_;
Subroutine at_runtime: called CC=1 SCAR=0.0
Pod documented
105 109 my $hk = find_hooks;
106 105 push @$hk, subname scalar(caller) . "::(at_runtime)", $cv;
107 }
108  
109 sub after_runtime (&) {
110 9 ▶ my ($cv) = @_;
Subroutine after_runtime: called CC=1 SCAR=0.0
Pod documented
111 9 my $hk = find_hooks;
112 9 push @$hk, \subname scalar(caller) . "::(after_runtime)", $cv;
113 }
114  
115 7 1;
116  
117 =head1 NAME
118  
119 B::Hooks::AtRuntime - Lower blocks from compile time to runtime
120  
121 =head1 SYNOPSIS
122  
123 # My::Module
124 sub import {
125 at_runtime { warn "TWO" };
126 }
127  
128 # elsewhere
129 warn "ONE";
130 use My::Module;
131 warn "THREE";
132  
133 =head1 DESCRIPTION
134  
135 This module allows code that runs at compile-time to do something at
136 runtime. A block passed to C<at_runtime> gets compiled into the code
137 that's currently compiling, and will be called when control reaches that
138 point at runtime. In the example in the SYNOPSIS, the warnings will
139 occur in order, and if that section of code runs more than once, so will
140 all three warnings.
141  
142 =head2 at_runtime
143  
144 at_runtime { ... };
145  
146 This sets up a block to be called at runtime. It must be called from
147 within a C<BEGIN> block or C<use>, otherwise there will be no compiling
148 code to insert into. The innermost enclosing C<BEGIN> block, which would
149 normally be invisible once the section of code it is in has been
150 compiled, will effectively leave behind a call to the given block. For
151 example, this
152  
153 BEGIN { warn "ONE" } warn "one";
154 BEGIN { warn "TWO"; at_runtime { warn "two" }; }
155  
156 will warn "ONE TWO one two", with the last warning 'lowered' out of the
157 C<BEGIN> block and back into the runtime control flow.
158  
159 This applies even if calls to other subs intervene between C<BEGIN> and
160 C<at_runtime>. The lowered block is always inserted at the innermost
161 point where perl is still compiling, so something like this
162  
163 # My::Module
164 sub also_at_runtime {
165 my ($msg) = @_;
166 at_runtime { warn $msg };
167 }
168  
169 sub import {
170 my ($class, $one, $two) = @_;
171 at_runtime { warn $one };
172 also_at_runtime $two;
173 }
174  
175 #
176 warn "one";
177 BEGIN { at_runtime { warn "two" } }
178 BEGIN { My::Module::also_at_runtime "three" }
179 use My::Module "four", "five";
180  
181 will still put the warnings in order.
182  
183 =head2 after_runtime
184  
185 after_runtime { ... };
186  
187 This arranges to call the block when runtime execution reaches the end
188 of the surrounding compiling scope. For example, this will warn in order:
189  
190 warn "one";
191 {
192 warn "two";
193 BEGIN {
194 after_runtime { warn "five" };
195 at_runtime { warn "three" };
196 }
197 warn "four";
198 }
199 warn "six";
200  
201 No exception handling is done, so if the block throws an exception it
202 will propogate normally into the surrounding code. (This is different
203 from the way perl calls C<DESTROY> methods, which have their exceptions
204 converted into warnings.)
205  
206 Note that the block will be called during stack unwind, so the package,
207 file and line information for C<caller 0> will be the point where the
208 surrounding scope was called. This is the same as a C<DESTROY> method.
209  
210 =head2 Object lifetimes
211  
212 C<at_runtime> and C<after_runtime> are careful to make sure the
213 anonymous sub passed to them doesn't live any longer than it has to.
214 That sub, and any lexicals it has closed over, will be destroyed when
215 the optree it has been compiled into is destroyed: for code outside any
216 sub, this is when the containing file or eval finishes executing; for
217 named subs, this is when the sub is un- or redefined; and for anonymous
218 subs, this is not until both the code containing the C<sub { }>
219 expression and all instances generated by that expression have been
220 destroyed.
221  
222 =head2 lex_stuff
223
224 lex_stuff $text;
225  
226 This is the function underlying C<at_runtime>. Under perl 5.12 and
227 later, this is just a Perl wrapper for the core function
228 L<lex_stuff_sv|perlapi/lex_stuff_sv>. Under earlier versions it is
229 implemented with a source filter, with some limitations, see L</CAVEATS>
230 below.
231  
232 This function pushes text into perl's line buffer, at the point perl is
233 currently compiling. You should probably not try to push too much at
234 once without giving perl a chance to compile it. If C<$text> contains
235 newlines, they will affect perl's idea of the current line number. You
236 probably shouldn't use this function at all.
237  
238 =head2 Exports
239  
240 B::Hooks::AtRuntime uses L<Exporter::Tiny>, so you can customise its
241 exports as described by that module's documentation. C<at_runtime> is
242 exported by default; C<after_runtime> and C<lex_stuff> can be exported
243 on request.
244  
245 =head1 CAVEATS
246  
247 =head2 Incompatible changes from version 1
248  
249 Version 1 used a different implementation for C<at_runtime>, which left
250 an extra scope between the provided block and the code it was compiled
251 into. Version 2 has removed this.
252  
253 =head2 Perls before 5.12
254  
255 Versions of perl before 5.12.0 don't have the C<lex_stuff_sv> function,
256 and don't export enough for it to be possible to emulate it entirely.
257 (L<B::Hooks::Parser> gets as close as it can, and just exactly doesn't
258 quite do what we need for C<at_runtime>.) This means our C<lex_stuff>
259 has to fall back to using a source filter to insert the text, which has
260 a couple of important limitations.
261  
262 =over 4
263  
264 =item * You cannot stuff text into a string C<eval>.
265  
266 String evals aren't affected by source filters, so the stuffed text
267 would end up getting inserted into the innermost compiling scope that
268 B<wasn't> a string eval. Since this would be rather confusing, and
269 different from what 5.12 does, C<lex_stuff> and C<at_runtime> will croak
270 if you try to use them to affect a string eval.
271  
272 =item * Stuffed text appears at the start of the next line.
273  
274 This, unfortunately, is rather annoying. With a filter, the earliest
275 point at which we can insert text is the start of the next line. This
276 means that if there is any text between the closing brace of the
277 C<BEGIN> block or the semicolon of the C<use> that caused the insertion,
278 and the end of the line, the insertion will certainly be in the wrong
279 place and probably cause a syntax error.
280  
281 C<lex_stuff> (and, therefore, C<at_runtime>) will issue a warning if
282 this is going to happen (specifically, if there are any non-space
283 non-comment characters between the point where we want to insert and the
284 point we're forced to settle for), but this may not be something you can
285 entirely control. If you are writing a module like the examples above
286 which calls C<at_runtime> from its C<import> method, what matters is
287 that B<users of your module> not put anything on a line after your
288 module's C<use> statement.
289  
290 =back
291  
292 If you want to use the filter implementation on perl 5.12 (for testing),
293 set C<PERL_B_HOOKS_ATRUNTIME=filter> in the environment. If the filter
294 implementation is in use, C<B::Hooks::AtRuntime::USE_FILTER> will be
295 true.
296  
297 =head1 SEE ALSO
298  
299 L<B::Hooks::Parser> will insert text 'here' in perls before 5.12, but
300 requires a setup step at least one source line in advance.
301  
302 L<Hook::AfterRuntime> uses it to implement something somewhat similar to
303 this module.
304  
305 L<Scope::OnExit> and L<B::Hooks::EndOfScope> provide hooks into
306 different points in the surrounding scope.
307  
308 L<Filter::Util::Call> is the generic interface to the source filtering
309 mechanism.
310  
311 =head1 AUTHOR
312  
313 Ben Morrow <ben@morrow.me.uk>
314  
315 =head1 BUGS
316  
317 Please report any bugs to <bug-B-Hooks-AtRuntime@rt.cpan.org>.
318  
319 =head1 ACKNOWLEDGEMENTS
320  
321 Zefram's work on the core lexer API made this module enormously easier.
322  
323 =head1 COPYRIGHT
324  
325 Copyright 2015 Ben Morrow.
326  
327 Released under the 2-clause BSD licence.
328  
329 =cut
« Build ↑ Summary tlib/t/D.pm »