lib/AutoLoader.pm

   1 package AutoLoader;
   2
   3 use vars qw(@EXPORT @EXPORT_OK $VERSION);
   4
   5 my $is_dosish;
   6 my $is_vms;
   7
   8 BEGIN {
   9     require Exporter;
  10     @EXPORT = ();
  11     @EXPORT_OK = qw(AUTOLOAD);
  12     $is_dosish = $^O eq 'dos' || $^O eq 'os2' || $^O eq 'MSWin32';
  13     $is_vms = $^O eq 'VMS';
  14     $VERSION = '5.55';
  15 }
  16
  17 AUTOLOAD {
  18     my $name;
  19     # Braces used to preserve $1 et al.
  20     {
  21         # Try to find the autoloaded file from the package-qualified
  22         # name of the sub. e.g., if the sub needed is
  23         # Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
  24         # something like '/usr/lib/perl5/Getopt/Long.pm', and the
  25         # autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
  26         #
  27         # However, if @INC is a relative path, this might not work.  If,
  28         # for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
  29         # 'lib/Getopt/Long.pm', and we want to require
  30         # 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
  31         # In this case, we simple prepend the 'auto/' and let the
  32         # C<require> take care of the searching for us.
  33
  34         my ($pkg,$func) = $AUTOLOAD =~ /(.*)::([^:]+)$/;
  35         $pkg =~ s#::#/#g;
  36         if (defined($name=$INC{"$pkg.pm"})) {
  37             $name =~ s#^(.*)$pkg\.pm$#$1auto/$pkg/$func.al#;
  38
  39             # if the file exists, then make sure that it is a
  40             # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
  41             # or './lib/auto/foo/bar.al'.  This avoids C<require> searching
  42             # (and failing) to find the 'lib/auto/foo/bar.al' because it
  43             # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
  44
  45             if (-r $name) {
  46                 unless ($name =~ m|^/|) {
  47                     if ($is_dosish) {
  48                         unless ($name =~ m{^([a-z]:)?[\\/]}i) {
  49                              $name = "./$name";
  50                         }
  51                     }
  52                     elsif ($is_vms) {
  53                         # XXX todo by VMSmiths
  54                         $name = "./$name";
  55                     }
  56                     else {
  57                         $name = "./$name";
  58                     }
  59                 }
  60             }
  61             else {
  62                 $name = undef;
  63             }
  64         }
  65         unless (defined $name) {
  66             # let C<require> do the searching
  67             $name = "auto/$AUTOLOAD.al";
  68             $name =~ s#::#/#g;
  69         }
  70     }
  71     my $save = $@;
  72     eval { local $SIG{__DIE__}; require $name };
  73     if ($@) {
  74         if (substr($AUTOLOAD,-9) eq '::DESTROY') {
  75             *$AUTOLOAD = sub {};
  76         } else {
  77             # The load might just have failed because the filename was too
  78             # long for some old SVR3 systems which treat long names as errors.
  79             # If we can succesfully truncate a long name then it's worth a go.
  80             # There is a slight risk that we could pick up the wrong file here
  81             # but autosplit should have warned about that when splitting.
  82             if ($name =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
  83                 eval {local $SIG{__DIE__};require $name};
  84             }
  85             if ($@){
  86                 $@ =~ s/ at .*\n//;
  87                 my $error = $@;
  88                 require Carp;
  89                 Carp::croak($error);
  90             }
  91         }
  92     }
  93     $@ = $save;
  94     goto &$AUTOLOAD;
  95 }
  96
  97 sub import {
  98     my $pkg = shift;
  99     my $callpkg = caller;
 100
 101     #
 102     # Export symbols, but not by accident of inheritance.
 103     #
 104
 105     Exporter::export $pkg, $callpkg, @_ if $pkg eq 'AutoLoader';
 106
 107     #
 108     # Try to find the autosplit index file.  Eg., if the call package
 109     # is POSIX, then $INC{POSIX.pm} is something like
 110     # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
 111     # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
 112     #
 113     # However, if @INC is a relative path, this might not work.  If,
 114     # for example, @INC = ('lib'), then
 115     # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
 116     # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
 117     #
 118
 119     (my $calldir = $callpkg) =~ s#::#/#g;
 120     my $path = $INC{$calldir . '.pm'};
 121     if (defined($path)) {
 122         # Try absolute path name.
 123         $path =~ s#^(.*)$calldir\.pm$#$1auto/$calldir/autosplit.ix#;
 124         eval { require $path; };
 125         # If that failed, try relative path with normal @INC searching.
 126         if ($@) {
 127             $path ="auto/$calldir/autosplit.ix";
 128             eval { require $path; };
 129         }
 130         if ($@) {
 131             my $error = $@;
 132             require Carp;
 133             Carp::carp($error);
 134         }
 135     }
 136 }
 137
 138 1;
 139
 140 __END__
 141
 142 =head1 NAME
 143
 144 AutoLoader - load subroutines only on demand
 145
 146 =head1 SYNOPSIS
 147
 148     package Foo;
 149     use AutoLoader 'AUTOLOAD';   # import the default AUTOLOAD subroutine
 150
 151     package Bar;
 152     use AutoLoader;              # don't import AUTOLOAD, define our own
 153     sub AUTOLOAD {
 154         ...
 155         $AutoLoader::AUTOLOAD = "...";
 156         goto &AutoLoader::AUTOLOAD;
 157     }
 158
 159 =head1 DESCRIPTION
 160
 161 The B<AutoLoader> module works with the B<AutoSplit> module and the
 162 C<__END__> token to defer the loading of some subroutines until they are
 163 used rather than loading them all at once.
 164
 165 To use B<AutoLoader>, the author of a module has to place the
 166 definitions of subroutines to be autoloaded after an C<__END__> token.
 167 (See L<perldata>.)  The B<AutoSplit> module can then be run manually to
 168 extract the definitions into individual files F<auto/funcname.al>.
 169
 170 B<AutoLoader> implements an AUTOLOAD subroutine.  When an undefined
 171 subroutine in is called in a client module of B<AutoLoader>,
 172 B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
 173 file with a name related to the location of the file from which the
 174 client module was read.  As an example, if F<POSIX.pm> is located in
 175 F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
 176 subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
 177 the C<.al> file has the same name as the subroutine, sans package.  If
 178 such a file exists, AUTOLOAD will read and evaluate it,
 179 thus (presumably) defining the needed subroutine.  AUTOLOAD will then
 180 C<goto> the newly defined subroutine.
 181
 182 Once this process completes for a given function, it is defined, so
 183 future calls to the subroutine will bypass the AUTOLOAD mechanism.
 184
 185 =head2 Subroutine Stubs
 186
 187 In order for object method lookup and/or prototype checking to operate
 188 correctly even when methods have not yet been defined it is necessary to
 189 "forward declare" each subroutine (as in C<sub NAME;>).  See
 190 L<perlsub/"SYNOPSIS">.  Such forward declaration creates "subroutine
 191 stubs", which are place holders with no code.
 192
 193 The AutoSplit and B<AutoLoader> modules automate the creation of forward
 194 declarations.  The AutoSplit module creates an 'index' file containing
 195 forward declarations of all the AutoSplit subroutines.  When the
 196 AutoLoader module is 'use'd it loads these declarations into its callers
 197 package.
 198
 199 Because of this mechanism it is important that B<AutoLoader> is always
 200 C<use>d and not C<require>d.
 201
 202 =head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
 203
 204 In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
 205 explicitly import it:
 206
 207     use AutoLoader 'AUTOLOAD';
 208
 209 =head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
 210
 211 Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
 212 They typically need to check for some special cases (such as constants)
 213 and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
 214
 215 Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
 216 Instead, they should define their own AUTOLOAD subroutines along these
 217 lines:
 218
 219     use AutoLoader;
 220     use Carp;
 221
 222     sub AUTOLOAD {
 223         my $constname;
 224         ($constname = $AUTOLOAD) =~ s/.*:://;
 225         my $val = constant($constname, @_ ? $_[0] : 0);
 226         if ($! != 0) {
 227             if ($! =~ /Invalid/) {
 228                 $AutoLoader::AUTOLOAD = $AUTOLOAD;
 229                 goto &AutoLoader::AUTOLOAD;
 230             }
 231             else {
 232                 croak "Your vendor has not defined constant $constname";
 233             }
 234         }
 235         *$AUTOLOAD = sub { $val }; # same as: eval "sub $AUTOLOAD { $val }";
 236         goto &$AUTOLOAD;
 237     }
 238
 239 If any module's own AUTOLOAD subroutine has no need to fallback to the
 240 AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
 241 subroutines), then that module should not use B<AutoLoader> at all.
 242
 243 =head2 Package Lexicals
 244
 245 Package lexicals declared with C<my> in the main block of a package
 246 using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
 247 the fact that the given scope ends at the C<__END__> marker.  A module
 248 using such variables as package globals will not work properly under the
 249 B<AutoLoader>.
 250
 251 The C<vars> pragma (see L<perlmod/"vars">) may be used in such
 252 situations as an alternative to explicitly qualifying all globals with
 253 the package namespace.  Variables pre-declared with this pragma will be
 254 visible to any autoloaded routines (but will not be invisible outside
 255 the package, unfortunately).
 256
 257 =head2 B<AutoLoader> vs. B<SelfLoader>
 258
 259 The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
 260 loading of subroutines.
 261
 262 B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
 263 While this avoids the use of a hierarchy of disk files and the
 264 associated open/close for each routine loaded, B<SelfLoader> suffers a
 265 startup speed disadvantage in the one-time parsing of the lines after
 266 C<__DATA__>, after which routines are cached.  B<SelfLoader> can also
 267 handle multiple packages in a file.
 268
 269 B<AutoLoader> only reads code as it is requested, and in many cases
 270 should be faster, but requires a mechanism like B<AutoSplit> be used to
 271 create the individual files.  L<ExtUtils::MakeMaker> will invoke
 272 B<AutoSplit> automatically if B<AutoLoader> is used in a module source
 273 file.
 274
 275 =head1 CAVEATS
 276
 277 AutoLoaders prior to Perl 5.002 had a slightly different interface.  Any
 278 old modules which use B<AutoLoader> should be changed to the new calling
 279 style.  Typically this just means changing a require to a use, adding
 280 the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
 281 from C<@ISA>.
 282
 283 On systems with restrictions on file name length, the file corresponding
 284 to a subroutine may have a shorter name that the routine itself.  This
 285 can lead to conflicting file names.  The I<AutoSplit> package warns of
 286 these potential conflicts when used to split a module.
 287
 288 AutoLoader may fail to find the autosplit files (or even find the wrong
 289 ones) in cases where C<@INC> contains relative paths, B<and> the program
 290 does C<chdir>.
 291
 292 =head1 SEE ALSO
 293
 294 L<SelfLoader> - an autoloader that doesn't use external files.
 295
 296 =cut