lib/AutoLoader.pm

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