This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
'Upgrade' to AutoLoader 5.71
[perl5.git] / cpan / AutoLoader / 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';
fb9404f5 18 $VERSION = '5.71';
1be0b951 19}
f06db76b 20
8990e307 21AUTOLOAD {
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
00bb01c7 54sub find_filename {
55 my $sub = shift;
7d4fbd98 56 my $filename;
5a556d17
NIS
57 # Braces used to preserve $1 et al.
58 {
adaafad2
GS
59 # Try to find the autoloaded file from the package-qualified
60 # name of the sub. e.g., if the sub needed is
61 # Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
62 # something like '/usr/lib/perl5/Getopt/Long.pm', and the
63 # autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
64 #
65 # However, if @INC is a relative path, this might not work. If,
66 # for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
67 # 'lib/Getopt/Long.pm', and we want to require
68 # 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
69 # In this case, we simple prepend the 'auto/' and let the
70 # C<require> take care of the searching for us.
71
7d4fbd98 72 my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
adaafad2 73 $pkg =~ s#::#/#g;
7d4fbd98 74 if (defined($filename = $INC{"$pkg.pm"})) {
084592ab
CN
75 if ($is_macos) {
76 $pkg =~ tr#/#:#;
017a05de
S
77 $filename = undef
78 unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
084592ab 79 } else {
017a05de
S
80 $filename = undef
81 unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
084592ab 82 }
adaafad2
GS
83
84 # if the file exists, then make sure that it is a
85 # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
86 # or './lib/auto/foo/bar.al'. This avoids C<require> searching
87 # (and failing) to find the 'lib/auto/foo/bar.al' because it
88 # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
89
3256a4f8 90 if (defined $filename and -r $filename) {
14a089c5 91 unless ($filename =~ m|^/|s) {
adaafad2 92 if ($is_dosish) {
14a089c5 93 unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
00bb01c7 94 if ($^O ne 'NetWare') {
95 $filename = "./$filename";
96 } else {
97 $filename = "$filename";
98 }
adaafad2
GS
99 }
100 }
ed79a026
OF
101 elsif ($is_epoc) {
102 unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
103 $filename = "./$filename";
104 }
4d6b4052
JH
105 }
106 elsif ($is_vms) {
7d4fbd98
GS
107 # XXX todo by VMSmiths
108 $filename = "./$filename";
adaafad2 109 }
084592ab 110 elsif (!$is_macos) {
7d4fbd98 111 $filename = "./$filename";
adaafad2
GS
112 }
113 }
114 }
115 else {
7d4fbd98 116 $filename = undef;
adaafad2
GS
117 }
118 }
7d4fbd98 119 unless (defined $filename) {
adaafad2 120 # let C<require> do the searching
7d4fbd98
GS
121 $filename = "auto/$sub.al";
122 $filename =~ s#::#/#g;
adaafad2 123 }
5a556d17 124 }
00bb01c7 125 return $filename;
8990e307 126}
1be0b951 127
c2960299 128sub import {
1be0b951
CS
129 my $pkg = shift;
130 my $callpkg = caller;
131
132 #
133 # Export symbols, but not by accident of inheritance.
134 #
135
e3d0cac0 136 if ($pkg eq 'AutoLoader') {
00bb01c7 137 if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) {
138 no strict 'refs';
139 *{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD;
00bb01c7 140 }
e3d0cac0 141 }
1be0b951
CS
142
143 #
c2960299
AD
144 # Try to find the autosplit index file. Eg., if the call package
145 # is POSIX, then $INC{POSIX.pm} is something like
146 # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
147 # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
148 #
149 # However, if @INC is a relative path, this might not work. If,
150 # for example, @INC = ('lib'), then
151 # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
152 # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
153 #
1be0b951 154
1c1c7f20 155 (my $calldir = $callpkg) =~ s#::#/#g;
1be0b951
CS
156 my $path = $INC{$calldir . '.pm'};
157 if (defined($path)) {
6ada912c
S
158 # Try absolute path name, but only eval it if the
159 # transformation from module path to autosplit.ix path
160 # succeeded!
161 my $replaced_okay;
4d6b4052
JH
162 if ($is_macos) {
163 (my $malldir = $calldir) =~ tr#/#:#;
6ada912c 164 $replaced_okay = ($path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s);
4d6b4052 165 } else {
6ada912c 166 $replaced_okay = ($path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#);
4d6b4052
JH
167 }
168
6ada912c 169 eval { require $path; } if $replaced_okay;
c2960299 170 # If that failed, try relative path with normal @INC searching.
6ada912c 171 if (!$replaced_okay or $@) {
1be0b951 172 $path ="auto/$calldir/autosplit.ix";
c2960299
AD
173 eval { require $path; };
174 }
fb73857a 175 if ($@) {
176 my $error = $@;
177 require Carp;
178 Carp::carp($error);
179 }
f06db76b 180 }
f06db76b 181}
8990e307 182
cb0cff20 183sub unimport {
7412bda7 184 my $callpkg = caller;
185
186 no strict 'refs';
00bb01c7 187
536daee0 188 for my $exported (qw( AUTOLOAD )) {
00bb01c7 189 my $symname = $callpkg . '::' . $exported;
190 undef *{ $symname } if \&{ $symname } == \&{ $exported };
191 *{ $symname } = \&{ $symname };
192 }
cb0cff20
JH
193}
194
8990e307 1951;
1be0b951
CS
196
197__END__
198
199=head1 NAME
200
201AutoLoader - load subroutines only on demand
202
203=head1 SYNOPSIS
204
205 package Foo;
206 use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine
207
208 package Bar;
209 use AutoLoader; # don't import AUTOLOAD, define our own
210 sub AUTOLOAD {
211 ...
212 $AutoLoader::AUTOLOAD = "...";
213 goto &AutoLoader::AUTOLOAD;
214 }
215
216=head1 DESCRIPTION
217
218The B<AutoLoader> module works with the B<AutoSplit> module and the
219C<__END__> token to defer the loading of some subroutines until they are
220used rather than loading them all at once.
221
222To use B<AutoLoader>, the author of a module has to place the
223definitions of subroutines to be autoloaded after an C<__END__> token.
224(See L<perldata>.) The B<AutoSplit> module can then be run manually to
225extract the definitions into individual files F<auto/funcname.al>.
226
227B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined
228subroutine in is called in a client module of B<AutoLoader>,
229B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
230file with a name related to the location of the file from which the
231client module was read. As an example, if F<POSIX.pm> is located in
232F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
233subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
234the C<.al> file has the same name as the subroutine, sans package. If
235such a file exists, AUTOLOAD will read and evaluate it,
236thus (presumably) defining the needed subroutine. AUTOLOAD will then
237C<goto> the newly defined subroutine.
238
f610777f 239Once this process completes for a given function, it is defined, so
1be0b951
CS
240future calls to the subroutine will bypass the AUTOLOAD mechanism.
241
242=head2 Subroutine Stubs
243
244In order for object method lookup and/or prototype checking to operate
245correctly even when methods have not yet been defined it is necessary to
246"forward declare" each subroutine (as in C<sub NAME;>). See
247L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine
248stubs", which are place holders with no code.
249
250The AutoSplit and B<AutoLoader> modules automate the creation of forward
251declarations. The AutoSplit module creates an 'index' file containing
252forward declarations of all the AutoSplit subroutines. When the
253AutoLoader module is 'use'd it loads these declarations into its callers
254package.
255
256Because of this mechanism it is important that B<AutoLoader> is always
257C<use>d and not C<require>d.
258
259=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
260
261In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
262explicitly import it:
263
264 use AutoLoader 'AUTOLOAD';
265
266=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
267
268Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
269They typically need to check for some special cases (such as constants)
270and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
271
272Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
273Instead, they should define their own AUTOLOAD subroutines along these
274lines:
275
276 use AutoLoader;
fb73857a 277 use Carp;
1be0b951
CS
278
279 sub AUTOLOAD {
7d4fbd98
GS
280 my $sub = $AUTOLOAD;
281 (my $constname = $sub) =~ s/.*:://;
1be0b951
CS
282 my $val = constant($constname, @_ ? $_[0] : 0);
283 if ($! != 0) {
265f5c4a 284 if ($! =~ /Invalid/ || $!{EINVAL}) {
7d4fbd98 285 $AutoLoader::AUTOLOAD = $sub;
1be0b951
CS
286 goto &AutoLoader::AUTOLOAD;
287 }
288 else {
289 croak "Your vendor has not defined constant $constname";
290 }
291 }
7d4fbd98
GS
292 *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
293 goto &$sub;
1be0b951
CS
294 }
295
296If any module's own AUTOLOAD subroutine has no need to fallback to the
297AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
298subroutines), then that module should not use B<AutoLoader> at all.
299
300=head2 Package Lexicals
301
302Package lexicals declared with C<my> in the main block of a package
303using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
304the fact that the given scope ends at the C<__END__> marker. A module
305using such variables as package globals will not work properly under the
306B<AutoLoader>.
307
308The C<vars> pragma (see L<perlmod/"vars">) may be used in such
309situations as an alternative to explicitly qualifying all globals with
310the package namespace. Variables pre-declared with this pragma will be
311visible to any autoloaded routines (but will not be invisible outside
312the package, unfortunately).
313
cb0cff20
JH
314=head2 Not Using AutoLoader
315
316You can stop using AutoLoader by simply
317
318 no AutoLoader;
319
1be0b951
CS
320=head2 B<AutoLoader> vs. B<SelfLoader>
321
322The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
323loading of subroutines.
324
325B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
326While this avoids the use of a hierarchy of disk files and the
327associated open/close for each routine loaded, B<SelfLoader> suffers a
328startup speed disadvantage in the one-time parsing of the lines after
329C<__DATA__>, after which routines are cached. B<SelfLoader> can also
330handle multiple packages in a file.
331
332B<AutoLoader> only reads code as it is requested, and in many cases
f610777f 333should be faster, but requires a mechanism like B<AutoSplit> be used to
1be0b951
CS
334create the individual files. L<ExtUtils::MakeMaker> will invoke
335B<AutoSplit> automatically if B<AutoLoader> is used in a module source
336file.
337
338=head1 CAVEATS
339
340AutoLoaders prior to Perl 5.002 had a slightly different interface. Any
341old modules which use B<AutoLoader> should be changed to the new calling
342style. Typically this just means changing a require to a use, adding
343the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
344from C<@ISA>.
345
346On systems with restrictions on file name length, the file corresponding
347to a subroutine may have a shorter name that the routine itself. This
348can lead to conflicting file names. The I<AutoSplit> package warns of
349these potential conflicts when used to split a module.
350
adaafad2
GS
351AutoLoader may fail to find the autosplit files (or even find the wrong
352ones) in cases where C<@INC> contains relative paths, B<and> the program
353does C<chdir>.
354
1be0b951
CS
355=head1 SEE ALSO
356
357L<SelfLoader> - an autoloader that doesn't use external files.
358
7a752413
SP
359=head1 AUTHOR
360
361C<AutoLoader> is maintained by the perl5-porters. Please direct
362any questions to the canonical mailing list. Anything that
363is applicable to the CPAN release can be sent to its maintainer,
364though.
365
366Author and Maintainer: The Perl5-Porters <perl5-porters@perl.org>
367
368Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>
369
370=head1 COPYRIGHT AND LICENSE
371
372This package has been part of the perl core since the first release
373of perl5. It has been released separately to CPAN so older installations
374can benefit from bug fixes.
375
376This package has the same copyright and license as the perl core:
377
378 Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999,
70abb332 379 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
79706302 380 by Larry Wall and others
7a752413
SP
381
382 All rights reserved.
383
384 This program is free software; you can redistribute it and/or modify
385 it under the terms of either:
386
387 a) the GNU General Public License as published by the Free
388 Software Foundation; either version 1, or (at your option) any
389 later version, or
390
391 b) the "Artistic License" which comes with this Kit.
392
393 This program is distributed in the hope that it will be useful,
394 but WITHOUT ANY WARRANTY; without even the implied warranty of
395 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
396 the GNU General Public License or the Artistic License for more details.
397
398 You should have received a copy of the Artistic License with this
399 Kit, in the file named "Artistic". If not, I'll be glad to provide one.
400
401 You should also have received a copy of the GNU General Public License
402 along with this program in the file named "Copying". If not, write to the
403 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
404 02111-1307, USA or visit their web page on the internet at
405 http://www.gnu.org/copyleft/gpl.html.
406
407 For those of you that choose to use the GNU General Public License,
408 my interpretation of the GNU General Public License is that no Perl
409 script falls under the terms of the GPL unless you explicitly put
410 said script under the terms of the GPL yourself. Furthermore, any
411 object code linked with perl does not automatically fall under the
412 terms of the GPL, provided such object code only adds definitions
413 of subroutines and variables, and does not otherwise impair the
414 resulting interpreter from executing any standard Perl script. I
415 consider linking in C subroutines in this manner to be the moral
416 equivalent of defining subroutines in the Perl language itself. You
417 may sell such an object file as proprietary provided that you provide
418 or offer to provide the Perl source, as specified by the GNU General
419 Public License. (This is merely an alternate way of specifying input
420 to the program.) You may also sell a binary produced by the dumping of
421 a running Perl script that belongs to you, provided that you provide or
422 offer to provide the Perl source as specified by the GPL. (The
423 fact that a Perl interpreter and your code are in the same binary file
424 is, in this case, a form of mere aggregation.) This is my interpretation
425 of the GPL. If you still have concerns or difficulties understanding
426 my intent, feel free to contact me. Of course, the Artistic License
427 spells all this out for your protection, so you may prefer to use that.
428
1be0b951 429=cut