| 1 |
package AutoLoader; |
| 2 |
|
| 3 |
use strict; |
| 4 |
use 5.006_001; |
| 5 |
|
| 6 |
our($VERSION, $AUTOLOAD); |
| 7 |
|
| 8 |
my $is_dosish; |
| 9 |
my $is_epoc; |
| 10 |
my $is_vms; |
| 11 |
my $is_macos; |
| 12 |
|
| 13 |
BEGIN { |
| 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 |
|
| 21 |
AUTOLOAD { |
| 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 |
|
| 119 |
sub 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 |
|
| 170 |
sub 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 |
|
| 179 |
1; |
| 180 |
|
| 181 |
__END__ |
| 182 |
|
| 183 |
=head1 NAME |
| 184 |
|
| 185 |
AutoLoader - 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 |
|
| 202 |
The B<AutoLoader> module works with the B<AutoSplit> module and the |
| 203 |
C<__END__> token to defer the loading of some subroutines until they are |
| 204 |
used rather than loading them all at once. |
| 205 |
|
| 206 |
To use B<AutoLoader>, the author of a module has to place the |
| 207 |
definitions of subroutines to be autoloaded after an C<__END__> token. |
| 208 |
(See L<perldata>.) The B<AutoSplit> module can then be run manually to |
| 209 |
extract the definitions into individual files F<auto/funcname.al>. |
| 210 |
|
| 211 |
B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined |
| 212 |
subroutine in is called in a client module of B<AutoLoader>, |
| 213 |
B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a |
| 214 |
file with a name related to the location of the file from which the |
| 215 |
client module was read. As an example, if F<POSIX.pm> is located in |
| 216 |
F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl |
| 217 |
subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where |
| 218 |
the C<.al> file has the same name as the subroutine, sans package. If |
| 219 |
such a file exists, AUTOLOAD will read and evaluate it, |
| 220 |
thus (presumably) defining the needed subroutine. AUTOLOAD will then |
| 221 |
C<goto> the newly defined subroutine. |
| 222 |
|
| 223 |
Once this process completes for a given function, it is defined, so |
| 224 |
future calls to the subroutine will bypass the AUTOLOAD mechanism. |
| 225 |
|
| 226 |
=head2 Subroutine Stubs |
| 227 |
|
| 228 |
In order for object method lookup and/or prototype checking to operate |
| 229 |
correctly even when methods have not yet been defined it is necessary to |
| 230 |
"forward declare" each subroutine (as in C<sub NAME;>). See |
| 231 |
L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine |
| 232 |
stubs", which are place holders with no code. |
| 233 |
|
| 234 |
The AutoSplit and B<AutoLoader> modules automate the creation of forward |
| 235 |
declarations. The AutoSplit module creates an 'index' file containing |
| 236 |
forward declarations of all the AutoSplit subroutines. When the |
| 237 |
AutoLoader module is 'use'd it loads these declarations into its callers |
| 238 |
package. |
| 239 |
|
| 240 |
Because of this mechanism it is important that B<AutoLoader> is always |
| 241 |
C<use>d and not C<require>d. |
| 242 |
|
| 243 |
=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine |
| 244 |
|
| 245 |
In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must> |
| 246 |
explicitly import it: |
| 247 |
|
| 248 |
use AutoLoader 'AUTOLOAD'; |
| 249 |
|
| 250 |
=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine |
| 251 |
|
| 252 |
Some modules, mainly extensions, provide their own AUTOLOAD subroutines. |
| 253 |
They typically need to check for some special cases (such as constants) |
| 254 |
and then fallback to B<AutoLoader>'s AUTOLOAD for the rest. |
| 255 |
|
| 256 |
Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine. |
| 257 |
Instead, they should define their own AUTOLOAD subroutines along these |
| 258 |
lines: |
| 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 |
|
| 280 |
If any module's own AUTOLOAD subroutine has no need to fallback to the |
| 281 |
AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit |
| 282 |
subroutines), then that module should not use B<AutoLoader> at all. |
| 283 |
|
| 284 |
=head2 Package Lexicals |
| 285 |
|
| 286 |
Package lexicals declared with C<my> in the main block of a package |
| 287 |
using B<AutoLoader> will not be visible to auto-loaded subroutines, due to |
| 288 |
the fact that the given scope ends at the C<__END__> marker. A module |
| 289 |
using such variables as package globals will not work properly under the |
| 290 |
B<AutoLoader>. |
| 291 |
|
| 292 |
The C<vars> pragma (see L<perlmod/"vars">) may be used in such |
| 293 |
situations as an alternative to explicitly qualifying all globals with |
| 294 |
the package namespace. Variables pre-declared with this pragma will be |
| 295 |
visible to any autoloaded routines (but will not be invisible outside |
| 296 |
the package, unfortunately). |
| 297 |
|
| 298 |
=head2 Not Using AutoLoader |
| 299 |
|
| 300 |
You can stop using AutoLoader by simply |
| 301 |
|
| 302 |
no AutoLoader; |
| 303 |
|
| 304 |
=head2 B<AutoLoader> vs. B<SelfLoader> |
| 305 |
|
| 306 |
The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the |
| 307 |
loading of subroutines. |
| 308 |
|
| 309 |
B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>. |
| 310 |
While this avoids the use of a hierarchy of disk files and the |
| 311 |
associated open/close for each routine loaded, B<SelfLoader> suffers a |
| 312 |
startup speed disadvantage in the one-time parsing of the lines after |
| 313 |
C<__DATA__>, after which routines are cached. B<SelfLoader> can also |
| 314 |
handle multiple packages in a file. |
| 315 |
|
| 316 |
B<AutoLoader> only reads code as it is requested, and in many cases |
| 317 |
should be faster, but requires a mechanism like B<AutoSplit> be used to |
| 318 |
create the individual files. L<ExtUtils::MakeMaker> will invoke |
| 319 |
B<AutoSplit> automatically if B<AutoLoader> is used in a module source |
| 320 |
file. |
| 321 |
|
| 322 |
=head1 CAVEATS |
| 323 |
|
| 324 |
AutoLoaders prior to Perl 5.002 had a slightly different interface. Any |
| 325 |
old modules which use B<AutoLoader> should be changed to the new calling |
| 326 |
style. Typically this just means changing a require to a use, adding |
| 327 |
the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader> |
| 328 |
from C<@ISA>. |
| 329 |
|
| 330 |
On systems with restrictions on file name length, the file corresponding |
| 331 |
to a subroutine may have a shorter name that the routine itself. This |
| 332 |
can lead to conflicting file names. The I<AutoSplit> package warns of |
| 333 |
these potential conflicts when used to split a module. |
| 334 |
|
| 335 |
AutoLoader may fail to find the autosplit files (or even find the wrong |
| 336 |
ones) in cases where C<@INC> contains relative paths, B<and> the program |
| 337 |
does C<chdir>. |
| 338 |
|
| 339 |
=head1 SEE ALSO |
| 340 |
|
| 341 |
L<SelfLoader> - an autoloader that doesn't use external files. |
| 342 |
|
| 343 |
=cut |
