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