Commit | Line | Data |
---|---|---|
f8881bd9 | 1 | package SelfLoader; |
0a8174e1 | 2 | use 5.008; |
5e1aa25c | 3 | use strict; |
4975ecc9 | 4 | our $VERSION = "1.17"; |
0a8174e1 RGS |
5 | |
6 | # The following bit of eval-magic is necessary to make this work on | |
7 | # perls < 5.009005. | |
8 | use vars qw/$AttrList/; | |
9 | BEGIN { | |
10 | if ($] > 5.009004) { | |
11 | eval <<'NEWERPERL'; | |
12 | use 5.009005; # due to new regexp features | |
09bef843 | 13 | # allow checking for valid ': attrlist' attachments |
5e1aa25c | 14 | # see also AutoSplit |
0a8174e1 | 15 | $AttrList = qr{ |
5e1aa25c RGS |
16 | \s* : \s* |
17 | (?: | |
18 | # one attribute | |
19 | (?> # no backtrack | |
20 | (?! \d) \w+ | |
21 | (?<nested> \( (?: [^()]++ | (?&nested)++ )*+ \) ) ? | |
22 | ) | |
23 | (?: \s* : \s* | \s+ (?! :) ) | |
24 | )* | |
25 | }x; | |
09bef843 | 26 | |
0a8174e1 RGS |
27 | NEWERPERL |
28 | } | |
29 | else { | |
30 | eval <<'OLDERPERL'; | |
31 | # allow checking for valid ': attrlist' attachments | |
32 | # (we use 'our' rather than 'my' here, due to the rather complex and buggy | |
33 | # behaviour of lexicals with qr// and (??{$lex}) ) | |
34 | our $nested; | |
35 | $nested = qr{ \( (?: (?> [^()]+ ) | (??{ $nested }) )* \) }x; | |
36 | our $one_attr = qr{ (?> (?! \d) \w+ (?:$nested)? ) (?:\s*\:\s*|\s+(?!\:)) }x; | |
37 | $AttrList = qr{ \s* : \s* (?: $one_attr )* }x; | |
38 | OLDERPERL | |
39 | } | |
40 | } | |
41 | use Exporter; | |
42 | our @ISA = qw(Exporter); | |
43 | our @EXPORT = qw(AUTOLOAD); | |
44 | sub Version {$VERSION} | |
45 | sub DEBUG () { 0 } | |
46 | ||
47 | my %Cache; # private cache for all SelfLoader's client packages | |
48 | ||
cca8f13b AF |
49 | # in croak and carp, protect $@ from "require Carp;" RT #40216 |
50 | ||
51 | sub croak { { local $@; require Carp; } goto &Carp::croak } | |
52 | sub carp { { local $@; require Carp; } goto &Carp::carp } | |
e3d0cac0 | 53 | |
f8881bd9 | 54 | AUTOLOAD { |
5e1aa25c RGS |
55 | our $AUTOLOAD; |
56 | print STDERR "SelfLoader::AUTOLOAD for $AUTOLOAD\n" if DEBUG; | |
c7675058 | 57 | my $SL_code = $Cache{$AUTOLOAD}; |
bfdd1499 | 58 | my $save = $@; # evals in both AUTOLOAD and _load_stubs can corrupt $@ |
c7675058 | 59 | unless ($SL_code) { |
f8881bd9 AD |
60 | # Maybe this pack had stubs before __DATA__, and never initialized. |
61 | # Or, this maybe an automatic DESTROY method call when none exists. | |
62 | $AUTOLOAD =~ m/^(.*)::/; | |
63 | SelfLoader->_load_stubs($1) unless exists $Cache{"${1}::<DATA"}; | |
c7675058 JG |
64 | $SL_code = $Cache{$AUTOLOAD}; |
65 | $SL_code = "sub $AUTOLOAD { }" | |
66 | if (!$SL_code and $AUTOLOAD =~ m/::DESTROY$/); | |
67 | croak "Undefined subroutine $AUTOLOAD" unless $SL_code; | |
f8881bd9 | 68 | } |
5e1aa25c | 69 | print STDERR "SelfLoader::AUTOLOAD eval: $SL_code\n" if DEBUG; |
bfdd1499 | 70 | |
5ef97ff3 RGS |
71 | { |
72 | no strict; | |
73 | eval $SL_code; | |
74 | } | |
f8881bd9 AD |
75 | if ($@) { |
76 | $@ =~ s/ at .*\n//; | |
77 | croak $@; | |
78 | } | |
bfdd1499 | 79 | $@ = $save; |
f8881bd9 AD |
80 | defined(&$AUTOLOAD) || die "SelfLoader inconsistency error"; |
81 | delete $Cache{$AUTOLOAD}; | |
82 | goto &$AUTOLOAD | |
83 | } | |
84 | ||
85 | sub load_stubs { shift->_load_stubs((caller)[0]) } | |
86 | ||
87 | sub _load_stubs { | |
33235a50 NC |
88 | # $endlines is used by Devel::SelfStubber to capture lines after __END__ |
89 | my($self, $callpack, $endlines) = @_; | |
5e1aa25c | 90 | no strict "refs"; |
f8881bd9 | 91 | my $fh = \*{"${callpack}::DATA"}; |
5e1aa25c | 92 | use strict; |
f8881bd9 AD |
93 | my $currpack = $callpack; |
94 | my($line,$name,@lines, @stubs, $protoype); | |
95 | ||
5e1aa25c | 96 | print STDERR "SelfLoader::load_stubs($callpack)\n" if DEBUG; |
f8881bd9 | 97 | croak("$callpack doesn't contain an __DATA__ token") |
2ef89038 | 98 | unless defined fileno($fh); |
add1a1a3 | 99 | # Protect: fork() shares the file pointer between the parent and the kid |
054149a8 SP |
100 | if(sysseek($fh, tell($fh), 0)) { |
101 | open my $nfh, '<&', $fh or croak "reopen: $!";# dup() the fd | |
4975ecc9 | 102 | close $fh or die "close: $!"; # autocloses, but be paranoid |
054149a8 | 103 | open $fh, '<&', $nfh or croak "reopen2: $!"; # dup() the fd "back" |
4975ecc9 | 104 | close $nfh or die "close after reopen: $!"; # autocloses, but be paranoid |
054149a8 | 105 | } |
f8881bd9 AD |
106 | $Cache{"${currpack}::<DATA"} = 1; # indicate package is cached |
107 | ||
52128c7b | 108 | local($/) = "\n"; |
40da2db3 | 109 | while(defined($line = <$fh>) and $line !~ m/^__END__/) { |
0a8174e1 | 110 | if ($line =~ m/^\s*sub\s+([\w:]+)\s*((?:\([\\\$\@\%\&\*\;]*\))?(?:$AttrList)?)/) { |
f8881bd9 AD |
111 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); |
112 | $protoype = $2; | |
113 | @lines = ($line); | |
114 | if (index($1,'::') == -1) { # simple sub name | |
115 | $name = "${currpack}::$1"; | |
116 | } else { # sub name with package | |
117 | $name = $1; | |
118 | $name =~ m/^(.*)::/; | |
119 | if (defined(&{"${1}::AUTOLOAD"})) { | |
120 | \&{"${1}::AUTOLOAD"} == \&SelfLoader::AUTOLOAD || | |
121 | die 'SelfLoader Error: attempt to specify Selfloading', | |
122 | " sub $name in non-selfloading module $1"; | |
123 | } else { | |
124 | $self->export($1,'AUTOLOAD'); | |
125 | } | |
126 | } | |
127 | } elsif ($line =~ m/^package\s+([\w:]+)/) { # A package declared | |
128 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); | |
129 | $self->_package_defined($line); | |
130 | $name = ''; | |
131 | @lines = (); | |
132 | $currpack = $1; | |
133 | $Cache{"${currpack}::<DATA"} = 1; # indicate package is cached | |
134 | if (defined(&{"${1}::AUTOLOAD"})) { | |
135 | \&{"${1}::AUTOLOAD"} == \&SelfLoader::AUTOLOAD || | |
136 | die 'SelfLoader Error: attempt to specify Selfloading', | |
137 | " package $currpack which already has AUTOLOAD"; | |
138 | } else { | |
139 | $self->export($currpack,'AUTOLOAD'); | |
140 | } | |
141 | } else { | |
142 | push(@lines,$line); | |
143 | } | |
144 | } | |
33235a50 NC |
145 | if (defined($line) && $line =~ /^__END__/) { # __END__ |
146 | unless ($line =~ /^__END__\s*DATA/) { | |
147 | if ($endlines) { | |
148 | # Devel::SelfStubber would like us to capture the lines after | |
149 | # __END__ so it can write out the entire file | |
150 | @$endlines = <$fh>; | |
151 | } | |
152 | close($fh); | |
153 | } | |
154 | } | |
f8881bd9 | 155 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); |
5ef97ff3 | 156 | no strict; |
f8881bd9 AD |
157 | eval join('', @stubs) if @stubs; |
158 | } | |
159 | ||
160 | ||
161 | sub _add_to_cache { | |
162 | my($self,$fullname,$pack,$lines, $protoype) = @_; | |
163 | return () unless $fullname; | |
8878f897 | 164 | carp("Redefining sub $fullname") |
e3d0cac0 | 165 | if exists $Cache{$fullname}; |
f9a01fbf S |
166 | $Cache{$fullname} = join('', "\n\#line 1 \"sub $fullname\"\npackage $pack; ", @$lines); |
167 | #$Cache{$fullname} = join('', "package $pack; ",@$lines); | |
5e1aa25c | 168 | print STDERR "SelfLoader cached $fullname: $Cache{$fullname}" if DEBUG; |
f8881bd9 AD |
169 | # return stub to be eval'd |
170 | defined($protoype) ? "sub $fullname $protoype;" : "sub $fullname;" | |
171 | } | |
172 | ||
173 | sub _package_defined {} | |
174 | ||
175 | 1; | |
176 | __END__ | |
cb1a09d0 | 177 | |
f8881bd9 AD |
178 | =head1 NAME |
179 | ||
180 | SelfLoader - load functions only on demand | |
181 | ||
182 | =head1 SYNOPSIS | |
183 | ||
184 | package FOOBAR; | |
185 | use SelfLoader; | |
3cb6de81 | 186 | |
f8881bd9 | 187 | ... (initializing code) |
3cb6de81 | 188 | |
f8881bd9 AD |
189 | __DATA__ |
190 | sub {.... | |
191 | ||
192 | ||
193 | =head1 DESCRIPTION | |
194 | ||
195 | This module tells its users that functions in the FOOBAR package are to be | |
463e8aa9 | 196 | autoloaded from after the C<__DATA__> token. See also |
197 | L<perlsub/"Autoloading">. | |
f8881bd9 AD |
198 | |
199 | =head2 The __DATA__ token | |
200 | ||
463e8aa9 | 201 | The C<__DATA__> token tells the perl compiler that the perl code |
202 | for compilation is finished. Everything after the C<__DATA__> token | |
f8881bd9 | 203 | is available for reading via the filehandle FOOBAR::DATA, |
463e8aa9 | 204 | where FOOBAR is the name of the current package when the C<__DATA__> |
205 | token is reached. This works just the same as C<__END__> does in | |
206 | package 'main', but for other modules data after C<__END__> is not | |
f610777f | 207 | automatically retrievable, whereas data after C<__DATA__> is. |
463e8aa9 | 208 | The C<__DATA__> token is not recognized in versions of perl prior to |
f8881bd9 AD |
209 | 5.001m. |
210 | ||
463e8aa9 | 211 | Note that it is possible to have C<__DATA__> tokens in the same package |
212 | in multiple files, and that the last C<__DATA__> token in a given | |
f8881bd9 | 213 | package that is encountered by the compiler is the one accessible |
463e8aa9 | 214 | by the filehandle. This also applies to C<__END__> and main, i.e. if |
215 | the 'main' program has an C<__END__>, but a module 'require'd (_not_ 'use'd) | |
216 | by that program has a 'package main;' declaration followed by an 'C<__DATA__>', | |
217 | then the C<DATA> filehandle is set to access the data after the C<__DATA__> | |
218 | in the module, _not_ the data after the C<__END__> token in the 'main' | |
f8881bd9 AD |
219 | program, since the compiler encounters the 'require'd file later. |
220 | ||
221 | =head2 SelfLoader autoloading | |
222 | ||
463e8aa9 | 223 | The B<SelfLoader> works by the user placing the C<__DATA__> |
224 | token I<after> perl code which needs to be compiled and | |
225 | run at 'require' time, but I<before> subroutine declarations | |
f8881bd9 AD |
226 | that can be loaded in later - usually because they may never |
227 | be called. | |
228 | ||
463e8aa9 | 229 | The B<SelfLoader> will read from the FOOBAR::DATA filehandle to |
230 | load in the data after C<__DATA__>, and load in any subroutine | |
f8881bd9 | 231 | when it is called. The costs are the one-time parsing of the |
463e8aa9 | 232 | data after C<__DATA__>, and a load delay for the _first_ |
f8881bd9 AD |
233 | call of any autoloaded function. The benefits (hopefully) |
234 | are a speeded up compilation phase, with no need to load | |
235 | functions which are never used. | |
236 | ||
463e8aa9 | 237 | The B<SelfLoader> will stop reading from C<__DATA__> if |
238 | it encounters the C<__END__> token - just as you would expect. | |
239 | If the C<__END__> token is present, and is followed by the | |
240 | token DATA, then the B<SelfLoader> leaves the FOOBAR::DATA | |
f8881bd9 AD |
241 | filehandle open on the line after that token. |
242 | ||
463e8aa9 | 243 | The B<SelfLoader> exports the C<AUTOLOAD> subroutine to the |
244 | package using the B<SelfLoader>, and this loads the called | |
f8881bd9 AD |
245 | subroutine when it is first called. |
246 | ||
247 | There is no advantage to putting subroutines which will _always_ | |
463e8aa9 | 248 | be called after the C<__DATA__> token. |
f8881bd9 AD |
249 | |
250 | =head2 Autoloading and package lexicals | |
251 | ||
252 | A 'my $pack_lexical' statement makes the variable $pack_lexical | |
463e8aa9 | 253 | local _only_ to the file up to the C<__DATA__> token. Subroutines |
f8881bd9 AD |
254 | declared elsewhere _cannot_ see these types of variables, |
255 | just as if you declared subroutines in the package but in another | |
256 | file, they cannot see these variables. | |
257 | ||
258 | So specifically, autoloaded functions cannot see package | |
463e8aa9 | 259 | lexicals (this applies to both the B<SelfLoader> and the Autoloader). |
260 | The C<vars> pragma provides an alternative to defining package-level | |
261 | globals that will be visible to autoloaded routines. See the documentation | |
262 | on B<vars> in the pragma section of L<perlmod>. | |
f8881bd9 AD |
263 | |
264 | =head2 SelfLoader and AutoLoader | |
265 | ||
463e8aa9 | 266 | The B<SelfLoader> can replace the AutoLoader - just change 'use AutoLoader' |
267 | to 'use SelfLoader' (though note that the B<SelfLoader> exports | |
f8881bd9 AD |
268 | the AUTOLOAD function - but if you have your own AUTOLOAD and |
269 | are using the AutoLoader too, you probably know what you're doing), | |
463e8aa9 | 270 | and the C<__END__> token to C<__DATA__>. You will need perl version 5.001m |
f8881bd9 AD |
271 | or later to use this (version 5.001 with all patches up to patch m). |
272 | ||
463e8aa9 | 273 | There is no need to inherit from the B<SelfLoader>. |
f8881bd9 | 274 | |
463e8aa9 | 275 | The B<SelfLoader> works similarly to the AutoLoader, but picks up the |
276 | subs from after the C<__DATA__> instead of in the 'lib/auto' directory. | |
f610777f | 277 | There is a maintenance gain in not needing to run AutoSplit on the module |
f8881bd9 AD |
278 | at installation, and a runtime gain in not needing to keep opening and |
279 | closing files to load subs. There is a runtime loss in needing | |
463e8aa9 | 280 | to parse the code after the C<__DATA__>. Details of the B<AutoLoader> and |
281 | another view of these distinctions can be found in that module's | |
282 | documentation. | |
f8881bd9 AD |
283 | |
284 | =head2 __DATA__, __END__, and the FOOBAR::DATA filehandle. | |
285 | ||
286 | This section is only relevant if you want to use | |
463e8aa9 | 287 | the C<FOOBAR::DATA> together with the B<SelfLoader>. |
288 | ||
289 | Data after the C<__DATA__> token in a module is read using the | |
290 | FOOBAR::DATA filehandle. C<__END__> can still be used to denote the end | |
291 | of the C<__DATA__> section if followed by the token DATA - this is supported | |
292 | by the B<SelfLoader>. The C<FOOBAR::DATA> filehandle is left open if an | |
293 | C<__END__> followed by a DATA is found, with the filehandle positioned at | |
294 | the start of the line after the C<__END__> token. If no C<__END__> token is | |
295 | present, or an C<__END__> token with no DATA token on the same line, then | |
296 | the filehandle is closed. | |
297 | ||
298 | The B<SelfLoader> reads from wherever the current | |
299 | position of the C<FOOBAR::DATA> filehandle is, until the | |
300 | EOF or C<__END__>. This means that if you want to use | |
f8881bd9 AD |
301 | that filehandle (and ONLY if you want to), you should either |
302 | ||
303 | 1. Put all your subroutine declarations immediately after | |
463e8aa9 | 304 | the C<__DATA__> token and put your own data after those |
305 | declarations, using the C<__END__> token to mark the end | |
306 | of subroutine declarations. You must also ensure that the B<SelfLoader> | |
1fef88e7 | 307 | reads first by calling 'SelfLoader-E<gt>load_stubs();', or by using a |
f8881bd9 AD |
308 | function which is selfloaded; |
309 | ||
310 | or | |
311 | ||
463e8aa9 | 312 | 2. You should read the C<FOOBAR::DATA> filehandle first, leaving |
f8881bd9 AD |
313 | the handle open and positioned at the first line of subroutine |
314 | declarations. | |
315 | ||
316 | You could conceivably do both. | |
317 | ||
318 | =head2 Classes and inherited methods. | |
319 | ||
320 | For modules which are not classes, this section is not relevant. | |
321 | This section is only relevant if you have methods which could | |
322 | be inherited. | |
323 | ||
324 | A subroutine stub (or forward declaration) looks like | |
325 | ||
326 | sub stub; | |
327 | ||
328 | i.e. it is a subroutine declaration without the body of the | |
329 | subroutine. For modules which are not classes, there is no real | |
330 | need for stubs as far as autoloading is concerned. | |
331 | ||
332 | For modules which ARE classes, and need to handle inherited methods, | |
333 | stubs are needed to ensure that the method inheritance mechanism works | |
334 | properly. You can load the stubs into the module at 'require' time, by | |
1fef88e7 | 335 | adding the statement 'SelfLoader-E<gt>load_stubs();' to the module to do |
f8881bd9 AD |
336 | this. |
337 | ||
463e8aa9 | 338 | The alternative is to put the stubs in before the C<__DATA__> token BEFORE |
339 | releasing the module, and for this purpose the C<Devel::SelfStubber> | |
f8881bd9 AD |
340 | module is available. However this does require the extra step of ensuring |
341 | that the stubs are in the module. If this is done I strongly recommend | |
342 | that this is done BEFORE releasing the module - it should NOT be done | |
343 | at install time in general. | |
344 | ||
345 | =head1 Multiple packages and fully qualified subroutine names | |
346 | ||
347 | Subroutines in multiple packages within the same file are supported - but you | |
463e8aa9 | 348 | should note that this requires exporting the C<SelfLoader::AUTOLOAD> to |
f8881bd9 | 349 | every package which requires it. This is done automatically by the |
463e8aa9 | 350 | B<SelfLoader> when it first loads the subs into the cache, but you should |
351 | really specify it in the initialization before the C<__DATA__> by putting | |
f8881bd9 AD |
352 | a 'use SelfLoader' statement in each package. |
353 | ||
354 | Fully qualified subroutine names are also supported. For example, | |
355 | ||
356 | __DATA__ | |
357 | sub foo::bar {23} | |
358 | package baz; | |
359 | sub dob {32} | |
360 | ||
463e8aa9 | 361 | will all be loaded correctly by the B<SelfLoader>, and the B<SelfLoader> |
f8881bd9 | 362 | will ensure that the packages 'foo' and 'baz' correctly have the |
463e8aa9 | 363 | B<SelfLoader> C<AUTOLOAD> method when the data after C<__DATA__> is first |
364 | parsed. | |
f8881bd9 | 365 | |
0a8174e1 RGS |
366 | =head1 AUTHOR |
367 | ||
368 | C<SelfLoader> is maintained by the perl5-porters. Please direct | |
369 | any questions to the canonical mailing list. Anything that | |
370 | is applicable to the CPAN release can be sent to its maintainer, | |
371 | though. | |
372 | ||
373 | Author and Maintainer: The Perl5-Porters <perl5-porters@perl.org> | |
374 | ||
375 | Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org> | |
376 | ||
377 | =head1 COPYRIGHT AND LICENSE | |
378 | ||
379 | This package has been part of the perl core since the first release | |
380 | of perl5. It has been released separately to CPAN so older installations | |
381 | can benefit from bug fixes. | |
382 | ||
383 | This package has the same copyright and license as the perl core: | |
384 | ||
385 | Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, | |
386 | 2000, 2001, 2002, 2003, 2004, 2005, 2006 by Larry Wall and others | |
387 | ||
388 | All rights reserved. | |
389 | ||
390 | This program is free software; you can redistribute it and/or modify | |
391 | it under the terms of either: | |
392 | ||
393 | a) the GNU General Public License as published by the Free | |
394 | Software Foundation; either version 1, or (at your option) any | |
395 | later version, or | |
396 | ||
397 | b) the "Artistic License" which comes with this Kit. | |
398 | ||
399 | This program is distributed in the hope that it will be useful, | |
400 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
401 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either | |
402 | the GNU General Public License or the Artistic License for more details. | |
403 | ||
404 | You should have received a copy of the Artistic License with this | |
405 | Kit, in the file named "Artistic". If not, I'll be glad to provide one. | |
406 | ||
407 | You should also have received a copy of the GNU General Public License | |
408 | along with this program in the file named "Copying". If not, write to the | |
409 | Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA | |
410 | 02111-1307, USA or visit their web page on the internet at | |
411 | http://www.gnu.org/copyleft/gpl.html. | |
412 | ||
413 | For those of you that choose to use the GNU General Public License, | |
414 | my interpretation of the GNU General Public License is that no Perl | |
415 | script falls under the terms of the GPL unless you explicitly put | |
416 | said script under the terms of the GPL yourself. Furthermore, any | |
417 | object code linked with perl does not automatically fall under the | |
418 | terms of the GPL, provided such object code only adds definitions | |
419 | of subroutines and variables, and does not otherwise impair the | |
420 | resulting interpreter from executing any standard Perl script. I | |
421 | consider linking in C subroutines in this manner to be the moral | |
422 | equivalent of defining subroutines in the Perl language itself. You | |
423 | may sell such an object file as proprietary provided that you provide | |
424 | or offer to provide the Perl source, as specified by the GNU General | |
425 | Public License. (This is merely an alternate way of specifying input | |
426 | to the program.) You may also sell a binary produced by the dumping of | |
427 | a running Perl script that belongs to you, provided that you provide or | |
428 | offer to provide the Perl source as specified by the GPL. (The | |
429 | fact that a Perl interpreter and your code are in the same binary file | |
430 | is, in this case, a form of mere aggregation.) This is my interpretation | |
431 | of the GPL. If you still have concerns or difficulties understanding | |
432 | my intent, feel free to contact me. Of course, the Artistic License | |
433 | spells all this out for your protection, so you may prefer to use that. | |
434 | ||
f8881bd9 | 435 | =cut |