lib/AutoLoader.pm

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