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