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.70'; 19} 20 21AUTOLOAD { 22 my $sub = $AUTOLOAD; 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 find_filename { 55 my $sub = shift; 56 my $filename; 57 # Braces used to preserve $1 et al. 58 { 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 72 my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/); 73 $pkg =~ s#::#/#g; 74 if (defined($filename = $INC{"$pkg.pm"})) { 75 if ($is_macos) { 76 $pkg =~ tr#/#:#; 77 $filename = undef 78 unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s; 79 } else { 80 $filename = undef 81 unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s; 82 } 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 90 if (defined $filename and -r $filename) { 91 unless ($filename =~ m|^/|s) { 92 if ($is_dosish) { 93 unless ($filename =~ m{^([a-z]:)?[\\/]}is) { 94 if ($^O ne 'NetWare') { 95 $filename = "./$filename"; 96 } else { 97 $filename = "$filename"; 98 } 99 } 100 } 101 elsif ($is_epoc) { 102 unless ($filename =~ m{^([a-z?]:)?[\\/]}is) { 103 $filename = "./$filename"; 104 } 105 } 106 elsif ($is_vms) { 107 # XXX todo by VMSmiths 108 $filename = "./$filename"; 109 } 110 elsif (!$is_macos) { 111 $filename = "./$filename"; 112 } 113 } 114 } 115 else { 116 $filename = undef; 117 } 118 } 119 unless (defined $filename) { 120 # let C<require> do the searching 121 $filename = "auto/$sub.al"; 122 $filename =~ s#::#/#g; 123 } 124 } 125 return $filename; 126} 127 128sub import { 129 my $pkg = shift; 130 my $callpkg = caller; 131 132 # 133 # Export symbols, but not by accident of inheritance. 134 # 135 136 if ($pkg eq 'AutoLoader') { 137 if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) { 138 no strict 'refs'; 139 *{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD; 140 } 141 } 142 143 # 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 # 154 155 (my $calldir = $callpkg) =~ s#::#/#g; 156 my $path = $INC{$calldir . '.pm'}; 157 if (defined($path)) { 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; 162 if ($is_macos) { 163 (my $malldir = $calldir) =~ tr#/#:#; 164 $replaced_okay = ($path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s); 165 } else { 166 $replaced_okay = ($path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#); 167 } 168 169 eval { require $path; } if $replaced_okay; 170 # If that failed, try relative path with normal @INC searching. 171 if (!$replaced_okay or $@) { 172 $path ="auto/$calldir/autosplit.ix"; 173 eval { require $path; }; 174 } 175 if ($@) { 176 my $error = $@; 177 require Carp; 178 Carp::carp($error); 179 } 180 } 181} 182 183sub unimport { 184 my $callpkg = caller; 185 186 no strict 'refs'; 187 188 for my $exported (qw( AUTOLOAD )) { 189 my $symname = $callpkg . '::' . $exported; 190 undef *{ $symname } if \&{ $symname } == \&{ $exported }; 191 *{ $symname } = \&{ $symname }; 192 } 193} 194 1951; 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 239Once this process completes for a given function, it is defined, so 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; 277 use Carp; 278 279 sub AUTOLOAD { 280 my $sub = $AUTOLOAD; 281 (my $constname = $sub) =~ s/.*:://; 282 my $val = constant($constname, @_ ? $_[0] : 0); 283 if ($! != 0) { 284 if ($! =~ /Invalid/ || $!{EINVAL}) { 285 $AutoLoader::AUTOLOAD = $sub; 286 goto &AutoLoader::AUTOLOAD; 287 } 288 else { 289 croak "Your vendor has not defined constant $constname"; 290 } 291 } 292 *$sub = sub { $val }; # same as: eval "sub $sub { $val }"; 293 goto &$sub; 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 314=head2 Not Using AutoLoader 315 316You can stop using AutoLoader by simply 317 318 no AutoLoader; 319 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 333should be faster, but requires a mechanism like B<AutoSplit> be used to 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 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 355=head1 SEE ALSO 356 357L<SelfLoader> - an autoloader that doesn't use external files. 358 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, 379 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 380 by Larry Wall and others 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 429=cut 430