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