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