1 | package AutoLoader;
|
---|
2 |
|
---|
3 | use strict;
|
---|
4 | use 5.006_001;
|
---|
5 |
|
---|
6 | our($VERSION, $AUTOLOAD);
|
---|
7 |
|
---|
8 | my $is_dosish;
|
---|
9 | my $is_epoc;
|
---|
10 | my $is_vms;
|
---|
11 | my $is_macos;
|
---|
12 |
|
---|
13 | BEGIN {
|
---|
14 | $is_dosish = $^O eq 'dos' || $^O eq 'os2' || $^O eq 'MSWin32' || $^O eq 'NetWare';
|
---|
15 | $is_epoc = $^O eq 'epoc';
|
---|
16 | $is_vms = $^O eq 'VMS';
|
---|
17 | $is_macos = $^O eq 'MacOS';
|
---|
18 | $VERSION = '5.60';
|
---|
19 | }
|
---|
20 |
|
---|
21 | AUTOLOAD {
|
---|
22 | my $sub = $AUTOLOAD;
|
---|
23 | my $filename;
|
---|
24 | # Braces used to preserve $1 et al.
|
---|
25 | {
|
---|
26 | # Try to find the autoloaded file from the package-qualified
|
---|
27 | # name of the sub. e.g., if the sub needed is
|
---|
28 | # Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
|
---|
29 | # something like '/usr/lib/perl5/Getopt/Long.pm', and the
|
---|
30 | # autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
|
---|
31 | #
|
---|
32 | # However, if @INC is a relative path, this might not work. If,
|
---|
33 | # for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
|
---|
34 | # 'lib/Getopt/Long.pm', and we want to require
|
---|
35 | # 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
|
---|
36 | # In this case, we simple prepend the 'auto/' and let the
|
---|
37 | # C<require> take care of the searching for us.
|
---|
38 |
|
---|
39 | my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
|
---|
40 | $pkg =~ s#::#/#g;
|
---|
41 | if (defined($filename = $INC{"$pkg.pm"})) {
|
---|
42 | if ($is_macos) {
|
---|
43 | $pkg =~ tr#/#:#;
|
---|
44 | $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
|
---|
45 | } else {
|
---|
46 | $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
|
---|
47 | }
|
---|
48 |
|
---|
49 | # if the file exists, then make sure that it is a
|
---|
50 | # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
|
---|
51 | # or './lib/auto/foo/bar.al'. This avoids C<require> searching
|
---|
52 | # (and failing) to find the 'lib/auto/foo/bar.al' because it
|
---|
53 | # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
|
---|
54 |
|
---|
55 | if (-r $filename) {
|
---|
56 | unless ($filename =~ m|^/|s) {
|
---|
57 | if ($is_dosish) {
|
---|
58 | unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
|
---|
59 | if ($^O ne 'NetWare') {
|
---|
60 | $filename = "./$filename";
|
---|
61 | } else {
|
---|
62 | $filename = "$filename";
|
---|
63 | }
|
---|
64 | }
|
---|
65 | }
|
---|
66 | elsif ($is_epoc) {
|
---|
67 | unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
|
---|
68 | $filename = "./$filename";
|
---|
69 | }
|
---|
70 | }
|
---|
71 | elsif ($is_vms) {
|
---|
72 | # XXX todo by VMSmiths
|
---|
73 | $filename = "./$filename";
|
---|
74 | }
|
---|
75 | elsif (!$is_macos) {
|
---|
76 | $filename = "./$filename";
|
---|
77 | }
|
---|
78 | }
|
---|
79 | }
|
---|
80 | else {
|
---|
81 | $filename = undef;
|
---|
82 | }
|
---|
83 | }
|
---|
84 | unless (defined $filename) {
|
---|
85 | # let C<require> do the searching
|
---|
86 | $filename = "auto/$sub.al";
|
---|
87 | $filename =~ s#::#/#g;
|
---|
88 | }
|
---|
89 | }
|
---|
90 | my $save = $@;
|
---|
91 | local $!; # Do not munge the value.
|
---|
92 | eval { local $SIG{__DIE__}; require $filename };
|
---|
93 | if ($@) {
|
---|
94 | if (substr($sub,-9) eq '::DESTROY') {
|
---|
95 | no strict 'refs';
|
---|
96 | *$sub = sub {};
|
---|
97 | $@ = undef;
|
---|
98 | } elsif ($@ =~ /^Can't locate/) {
|
---|
99 | # The load might just have failed because the filename was too
|
---|
100 | # long for some old SVR3 systems which treat long names as errors.
|
---|
101 | # If we can successfully truncate a long name then it's worth a go.
|
---|
102 | # There is a slight risk that we could pick up the wrong file here
|
---|
103 | # but autosplit should have warned about that when splitting.
|
---|
104 | if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
|
---|
105 | eval { local $SIG{__DIE__}; require $filename };
|
---|
106 | }
|
---|
107 | }
|
---|
108 | if ($@){
|
---|
109 | $@ =~ s/ at .*\n//;
|
---|
110 | my $error = $@;
|
---|
111 | require Carp;
|
---|
112 | Carp::croak($error);
|
---|
113 | }
|
---|
114 | }
|
---|
115 | $@ = $save;
|
---|
116 | goto &$sub;
|
---|
117 | }
|
---|
118 |
|
---|
119 | sub import {
|
---|
120 | my $pkg = shift;
|
---|
121 | my $callpkg = caller;
|
---|
122 |
|
---|
123 | #
|
---|
124 | # Export symbols, but not by accident of inheritance.
|
---|
125 | #
|
---|
126 |
|
---|
127 | if ($pkg eq 'AutoLoader') {
|
---|
128 | no strict 'refs';
|
---|
129 | *{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD
|
---|
130 | if @_ and $_[0] =~ /^&?AUTOLOAD$/;
|
---|
131 | }
|
---|
132 |
|
---|
133 | #
|
---|
134 | # Try to find the autosplit index file. Eg., if the call package
|
---|
135 | # is POSIX, then $INC{POSIX.pm} is something like
|
---|
136 | # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
|
---|
137 | # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
|
---|
138 | #
|
---|
139 | # However, if @INC is a relative path, this might not work. If,
|
---|
140 | # for example, @INC = ('lib'), then
|
---|
141 | # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
|
---|
142 | # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
|
---|
143 | #
|
---|
144 |
|
---|
145 | (my $calldir = $callpkg) =~ s#::#/#g;
|
---|
146 | my $path = $INC{$calldir . '.pm'};
|
---|
147 | if (defined($path)) {
|
---|
148 | # Try absolute path name.
|
---|
149 | if ($is_macos) {
|
---|
150 | (my $malldir = $calldir) =~ tr#/#:#;
|
---|
151 | $path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s;
|
---|
152 | } else {
|
---|
153 | $path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#;
|
---|
154 | }
|
---|
155 |
|
---|
156 | eval { require $path; };
|
---|
157 | # If that failed, try relative path with normal @INC searching.
|
---|
158 | if ($@) {
|
---|
159 | $path ="auto/$calldir/autosplit.ix";
|
---|
160 | eval { require $path; };
|
---|
161 | }
|
---|
162 | if ($@) {
|
---|
163 | my $error = $@;
|
---|
164 | require Carp;
|
---|
165 | Carp::carp($error);
|
---|
166 | }
|
---|
167 | }
|
---|
168 | }
|
---|
169 |
|
---|
170 | sub unimport {
|
---|
171 | my $callpkg = caller;
|
---|
172 |
|
---|
173 | no strict 'refs';
|
---|
174 | my $symname = $callpkg . '::AUTOLOAD';
|
---|
175 | undef *{ $symname } if \&{ $symname } == \&AUTOLOAD;
|
---|
176 | *{ $symname } = \&{ $symname };
|
---|
177 | }
|
---|
178 |
|
---|
179 | 1;
|
---|
180 |
|
---|
181 | __END__
|
---|
182 |
|
---|
183 | =head1 NAME
|
---|
184 |
|
---|
185 | AutoLoader - load subroutines only on demand
|
---|
186 |
|
---|
187 | =head1 SYNOPSIS
|
---|
188 |
|
---|
189 | package Foo;
|
---|
190 | use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine
|
---|
191 |
|
---|
192 | package Bar;
|
---|
193 | use AutoLoader; # don't import AUTOLOAD, define our own
|
---|
194 | sub AUTOLOAD {
|
---|
195 | ...
|
---|
196 | $AutoLoader::AUTOLOAD = "...";
|
---|
197 | goto &AutoLoader::AUTOLOAD;
|
---|
198 | }
|
---|
199 |
|
---|
200 | =head1 DESCRIPTION
|
---|
201 |
|
---|
202 | The B<AutoLoader> module works with the B<AutoSplit> module and the
|
---|
203 | C<__END__> token to defer the loading of some subroutines until they are
|
---|
204 | used rather than loading them all at once.
|
---|
205 |
|
---|
206 | To use B<AutoLoader>, the author of a module has to place the
|
---|
207 | definitions of subroutines to be autoloaded after an C<__END__> token.
|
---|
208 | (See L<perldata>.) The B<AutoSplit> module can then be run manually to
|
---|
209 | extract the definitions into individual files F<auto/funcname.al>.
|
---|
210 |
|
---|
211 | B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined
|
---|
212 | subroutine in is called in a client module of B<AutoLoader>,
|
---|
213 | B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
|
---|
214 | file with a name related to the location of the file from which the
|
---|
215 | client module was read. As an example, if F<POSIX.pm> is located in
|
---|
216 | F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
|
---|
217 | subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
|
---|
218 | the C<.al> file has the same name as the subroutine, sans package. If
|
---|
219 | such a file exists, AUTOLOAD will read and evaluate it,
|
---|
220 | thus (presumably) defining the needed subroutine. AUTOLOAD will then
|
---|
221 | C<goto> the newly defined subroutine.
|
---|
222 |
|
---|
223 | Once this process completes for a given function, it is defined, so
|
---|
224 | future calls to the subroutine will bypass the AUTOLOAD mechanism.
|
---|
225 |
|
---|
226 | =head2 Subroutine Stubs
|
---|
227 |
|
---|
228 | In order for object method lookup and/or prototype checking to operate
|
---|
229 | correctly even when methods have not yet been defined it is necessary to
|
---|
230 | "forward declare" each subroutine (as in C<sub NAME;>). See
|
---|
231 | L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine
|
---|
232 | stubs", which are place holders with no code.
|
---|
233 |
|
---|
234 | The AutoSplit and B<AutoLoader> modules automate the creation of forward
|
---|
235 | declarations. The AutoSplit module creates an 'index' file containing
|
---|
236 | forward declarations of all the AutoSplit subroutines. When the
|
---|
237 | AutoLoader module is 'use'd it loads these declarations into its callers
|
---|
238 | package.
|
---|
239 |
|
---|
240 | Because of this mechanism it is important that B<AutoLoader> is always
|
---|
241 | C<use>d and not C<require>d.
|
---|
242 |
|
---|
243 | =head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
|
---|
244 |
|
---|
245 | In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
|
---|
246 | explicitly import it:
|
---|
247 |
|
---|
248 | use AutoLoader 'AUTOLOAD';
|
---|
249 |
|
---|
250 | =head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
|
---|
251 |
|
---|
252 | Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
|
---|
253 | They typically need to check for some special cases (such as constants)
|
---|
254 | and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
|
---|
255 |
|
---|
256 | Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
|
---|
257 | Instead, they should define their own AUTOLOAD subroutines along these
|
---|
258 | lines:
|
---|
259 |
|
---|
260 | use AutoLoader;
|
---|
261 | use Carp;
|
---|
262 |
|
---|
263 | sub AUTOLOAD {
|
---|
264 | my $sub = $AUTOLOAD;
|
---|
265 | (my $constname = $sub) =~ s/.*:://;
|
---|
266 | my $val = constant($constname, @_ ? $_[0] : 0);
|
---|
267 | if ($! != 0) {
|
---|
268 | if ($! =~ /Invalid/ || $!{EINVAL}) {
|
---|
269 | $AutoLoader::AUTOLOAD = $sub;
|
---|
270 | goto &AutoLoader::AUTOLOAD;
|
---|
271 | }
|
---|
272 | else {
|
---|
273 | croak "Your vendor has not defined constant $constname";
|
---|
274 | }
|
---|
275 | }
|
---|
276 | *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
|
---|
277 | goto &$sub;
|
---|
278 | }
|
---|
279 |
|
---|
280 | If any module's own AUTOLOAD subroutine has no need to fallback to the
|
---|
281 | AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
|
---|
282 | subroutines), then that module should not use B<AutoLoader> at all.
|
---|
283 |
|
---|
284 | =head2 Package Lexicals
|
---|
285 |
|
---|
286 | Package lexicals declared with C<my> in the main block of a package
|
---|
287 | using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
|
---|
288 | the fact that the given scope ends at the C<__END__> marker. A module
|
---|
289 | using such variables as package globals will not work properly under the
|
---|
290 | B<AutoLoader>.
|
---|
291 |
|
---|
292 | The C<vars> pragma (see L<perlmod/"vars">) may be used in such
|
---|
293 | situations as an alternative to explicitly qualifying all globals with
|
---|
294 | the package namespace. Variables pre-declared with this pragma will be
|
---|
295 | visible to any autoloaded routines (but will not be invisible outside
|
---|
296 | the package, unfortunately).
|
---|
297 |
|
---|
298 | =head2 Not Using AutoLoader
|
---|
299 |
|
---|
300 | You can stop using AutoLoader by simply
|
---|
301 |
|
---|
302 | no AutoLoader;
|
---|
303 |
|
---|
304 | =head2 B<AutoLoader> vs. B<SelfLoader>
|
---|
305 |
|
---|
306 | The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
|
---|
307 | loading of subroutines.
|
---|
308 |
|
---|
309 | B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
|
---|
310 | While this avoids the use of a hierarchy of disk files and the
|
---|
311 | associated open/close for each routine loaded, B<SelfLoader> suffers a
|
---|
312 | startup speed disadvantage in the one-time parsing of the lines after
|
---|
313 | C<__DATA__>, after which routines are cached. B<SelfLoader> can also
|
---|
314 | handle multiple packages in a file.
|
---|
315 |
|
---|
316 | B<AutoLoader> only reads code as it is requested, and in many cases
|
---|
317 | should be faster, but requires a mechanism like B<AutoSplit> be used to
|
---|
318 | create the individual files. L<ExtUtils::MakeMaker> will invoke
|
---|
319 | B<AutoSplit> automatically if B<AutoLoader> is used in a module source
|
---|
320 | file.
|
---|
321 |
|
---|
322 | =head1 CAVEATS
|
---|
323 |
|
---|
324 | AutoLoaders prior to Perl 5.002 had a slightly different interface. Any
|
---|
325 | old modules which use B<AutoLoader> should be changed to the new calling
|
---|
326 | style. Typically this just means changing a require to a use, adding
|
---|
327 | the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
|
---|
328 | from C<@ISA>.
|
---|
329 |
|
---|
330 | On systems with restrictions on file name length, the file corresponding
|
---|
331 | to a subroutine may have a shorter name that the routine itself. This
|
---|
332 | can lead to conflicting file names. The I<AutoSplit> package warns of
|
---|
333 | these potential conflicts when used to split a module.
|
---|
334 |
|
---|
335 | AutoLoader may fail to find the autosplit files (or even find the wrong
|
---|
336 | ones) in cases where C<@INC> contains relative paths, B<and> the program
|
---|
337 | does C<chdir>.
|
---|
338 |
|
---|
339 | =head1 SEE ALSO
|
---|
340 |
|
---|
341 | L<SelfLoader> - an autoloader that doesn't use external files.
|
---|
342 |
|
---|
343 | =cut
|
---|