Some escapes were mentioned twice, although they're not qr//-specific
[p5sagit/p5-mst-13.2.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';
bf230196 18 $VERSION = '5.63';
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
54sub 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
69sub find_filename {
70 my $sub = shift;
7d4fbd98 71 my $filename;
5a556d17 72 # Braces used to preserve $1 et al.
73 {
adaafad2 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 90 if ($is_macos) {
91 $pkg =~ tr#/#:#;
017a05de 92 $filename = undef
93 unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
084592ab 94 } else {
017a05de 95 $filename = undef
96 unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
084592ab 97 }
adaafad2 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 114 }
115 }
ed79a026 116 elsif ($is_epoc) {
117 unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
118 $filename = "./$filename";
119 }
4d6b4052 120 }
121 elsif ($is_vms) {
7d4fbd98 122 # XXX todo by VMSmiths
123 $filename = "./$filename";
adaafad2 124 }
084592ab 125 elsif (!$is_macos) {
7d4fbd98 126 $filename = "./$filename";
adaafad2 127 }
128 }
129 }
130 else {
7d4fbd98 131 $filename = undef;
adaafad2 132 }
133 }
7d4fbd98 134 unless (defined $filename) {
adaafad2 135 # let C<require> do the searching
7d4fbd98 136 $filename = "auto/$sub.al";
137 $filename =~ s#::#/#g;
adaafad2 138 }
5a556d17 139 }
00bb01c7 140 return $filename;
8990e307 141}
1be0b951 142
c2960299 143sub import {
1be0b951 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 158
159 #
c2960299 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 172 my $path = $INC{$calldir . '.pm'};
173 if (defined($path)) {
c2960299 174 # Try absolute path name.
4d6b4052 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 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 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 196sub 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 206}
207
8990e307 2081;
1be0b951 209
210__END__
211
212=head1 NAME
213
214AutoLoader - 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
231The B<AutoLoader> module works with the B<AutoSplit> module and the
232C<__END__> token to defer the loading of some subroutines until they are
233used rather than loading them all at once.
234
235To use B<AutoLoader>, the author of a module has to place the
236definitions of subroutines to be autoloaded after an C<__END__> token.
237(See L<perldata>.) The B<AutoSplit> module can then be run manually to
238extract the definitions into individual files F<auto/funcname.al>.
239
240B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined
241subroutine in is called in a client module of B<AutoLoader>,
242B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
243file with a name related to the location of the file from which the
244client module was read. As an example, if F<POSIX.pm> is located in
245F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
246subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
247the C<.al> file has the same name as the subroutine, sans package. If
248such a file exists, AUTOLOAD will read and evaluate it,
249thus (presumably) defining the needed subroutine. AUTOLOAD will then
250C<goto> the newly defined subroutine.
251
f610777f 252Once this process completes for a given function, it is defined, so
1be0b951 253future calls to the subroutine will bypass the AUTOLOAD mechanism.
254
255=head2 Subroutine Stubs
256
257In order for object method lookup and/or prototype checking to operate
258correctly even when methods have not yet been defined it is necessary to
259"forward declare" each subroutine (as in C<sub NAME;>). See
260L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine
261stubs", which are place holders with no code.
262
263The AutoSplit and B<AutoLoader> modules automate the creation of forward
264declarations. The AutoSplit module creates an 'index' file containing
265forward declarations of all the AutoSplit subroutines. When the
266AutoLoader module is 'use'd it loads these declarations into its callers
267package.
268
269Because of this mechanism it is important that B<AutoLoader> is always
270C<use>d and not C<require>d.
271
272=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
273
274In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
275explicitly import it:
276
277 use AutoLoader 'AUTOLOAD';
278
279=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
280
281Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
282They typically need to check for some special cases (such as constants)
283and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
284
285Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
286Instead, they should define their own AUTOLOAD subroutines along these
287lines:
288
289 use AutoLoader;
fb73857a 290 use Carp;
1be0b951 291
292 sub AUTOLOAD {
7d4fbd98 293 my $sub = $AUTOLOAD;
294 (my $constname = $sub) =~ s/.*:://;
1be0b951 295 my $val = constant($constname, @_ ? $_[0] : 0);
296 if ($! != 0) {
265f5c4a 297 if ($! =~ /Invalid/ || $!{EINVAL}) {
7d4fbd98 298 $AutoLoader::AUTOLOAD = $sub;
1be0b951 299 goto &AutoLoader::AUTOLOAD;
300 }
301 else {
302 croak "Your vendor has not defined constant $constname";
303 }
304 }
7d4fbd98 305 *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
306 goto &$sub;
1be0b951 307 }
308
309If any module's own AUTOLOAD subroutine has no need to fallback to the
310AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
311subroutines), then that module should not use B<AutoLoader> at all.
312
313=head2 Package Lexicals
314
315Package lexicals declared with C<my> in the main block of a package
316using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
317the fact that the given scope ends at the C<__END__> marker. A module
318using such variables as package globals will not work properly under the
319B<AutoLoader>.
320
321The C<vars> pragma (see L<perlmod/"vars">) may be used in such
322situations as an alternative to explicitly qualifying all globals with
323the package namespace. Variables pre-declared with this pragma will be
324visible to any autoloaded routines (but will not be invisible outside
325the package, unfortunately).
326
cb0cff20 327=head2 Not Using AutoLoader
328
329You can stop using AutoLoader by simply
330
331 no AutoLoader;
332
1be0b951 333=head2 B<AutoLoader> vs. B<SelfLoader>
334
335The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
336loading of subroutines.
337
338B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
339While this avoids the use of a hierarchy of disk files and the
340associated open/close for each routine loaded, B<SelfLoader> suffers a
341startup speed disadvantage in the one-time parsing of the lines after
342C<__DATA__>, after which routines are cached. B<SelfLoader> can also
343handle multiple packages in a file.
344
345B<AutoLoader> only reads code as it is requested, and in many cases
f610777f 346should be faster, but requires a mechanism like B<AutoSplit> be used to
1be0b951 347create the individual files. L<ExtUtils::MakeMaker> will invoke
348B<AutoSplit> automatically if B<AutoLoader> is used in a module source
349file.
350
351=head1 CAVEATS
352
353AutoLoaders prior to Perl 5.002 had a slightly different interface. Any
354old modules which use B<AutoLoader> should be changed to the new calling
355style. Typically this just means changing a require to a use, adding
356the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
357from C<@ISA>.
358
359On systems with restrictions on file name length, the file corresponding
360to a subroutine may have a shorter name that the routine itself. This
361can lead to conflicting file names. The I<AutoSplit> package warns of
362these potential conflicts when used to split a module.
363
adaafad2 364AutoLoader may fail to find the autosplit files (or even find the wrong
365ones) in cases where C<@INC> contains relative paths, B<and> the program
366does C<chdir>.
367
1be0b951 368=head1 SEE ALSO
369
370L<SelfLoader> - an autoloader that doesn't use external files.
371
372=cut