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