Commit | Line | Data |
f8881bd9 |
1 | package SelfLoader; |
5e1aa25c |
2 | |
3 | use 5.009005; # due to new regexp features |
4 | use strict; |
5 | |
6 | use Exporter; |
7 | our @ISA = qw(Exporter); |
8 | our @EXPORT = qw(AUTOLOAD); |
1163f0e4 |
9 | our $VERSION = "1.12"; |
52128c7b |
10 | sub Version {$VERSION} |
5e1aa25c |
11 | sub DEBUG () { 0 } |
f8881bd9 |
12 | |
13 | my %Cache; # private cache for all SelfLoader's client packages |
14 | |
09bef843 |
15 | # allow checking for valid ': attrlist' attachments |
5e1aa25c |
16 | # see also AutoSplit |
17 | |
18 | my $attr_list = qr{ |
19 | \s* : \s* |
20 | (?: |
21 | # one attribute |
22 | (?> # no backtrack |
23 | (?! \d) \w+ |
24 | (?<nested> \( (?: [^()]++ | (?&nested)++ )*+ \) ) ? |
25 | ) |
26 | (?: \s* : \s* | \s+ (?! :) ) |
27 | )* |
28 | }x; |
09bef843 |
29 | |
cca8f13b |
30 | # in croak and carp, protect $@ from "require Carp;" RT #40216 |
31 | |
32 | sub croak { { local $@; require Carp; } goto &Carp::croak } |
33 | sub carp { { local $@; require Carp; } goto &Carp::carp } |
e3d0cac0 |
34 | |
f8881bd9 |
35 | AUTOLOAD { |
5e1aa25c |
36 | our $AUTOLOAD; |
37 | print STDERR "SelfLoader::AUTOLOAD for $AUTOLOAD\n" if DEBUG; |
c7675058 |
38 | my $SL_code = $Cache{$AUTOLOAD}; |
bfdd1499 |
39 | my $save = $@; # evals in both AUTOLOAD and _load_stubs can corrupt $@ |
c7675058 |
40 | unless ($SL_code) { |
f8881bd9 |
41 | # Maybe this pack had stubs before __DATA__, and never initialized. |
42 | # Or, this maybe an automatic DESTROY method call when none exists. |
43 | $AUTOLOAD =~ m/^(.*)::/; |
44 | SelfLoader->_load_stubs($1) unless exists $Cache{"${1}::<DATA"}; |
c7675058 |
45 | $SL_code = $Cache{$AUTOLOAD}; |
46 | $SL_code = "sub $AUTOLOAD { }" |
47 | if (!$SL_code and $AUTOLOAD =~ m/::DESTROY$/); |
48 | croak "Undefined subroutine $AUTOLOAD" unless $SL_code; |
f8881bd9 |
49 | } |
5e1aa25c |
50 | print STDERR "SelfLoader::AUTOLOAD eval: $SL_code\n" if DEBUG; |
bfdd1499 |
51 | |
5ef97ff3 |
52 | { |
53 | no strict; |
54 | eval $SL_code; |
55 | } |
f8881bd9 |
56 | if ($@) { |
57 | $@ =~ s/ at .*\n//; |
58 | croak $@; |
59 | } |
bfdd1499 |
60 | $@ = $save; |
f8881bd9 |
61 | defined(&$AUTOLOAD) || die "SelfLoader inconsistency error"; |
62 | delete $Cache{$AUTOLOAD}; |
63 | goto &$AUTOLOAD |
64 | } |
65 | |
66 | sub load_stubs { shift->_load_stubs((caller)[0]) } |
67 | |
68 | sub _load_stubs { |
33235a50 |
69 | # $endlines is used by Devel::SelfStubber to capture lines after __END__ |
70 | my($self, $callpack, $endlines) = @_; |
5e1aa25c |
71 | no strict "refs"; |
f8881bd9 |
72 | my $fh = \*{"${callpack}::DATA"}; |
5e1aa25c |
73 | use strict; |
f8881bd9 |
74 | my $currpack = $callpack; |
75 | my($line,$name,@lines, @stubs, $protoype); |
76 | |
5e1aa25c |
77 | print STDERR "SelfLoader::load_stubs($callpack)\n" if DEBUG; |
f8881bd9 |
78 | croak("$callpack doesn't contain an __DATA__ token") |
2ef89038 |
79 | unless defined fileno($fh); |
add1a1a3 |
80 | # Protect: fork() shares the file pointer between the parent and the kid |
054149a8 |
81 | if(sysseek($fh, tell($fh), 0)) { |
82 | open my $nfh, '<&', $fh or croak "reopen: $!";# dup() the fd |
83 | close $fh or die "close: $1"; # autocloses, but be paranoid |
84 | open $fh, '<&', $nfh or croak "reopen2: $!"; # dup() the fd "back" |
85 | close $nfh or die "close after reopen: $1"; # autocloses, but be paranoid |
86 | } |
f8881bd9 |
87 | $Cache{"${currpack}::<DATA"} = 1; # indicate package is cached |
88 | |
52128c7b |
89 | local($/) = "\n"; |
40da2db3 |
90 | while(defined($line = <$fh>) and $line !~ m/^__END__/) { |
1163f0e4 |
91 | if ($line =~ m/^\s*sub\s+([\w:]+)\s*((?:\([\\\$\@\%\&\*\;]*\))?(?:$attr_list)?)/) { |
f8881bd9 |
92 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); |
93 | $protoype = $2; |
94 | @lines = ($line); |
95 | if (index($1,'::') == -1) { # simple sub name |
96 | $name = "${currpack}::$1"; |
97 | } else { # sub name with package |
98 | $name = $1; |
99 | $name =~ m/^(.*)::/; |
100 | if (defined(&{"${1}::AUTOLOAD"})) { |
101 | \&{"${1}::AUTOLOAD"} == \&SelfLoader::AUTOLOAD || |
102 | die 'SelfLoader Error: attempt to specify Selfloading', |
103 | " sub $name in non-selfloading module $1"; |
104 | } else { |
105 | $self->export($1,'AUTOLOAD'); |
106 | } |
107 | } |
108 | } elsif ($line =~ m/^package\s+([\w:]+)/) { # A package declared |
109 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); |
110 | $self->_package_defined($line); |
111 | $name = ''; |
112 | @lines = (); |
113 | $currpack = $1; |
114 | $Cache{"${currpack}::<DATA"} = 1; # indicate package is cached |
115 | if (defined(&{"${1}::AUTOLOAD"})) { |
116 | \&{"${1}::AUTOLOAD"} == \&SelfLoader::AUTOLOAD || |
117 | die 'SelfLoader Error: attempt to specify Selfloading', |
118 | " package $currpack which already has AUTOLOAD"; |
119 | } else { |
120 | $self->export($currpack,'AUTOLOAD'); |
121 | } |
122 | } else { |
123 | push(@lines,$line); |
124 | } |
125 | } |
33235a50 |
126 | if (defined($line) && $line =~ /^__END__/) { # __END__ |
127 | unless ($line =~ /^__END__\s*DATA/) { |
128 | if ($endlines) { |
129 | # Devel::SelfStubber would like us to capture the lines after |
130 | # __END__ so it can write out the entire file |
131 | @$endlines = <$fh>; |
132 | } |
133 | close($fh); |
134 | } |
135 | } |
f8881bd9 |
136 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); |
5ef97ff3 |
137 | no strict; |
f8881bd9 |
138 | eval join('', @stubs) if @stubs; |
139 | } |
140 | |
141 | |
142 | sub _add_to_cache { |
143 | my($self,$fullname,$pack,$lines, $protoype) = @_; |
144 | return () unless $fullname; |
8878f897 |
145 | carp("Redefining sub $fullname") |
e3d0cac0 |
146 | if exists $Cache{$fullname}; |
f8881bd9 |
147 | $Cache{$fullname} = join('', "package $pack; ",@$lines); |
5e1aa25c |
148 | print STDERR "SelfLoader cached $fullname: $Cache{$fullname}" if DEBUG; |
f8881bd9 |
149 | # return stub to be eval'd |
150 | defined($protoype) ? "sub $fullname $protoype;" : "sub $fullname;" |
151 | } |
152 | |
153 | sub _package_defined {} |
154 | |
155 | 1; |
156 | __END__ |
cb1a09d0 |
157 | |
f8881bd9 |
158 | =head1 NAME |
159 | |
160 | SelfLoader - load functions only on demand |
161 | |
162 | =head1 SYNOPSIS |
163 | |
164 | package FOOBAR; |
165 | use SelfLoader; |
3cb6de81 |
166 | |
f8881bd9 |
167 | ... (initializing code) |
3cb6de81 |
168 | |
f8881bd9 |
169 | __DATA__ |
170 | sub {.... |
171 | |
172 | |
173 | =head1 DESCRIPTION |
174 | |
175 | This module tells its users that functions in the FOOBAR package are to be |
463e8aa9 |
176 | autoloaded from after the C<__DATA__> token. See also |
177 | L<perlsub/"Autoloading">. |
f8881bd9 |
178 | |
179 | =head2 The __DATA__ token |
180 | |
463e8aa9 |
181 | The C<__DATA__> token tells the perl compiler that the perl code |
182 | for compilation is finished. Everything after the C<__DATA__> token |
f8881bd9 |
183 | is available for reading via the filehandle FOOBAR::DATA, |
463e8aa9 |
184 | where FOOBAR is the name of the current package when the C<__DATA__> |
185 | token is reached. This works just the same as C<__END__> does in |
186 | package 'main', but for other modules data after C<__END__> is not |
f610777f |
187 | automatically retrievable, whereas data after C<__DATA__> is. |
463e8aa9 |
188 | The C<__DATA__> token is not recognized in versions of perl prior to |
f8881bd9 |
189 | 5.001m. |
190 | |
463e8aa9 |
191 | Note that it is possible to have C<__DATA__> tokens in the same package |
192 | in multiple files, and that the last C<__DATA__> token in a given |
f8881bd9 |
193 | package that is encountered by the compiler is the one accessible |
463e8aa9 |
194 | by the filehandle. This also applies to C<__END__> and main, i.e. if |
195 | the 'main' program has an C<__END__>, but a module 'require'd (_not_ 'use'd) |
196 | by that program has a 'package main;' declaration followed by an 'C<__DATA__>', |
197 | then the C<DATA> filehandle is set to access the data after the C<__DATA__> |
198 | in the module, _not_ the data after the C<__END__> token in the 'main' |
f8881bd9 |
199 | program, since the compiler encounters the 'require'd file later. |
200 | |
201 | =head2 SelfLoader autoloading |
202 | |
463e8aa9 |
203 | The B<SelfLoader> works by the user placing the C<__DATA__> |
204 | token I<after> perl code which needs to be compiled and |
205 | run at 'require' time, but I<before> subroutine declarations |
f8881bd9 |
206 | that can be loaded in later - usually because they may never |
207 | be called. |
208 | |
463e8aa9 |
209 | The B<SelfLoader> will read from the FOOBAR::DATA filehandle to |
210 | load in the data after C<__DATA__>, and load in any subroutine |
f8881bd9 |
211 | when it is called. The costs are the one-time parsing of the |
463e8aa9 |
212 | data after C<__DATA__>, and a load delay for the _first_ |
f8881bd9 |
213 | call of any autoloaded function. The benefits (hopefully) |
214 | are a speeded up compilation phase, with no need to load |
215 | functions which are never used. |
216 | |
463e8aa9 |
217 | The B<SelfLoader> will stop reading from C<__DATA__> if |
218 | it encounters the C<__END__> token - just as you would expect. |
219 | If the C<__END__> token is present, and is followed by the |
220 | token DATA, then the B<SelfLoader> leaves the FOOBAR::DATA |
f8881bd9 |
221 | filehandle open on the line after that token. |
222 | |
463e8aa9 |
223 | The B<SelfLoader> exports the C<AUTOLOAD> subroutine to the |
224 | package using the B<SelfLoader>, and this loads the called |
f8881bd9 |
225 | subroutine when it is first called. |
226 | |
227 | There is no advantage to putting subroutines which will _always_ |
463e8aa9 |
228 | be called after the C<__DATA__> token. |
f8881bd9 |
229 | |
230 | =head2 Autoloading and package lexicals |
231 | |
232 | A 'my $pack_lexical' statement makes the variable $pack_lexical |
463e8aa9 |
233 | local _only_ to the file up to the C<__DATA__> token. Subroutines |
f8881bd9 |
234 | declared elsewhere _cannot_ see these types of variables, |
235 | just as if you declared subroutines in the package but in another |
236 | file, they cannot see these variables. |
237 | |
238 | So specifically, autoloaded functions cannot see package |
463e8aa9 |
239 | lexicals (this applies to both the B<SelfLoader> and the Autoloader). |
240 | The C<vars> pragma provides an alternative to defining package-level |
241 | globals that will be visible to autoloaded routines. See the documentation |
242 | on B<vars> in the pragma section of L<perlmod>. |
f8881bd9 |
243 | |
244 | =head2 SelfLoader and AutoLoader |
245 | |
463e8aa9 |
246 | The B<SelfLoader> can replace the AutoLoader - just change 'use AutoLoader' |
247 | to 'use SelfLoader' (though note that the B<SelfLoader> exports |
f8881bd9 |
248 | the AUTOLOAD function - but if you have your own AUTOLOAD and |
249 | are using the AutoLoader too, you probably know what you're doing), |
463e8aa9 |
250 | and the C<__END__> token to C<__DATA__>. You will need perl version 5.001m |
f8881bd9 |
251 | or later to use this (version 5.001 with all patches up to patch m). |
252 | |
463e8aa9 |
253 | There is no need to inherit from the B<SelfLoader>. |
f8881bd9 |
254 | |
463e8aa9 |
255 | The B<SelfLoader> works similarly to the AutoLoader, but picks up the |
256 | subs from after the C<__DATA__> instead of in the 'lib/auto' directory. |
f610777f |
257 | There is a maintenance gain in not needing to run AutoSplit on the module |
f8881bd9 |
258 | at installation, and a runtime gain in not needing to keep opening and |
259 | closing files to load subs. There is a runtime loss in needing |
463e8aa9 |
260 | to parse the code after the C<__DATA__>. Details of the B<AutoLoader> and |
261 | another view of these distinctions can be found in that module's |
262 | documentation. |
f8881bd9 |
263 | |
264 | =head2 __DATA__, __END__, and the FOOBAR::DATA filehandle. |
265 | |
266 | This section is only relevant if you want to use |
463e8aa9 |
267 | the C<FOOBAR::DATA> together with the B<SelfLoader>. |
268 | |
269 | Data after the C<__DATA__> token in a module is read using the |
270 | FOOBAR::DATA filehandle. C<__END__> can still be used to denote the end |
271 | of the C<__DATA__> section if followed by the token DATA - this is supported |
272 | by the B<SelfLoader>. The C<FOOBAR::DATA> filehandle is left open if an |
273 | C<__END__> followed by a DATA is found, with the filehandle positioned at |
274 | the start of the line after the C<__END__> token. If no C<__END__> token is |
275 | present, or an C<__END__> token with no DATA token on the same line, then |
276 | the filehandle is closed. |
277 | |
278 | The B<SelfLoader> reads from wherever the current |
279 | position of the C<FOOBAR::DATA> filehandle is, until the |
280 | EOF or C<__END__>. This means that if you want to use |
f8881bd9 |
281 | that filehandle (and ONLY if you want to), you should either |
282 | |
283 | 1. Put all your subroutine declarations immediately after |
463e8aa9 |
284 | the C<__DATA__> token and put your own data after those |
285 | declarations, using the C<__END__> token to mark the end |
286 | of subroutine declarations. You must also ensure that the B<SelfLoader> |
1fef88e7 |
287 | reads first by calling 'SelfLoader-E<gt>load_stubs();', or by using a |
f8881bd9 |
288 | function which is selfloaded; |
289 | |
290 | or |
291 | |
463e8aa9 |
292 | 2. You should read the C<FOOBAR::DATA> filehandle first, leaving |
f8881bd9 |
293 | the handle open and positioned at the first line of subroutine |
294 | declarations. |
295 | |
296 | You could conceivably do both. |
297 | |
298 | =head2 Classes and inherited methods. |
299 | |
300 | For modules which are not classes, this section is not relevant. |
301 | This section is only relevant if you have methods which could |
302 | be inherited. |
303 | |
304 | A subroutine stub (or forward declaration) looks like |
305 | |
306 | sub stub; |
307 | |
308 | i.e. it is a subroutine declaration without the body of the |
309 | subroutine. For modules which are not classes, there is no real |
310 | need for stubs as far as autoloading is concerned. |
311 | |
312 | For modules which ARE classes, and need to handle inherited methods, |
313 | stubs are needed to ensure that the method inheritance mechanism works |
314 | properly. You can load the stubs into the module at 'require' time, by |
1fef88e7 |
315 | adding the statement 'SelfLoader-E<gt>load_stubs();' to the module to do |
f8881bd9 |
316 | this. |
317 | |
463e8aa9 |
318 | The alternative is to put the stubs in before the C<__DATA__> token BEFORE |
319 | releasing the module, and for this purpose the C<Devel::SelfStubber> |
f8881bd9 |
320 | module is available. However this does require the extra step of ensuring |
321 | that the stubs are in the module. If this is done I strongly recommend |
322 | that this is done BEFORE releasing the module - it should NOT be done |
323 | at install time in general. |
324 | |
325 | =head1 Multiple packages and fully qualified subroutine names |
326 | |
327 | Subroutines in multiple packages within the same file are supported - but you |
463e8aa9 |
328 | should note that this requires exporting the C<SelfLoader::AUTOLOAD> to |
f8881bd9 |
329 | every package which requires it. This is done automatically by the |
463e8aa9 |
330 | B<SelfLoader> when it first loads the subs into the cache, but you should |
331 | really specify it in the initialization before the C<__DATA__> by putting |
f8881bd9 |
332 | a 'use SelfLoader' statement in each package. |
333 | |
334 | Fully qualified subroutine names are also supported. For example, |
335 | |
336 | __DATA__ |
337 | sub foo::bar {23} |
338 | package baz; |
339 | sub dob {32} |
340 | |
463e8aa9 |
341 | will all be loaded correctly by the B<SelfLoader>, and the B<SelfLoader> |
f8881bd9 |
342 | will ensure that the packages 'foo' and 'baz' correctly have the |
463e8aa9 |
343 | B<SelfLoader> C<AUTOLOAD> method when the data after C<__DATA__> is first |
344 | parsed. |
f8881bd9 |
345 | |
346 | =cut |