lib/AutoLoader.pm

   1 package AutoLoader;
   2 use Carp;
   3 $DB::sub = $DB::sub;    # Avoid warning
   4
   5 =head1 NAME
   6
   7 AutoLoader - load functions only on demand
   8
   9 =head1 SYNOPSIS
  10
  11     package FOOBAR;
  12     use Exporter;
  13     use AutoLoader;
  14     @ISA = (Exporter, AutoLoader);
  15
  16 =head1 DESCRIPTION
  17
  18 This module tells its users that functions in the FOOBAR package are
  19 to be autoloaded from F<auto/$AUTOLOAD.al>.  See
  20 L<perlsub/"Autoloading"> and L<AutoSplit>.
  21
  22 =head2 __END__
  23
  24 The module using the autoloader should have the special marker C<__END__>
  25 prior to the actual subroutine declarations. All code that is before the
  26 marker will be loaded and compiled when the module is used. At the marker,
  27 perl will cease reading and parsing. See also the B<AutoSplit> module, a
  28 utility that automatically splits a module into a collection of files for
  29 autoloading.
  30
  31 When a subroutine not yet in memory is called, the C<AUTOLOAD> function
  32 attempts to locate it in a directory relative to the location of the module
  33 file itself. As an example, assume F<POSIX.pm> is located in
  34 F</usr/local/lib/perl5/POSIX.pm>. The autoloader will look for perl
  35 subroutines for this package in F</usr/local/lib/perl5/auto/POSIX/*.al>.
  36 The C<.al> file is named using the subroutine name, sans package.
  37
  38 =head2 Package Lexicals
  39
  40 Package lexicals declared with C<my> in the main block of a package using
  41 the B<AutoLoader> will not be visible to auto-loaded functions, due to the
  42 fact that the given scope ends at the C<__END__> marker. A module using such
  43 variables as package globals will not work properly under the B<AutoLoader>.
  44
  45 The C<vars> pragma (see L<perlmod/"vars">) may be used in such situations
  46 as an alternative to explicitly qualifying all globals with the package
  47 namespace. Variables pre-declared with this pragma will be visible to any
  48 autoloaded routines (but will not be invisible outside the package,
  49 unfortunately).
  50
  51 =head2 AutoLoader vs. SelfLoader
  52
  53 The B<AutoLoader> is a counterpart to the B<SelfLoader> module. Both delay
  54 the loading of subroutines, but the B<SelfLoader> accomplishes the goal via
  55 the C<__DATA__> marker rather than C<__END__>. While this avoids the use of
  56 a hierarchy of disk files and the associated open/close for each routine
  57 loaded, the B<SelfLoader> suffers a disadvantage in the one-time parsing of
  58 the lines after C<__DATA__>, after which routines are cached. B<SelfLoader>
  59 can also handle multiple packages in a file.
  60
  61 B<AutoLoader> only reads code as it is requested, and in many cases should be
  62 faster, but requires a machanism like B<AutoSplit> be used to create the
  63 individual files.
  64
  65 =head1 CAVEAT
  66
  67 On systems with restrictions on file name length, the file corresponding to a
  68 subroutine may have a shorter name that the routine itself. This can lead to
  69 conflicting file names. The I<AutoSplit> package warns of these potential
  70 conflicts when used to split a module.
  71
  72 =cut
  73
  74 AUTOLOAD {
  75     my $name = "auto/$AUTOLOAD.al";
  76     $name =~ s#::#/#g;
  77     eval {require $name};
  78     if ($@) {
  79         # The load might just have failed because the filename was too
  80         # long for some old SVR3 systems which treat long names as errors.
  81         # If we can succesfully truncate a long name then it's worth a go.
  82         # There is a slight risk that we could pick up the wrong file here
  83         # but autosplit should have warned about that when splitting.
  84         if ($name =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
  85             eval {require $name};
  86         }
  87         elsif ($AUTOLOAD =~ /::DESTROY$/) {
  88             # eval "sub $AUTOLOAD {}";
  89             *$AUTOLOAD = sub {};
  90         }
  91         if ($@){
  92             $@ =~ s/ at .*\n//;
  93             croak $@;
  94         }
  95     }
  96     $DB::sub = $AUTOLOAD;       # Now debugger know where we are.
  97     goto &$AUTOLOAD;
  98 }
  99
 100 sub import {
 101     my ($callclass, $callfile, $callline,$path,$callpack) = caller(0);
 102     ($callpack = $callclass) =~ s#::#/#;
 103     # Try to find the autosplit index file.  Eg., if the call package
 104     # is POSIX, then $INC{POSIX.pm} is something like
 105     # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
 106     # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
 107     #
 108     # However, if @INC is a relative path, this might not work.  If,
 109     # for example, @INC = ('lib'), then
 110     # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
 111     # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
 112     #
 113     if (defined($path = $INC{$callpack . '.pm'})) {
 114         # Try absolute path name.
 115         $path =~ s#^(.*)$callpack\.pm$#$1auto/$callpack/autosplit.ix#;
 116         eval { require $path; };
 117         # If that failed, try relative path with normal @INC searching.
 118         if ($@) {
 119             $path ="auto/$callpack/autosplit.ix";
 120             eval { require $path; };
 121         }
 122         carp $@ if ($@);
 123     }
 124 }
 125
 126 1;