[Summary view] [Print] [Text view]

   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.63';
  19  }
  20  
  21  AUTOLOAD {
  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  
  54  sub can {
  55      my ($self, $method) = @_;
  56  
  57      my $parent          = $self->SUPER::can( $method );
  58      return $parent if $parent;
  59  
  60      my $package         = ref( $self ) || $self;
  61      my $filename        = AutoLoader::find_filename( $package . '::' . $method );
  62      local $@;
  63      return unless eval { require $filename };
  64  
  65      no strict 'refs';
  66      return \&{ $package . '::' . $method };
  67  }
  68  
  69  sub find_filename {
  70      my $sub = shift;
  71      my $filename;
  72      # Braces used to preserve $1 et al.
  73      {
  74      # Try to find the autoloaded file from the package-qualified
  75      # name of the sub. e.g., if the sub needed is
  76      # Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
  77      # something like '/usr/lib/perl5/Getopt/Long.pm', and the
  78      # autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
  79      #
  80      # However, if @INC is a relative path, this might not work.  If,
  81      # for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
  82      # 'lib/Getopt/Long.pm', and we want to require
  83      # 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
  84      # In this case, we simple prepend the 'auto/' and let the
  85      # C<require> take care of the searching for us.
  86  
  87      my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
  88      $pkg =~ s#::#/#g;
  89      if (defined($filename = $INC{"$pkg.pm"})) {
  90          if ($is_macos) {
  91          $pkg =~ tr#/#:#;
  92          $filename = undef
  93            unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
  94          } else {
  95          $filename = undef
  96            unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
  97          }
  98  
  99          # if the file exists, then make sure that it is a
 100          # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
 101          # or './lib/auto/foo/bar.al'.  This avoids C<require> searching
 102          # (and failing) to find the 'lib/auto/foo/bar.al' because it
 103          # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
 104  
 105          if (defined $filename and -r $filename) {
 106          unless ($filename =~ m|^/|s) {
 107              if ($is_dosish) {
 108              unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
 109                  if ($^O ne 'NetWare') {
 110                  $filename = "./$filename";
 111                  } else {
 112                  $filename = "$filename";
 113                  }
 114              }
 115              }
 116              elsif ($is_epoc) {
 117              unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
 118                   $filename = "./$filename";
 119              }
 120              }
 121              elsif ($is_vms) {
 122              # XXX todo by VMSmiths
 123              $filename = "./$filename";
 124              }
 125              elsif (!$is_macos) {
 126              $filename = "./$filename";
 127              }
 128          }
 129          }
 130          else {
 131          $filename = undef;
 132          }
 133      }
 134      unless (defined $filename) {
 135          # let C<require> do the searching
 136          $filename = "auto/$sub.al";
 137          $filename =~ s#::#/#g;
 138      }
 139      }
 140      return $filename;
 141  }
 142  
 143  sub import {
 144      my $pkg = shift;
 145      my $callpkg = caller;
 146  
 147      #
 148      # Export symbols, but not by accident of inheritance.
 149      #
 150  
 151      if ($pkg eq 'AutoLoader') {
 152      if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) {
 153          no strict 'refs';
 154          *{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD;
 155          *{ $callpkg . '::can'      } = \&can;
 156      }
 157      }
 158  
 159      #
 160      # Try to find the autosplit index file.  Eg., if the call package
 161      # is POSIX, then $INC{POSIX.pm} is something like
 162      # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
 163      # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
 164      #
 165      # However, if @INC is a relative path, this might not work.  If,
 166      # for example, @INC = ('lib'), then
 167      # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
 168      # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
 169      #
 170  
 171      (my $calldir = $callpkg) =~ s#::#/#g;
 172      my $path = $INC{$calldir . '.pm'};
 173      if (defined($path)) {
 174      # Try absolute path name.
 175      if ($is_macos) {
 176          (my $malldir = $calldir) =~ tr#/#:#;
 177          $path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s;
 178      } else {
 179          $path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#;
 180      }
 181  
 182      eval { require $path; };
 183      # If that failed, try relative path with normal @INC searching.
 184      if ($@) {
 185          $path ="auto/$calldir/autosplit.ix";
 186          eval { require $path; };
 187      }
 188      if ($@) {
 189          my $error = $@;
 190          require Carp;
 191          Carp::carp($error);
 192      }
 193      } 
 194  }
 195  
 196  sub unimport {
 197      my $callpkg = caller;
 198  
 199      no strict 'refs';
 200  
 201      for my $exported (qw( AUTOLOAD can )) {
 202      my $symname = $callpkg . '::' . $exported;
 203      undef *{ $symname } if \&{ $symname } == \&{ $exported };
 204      *{ $symname } = \&{ $symname };
 205      }
 206  }
 207  
 208  1;
 209  
 210  __END__
 211  
 212  =head1 NAME
 213  
 214  AutoLoader - load subroutines only on demand
 215  
 216  =head1 SYNOPSIS
 217  
 218      package Foo;
 219      use AutoLoader 'AUTOLOAD';   # import the default AUTOLOAD subroutine
 220  
 221      package Bar;
 222      use AutoLoader;              # don't import AUTOLOAD, define our own
 223      sub AUTOLOAD {
 224          ...
 225          $AutoLoader::AUTOLOAD = "...";
 226          goto &AutoLoader::AUTOLOAD;
 227      }
 228  
 229  =head1 DESCRIPTION
 230  
 231  The B<AutoLoader> module works with the B<AutoSplit> module and the
 232  C<__END__> token to defer the loading of some subroutines until they are
 233  used rather than loading them all at once.
 234  
 235  To use B<AutoLoader>, the author of a module has to place the
 236  definitions of subroutines to be autoloaded after an C<__END__> token.
 237  (See L<perldata>.)  The B<AutoSplit> module can then be run manually to
 238  extract the definitions into individual files F<auto/funcname.al>.
 239  
 240  B<AutoLoader> implements an AUTOLOAD subroutine.  When an undefined
 241  subroutine in is called in a client module of B<AutoLoader>,
 242  B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
 243  file with a name related to the location of the file from which the
 244  client module was read.  As an example, if F<POSIX.pm> is located in
 245  F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
 246  subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
 247  the C<.al> file has the same name as the subroutine, sans package.  If
 248  such a file exists, AUTOLOAD will read and evaluate it,
 249  thus (presumably) defining the needed subroutine.  AUTOLOAD will then
 250  C<goto> the newly defined subroutine.
 251  
 252  Once this process completes for a given function, it is defined, so
 253  future calls to the subroutine will bypass the AUTOLOAD mechanism.
 254  
 255  =head2 Subroutine Stubs
 256  
 257  In order for object method lookup and/or prototype checking to operate
 258  correctly even when methods have not yet been defined it is necessary to
 259  "forward declare" each subroutine (as in C<sub NAME;>).  See
 260  L<perlsub/"SYNOPSIS">.  Such forward declaration creates "subroutine
 261  stubs", which are place holders with no code.
 262  
 263  The AutoSplit and B<AutoLoader> modules automate the creation of forward
 264  declarations.  The AutoSplit module creates an 'index' file containing
 265  forward declarations of all the AutoSplit subroutines.  When the
 266  AutoLoader module is 'use'd it loads these declarations into its callers
 267  package.
 268  
 269  Because of this mechanism it is important that B<AutoLoader> is always
 270  C<use>d and not C<require>d.
 271  
 272  =head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
 273  
 274  In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
 275  explicitly import it:
 276  
 277      use AutoLoader 'AUTOLOAD';
 278  
 279  =head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
 280  
 281  Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
 282  They typically need to check for some special cases (such as constants)
 283  and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
 284  
 285  Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
 286  Instead, they should define their own AUTOLOAD subroutines along these
 287  lines:
 288  
 289      use AutoLoader;
 290      use Carp;
 291  
 292      sub AUTOLOAD {
 293          my $sub = $AUTOLOAD;
 294          (my $constname = $sub) =~ s/.*:://;
 295          my $val = constant($constname, @_ ? $_[0] : 0);
 296          if ($! != 0) {
 297              if ($! =~ /Invalid/ || $!{EINVAL}) {
 298                  $AutoLoader::AUTOLOAD = $sub;
 299                  goto &AutoLoader::AUTOLOAD;
 300              }
 301              else {
 302                  croak "Your vendor has not defined constant $constname";
 303              }
 304          }
 305          *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
 306          goto &$sub;
 307      }
 308  
 309  If any module's own AUTOLOAD subroutine has no need to fallback to the
 310  AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
 311  subroutines), then that module should not use B<AutoLoader> at all.
 312  
 313  =head2 Package Lexicals
 314  
 315  Package lexicals declared with C<my> in the main block of a package
 316  using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
 317  the fact that the given scope ends at the C<__END__> marker.  A module
 318  using such variables as package globals will not work properly under the
 319  B<AutoLoader>.
 320  
 321  The C<vars> pragma (see L<perlmod/"vars">) may be used in such
 322  situations as an alternative to explicitly qualifying all globals with
 323  the package namespace.  Variables pre-declared with this pragma will be
 324  visible to any autoloaded routines (but will not be invisible outside
 325  the package, unfortunately).
 326  
 327  =head2 Not Using AutoLoader
 328  
 329  You can stop using AutoLoader by simply
 330  
 331      no AutoLoader;
 332  
 333  =head2 B<AutoLoader> vs. B<SelfLoader>
 334  
 335  The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
 336  loading of subroutines.
 337  
 338  B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
 339  While this avoids the use of a hierarchy of disk files and the
 340  associated open/close for each routine loaded, B<SelfLoader> suffers a
 341  startup speed disadvantage in the one-time parsing of the lines after
 342  C<__DATA__>, after which routines are cached.  B<SelfLoader> can also
 343  handle multiple packages in a file.
 344  
 345  B<AutoLoader> only reads code as it is requested, and in many cases
 346  should be faster, but requires a mechanism like B<AutoSplit> be used to
 347  create the individual files.  L<ExtUtils::MakeMaker> will invoke
 348  B<AutoSplit> automatically if B<AutoLoader> is used in a module source
 349  file.
 350  
 351  =head1 CAVEATS
 352  
 353  AutoLoaders prior to Perl 5.002 had a slightly different interface.  Any
 354  old modules which use B<AutoLoader> should be changed to the new calling
 355  style.  Typically this just means changing a require to a use, adding
 356  the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
 357  from C<@ISA>.
 358  
 359  On systems with restrictions on file name length, the file corresponding
 360  to a subroutine may have a shorter name that the routine itself.  This
 361  can lead to conflicting file names.  The I<AutoSplit> package warns of
 362  these potential conflicts when used to split a module.
 363  
 364  AutoLoader may fail to find the autosplit files (or even find the wrong
 365  ones) in cases where C<@INC> contains relative paths, B<and> the program
 366  does C<chdir>.
 367  
 368  =head1 SEE ALSO
 369  
 370  L<SelfLoader> - an autoloader that doesn't use external files.
 371  
 372  =cut