1package AutoLoader; 2 3use strict; 4use 5.006_001; 5 6our($VERSION, $AUTOLOAD); 7 8my $is_dosish; 9my $is_epoc; 10my $is_vms; 11my $is_macos; 12 13BEGIN { 14 $is_dosish = $^O eq 'dos' || $^O eq 'os2' || $^O eq 'MSWin32' || $^O eq 'NetWare'; 15 $is_epoc = $^O eq 'epoc'; 16 $is_vms = $^O eq 'VMS'; 17 $is_macos = $^O eq 'MacOS'; 18 $VERSION = '5.60'; 19} 20 21AUTOLOAD { 22 my $sub = $AUTOLOAD; 23 my $filename; 24 # Braces used to preserve $1 et al. 25 { 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 39 my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/); 40 $pkg =~ s#::#/#g; 41 if (defined($filename = $INC{"$pkg.pm"})) { 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 } 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 55 if (-r $filename) { 56 unless ($filename =~ m|^/|s) { 57 if ($is_dosish) { 58 unless ($filename =~ m{^([a-z]:)?[\\/]}is) { 59 if ($^O ne 'NetWare') { 60 $filename = "./$filename"; 61 } else { 62 $filename = "$filename"; 63 } 64 } 65 } 66 elsif ($is_epoc) { 67 unless ($filename =~ m{^([a-z?]:)?[\\/]}is) { 68 $filename = "./$filename"; 69 } 70 } 71 elsif ($is_vms) { 72 # XXX todo by VMSmiths 73 $filename = "./$filename"; 74 } 75 elsif (!$is_macos) { 76 $filename = "./$filename"; 77 } 78 } 79 } 80 else { 81 $filename = undef; 82 } 83 } 84 unless (defined $filename) { 85 # let C<require> do the searching 86 $filename = "auto/$sub.al"; 87 $filename =~ s#::#/#g; 88 } 89 } 90 my $save = $@; 91 local $!; # Do not munge the value. 92 eval { local $SIG{__DIE__}; require $filename }; 93 if ($@) { 94 if (substr($sub,-9) eq '::DESTROY') { 95 no strict 'refs'; 96 *$sub = sub {}; 97 $@ = undef; 98 } elsif ($@ =~ /^Can't locate/) { 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. 101 # If we can successfully truncate a long name then it's worth a go. 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. 104 if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){ 105 eval { local $SIG{__DIE__}; require $filename }; 106 } 107 } 108 if ($@){ 109 $@ =~ s/ at .*\n//; 110 my $error = $@; 111 require Carp; 112 Carp::croak($error); 113 } 114 } 115 $@ = $save; 116 goto &$sub; 117} 118 119sub import { 120 my $pkg = shift; 121 my $callpkg = caller; 122 123 # 124 # Export symbols, but not by accident of inheritance. 125 # 126 127 if ($pkg eq 'AutoLoader') { 128 no strict 'refs'; 129 *{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD 130 if @_ and $_[0] =~ /^&?AUTOLOAD$/; 131 } 132 133 # 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 # 144 145 (my $calldir = $callpkg) =~ s#::#/#g; 146 my $path = $INC{$calldir . '.pm'}; 147 if (defined($path)) { 148 # Try absolute path name. 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 156 eval { require $path; }; 157 # If that failed, try relative path with normal @INC searching. 158 if ($@) { 159 $path ="auto/$calldir/autosplit.ix"; 160 eval { require $path; }; 161 } 162 if ($@) { 163 my $error = $@; 164 require Carp; 165 Carp::carp($error); 166 } 167 } 168} 169 170sub unimport { 171 my $callpkg = caller; 172 173 no strict 'refs'; 174 my $symname = $callpkg . '::AUTOLOAD'; 175 undef *{ $symname } if \&{ $symname } == \&AUTOLOAD; 176 *{ $symname } = \&{ $symname }; 177} 178 1791; 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 223Once this process completes for a given function, it is defined, so 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; 261 use Carp; 262 263 sub AUTOLOAD { 264 my $sub = $AUTOLOAD; 265 (my $constname = $sub) =~ s/.*:://; 266 my $val = constant($constname, @_ ? $_[0] : 0); 267 if ($! != 0) { 268 if ($! =~ /Invalid/ || $!{EINVAL}) { 269 $AutoLoader::AUTOLOAD = $sub; 270 goto &AutoLoader::AUTOLOAD; 271 } 272 else { 273 croak "Your vendor has not defined constant $constname"; 274 } 275 } 276 *$sub = sub { $val }; # same as: eval "sub $sub { $val }"; 277 goto &$sub; 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 298=head2 Not Using AutoLoader 299 300You can stop using AutoLoader by simply 301 302 no AutoLoader; 303 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 317should be faster, but requires a mechanism like B<AutoSplit> be used to 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 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 339=head1 SEE ALSO 340 341L<SelfLoader> - an autoloader that doesn't use external files. 342 343=cut 344