home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / Savant.exe / disk1 / data1.cab / Perl5 / perl5 / lib / autoloader.pm < prev    next >
Encoding:
Perl POD Document  |  2001-02-23  |  6.0 KB  |  160 lines
  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 = qw(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 Loading Stubs
  39.  
  40. The B<AutoLoader> module provide a special import() method that will
  41. load the stubs (from F<autosplit.ix> file) of the calling module.
  42. These stubs are needed to make inheritance work correctly for class
  43. modules.
  44.  
  45. Modules that inherit from B<AutoLoader> should always ensure that they
  46. override the AutoLoader->import() method.  If the module inherit from
  47. B<Exporter> like shown in the I<synopis> section this is already taken
  48. care of.  For class methods an empty import() would do nicely:
  49.  
  50.   package MyClass;
  51.   use AutoLoader;        # load stubs
  52.   @ISA=qw(AutoLoader);
  53.   sub import {}          # hide AutoLoader::import
  54.  
  55. You can also set up autoloading by importing the AUTOLOAD function
  56. instead of inheriting from B<AutoLoader>:
  57.  
  58.   package MyClass;
  59.   use AutoLoader;        # load stubs
  60.   *AUTOLOAD = \&AutoLoader::AUTOLOAD;
  61.  
  62.  
  63. =head2 Package Lexicals
  64.  
  65. Package lexicals declared with C<my> in the main block of a package using
  66. the B<AutoLoader> will not be visible to auto-loaded functions, due to the
  67. fact that the given scope ends at the C<__END__> marker. A module using such
  68. variables as package globals will not work properly under the B<AutoLoader>.
  69.  
  70. The C<vars> pragma (see L<perlmod/"vars">) may be used in such situations
  71. as an alternative to explicitly qualifying all globals with the package
  72. namespace. Variables pre-declared with this pragma will be visible to any
  73. autoloaded routines (but will not be invisible outside the package,
  74. unfortunately).
  75.  
  76. =head2 AutoLoader vs. SelfLoader
  77.  
  78. The B<AutoLoader> is a counterpart to the B<SelfLoader> module. Both delay
  79. the loading of subroutines, but the B<SelfLoader> accomplishes the goal via
  80. the C<__DATA__> marker rather than C<__END__>. While this avoids the use of
  81. a hierarchy of disk files and the associated open/close for each routine
  82. loaded, the B<SelfLoader> suffers a disadvantage in the one-time parsing of
  83. the lines after C<__DATA__>, after which routines are cached. B<SelfLoader>
  84. can also handle multiple packages in a file.
  85.  
  86. B<AutoLoader> only reads code as it is requested, and in many cases should be
  87. faster, but requires a machanism like B<AutoSplit> be used to create the
  88. individual files.  The B<ExtUtils::MakeMaker> will invoke B<AutoSplit>
  89. automatically if the B<AutoLoader> is used in a module source file.
  90.  
  91. =head1 CAVEAT
  92.  
  93. On systems with restrictions on file name length, the file corresponding to a
  94. subroutine may have a shorter name that the routine itself. This can lead to
  95. conflicting file names. The I<AutoSplit> package warns of these potential
  96. conflicts when used to split a module.
  97.  
  98. Calling foo($1) for the autoloaded function foo() might not work as
  99. expected, because the AUTOLOAD function of B<AutoLoader> clobbers the
  100. regexp variables.  Invoking it as foo("$1") avoids this problem.
  101.  
  102. =cut
  103.  
  104. AUTOLOAD {
  105.     my $name = "auto/$AUTOLOAD.al";
  106.     # Braces used on the s/// below to preserve $1 et al.
  107.     {$name =~ s#::#/#g}
  108.     my $save = $@;
  109.     eval {require $name};
  110.     if ($@) {
  111.     if (substr($AUTOLOAD,-9) eq '::DESTROY') {
  112.         *$AUTOLOAD = sub {};
  113.     } else {
  114.         # The load might just have failed because the filename was too
  115.         # long for some old SVR3 systems which treat long names as errors.
  116.         # If we can succesfully truncate a long name then it's worth a go.
  117.         # There is a slight risk that we could pick up the wrong file here
  118.         # but autosplit should have warned about that when splitting.
  119.         if ($name =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
  120.         eval {require $name};
  121.         }
  122.         if ($@){
  123.         $@ =~ s/ at .*\n//;
  124.         croak $@;
  125.         }
  126.     }
  127.     }
  128.     $@ = $save;
  129.     $DB::sub = $AUTOLOAD;    # Now debugger know where we are.
  130.     goto &$AUTOLOAD;
  131. }
  132.                             
  133. sub import {
  134.     my ($callclass, $callfile, $callline,$path,$callpack) = caller(0);
  135.     ($callpack = $callclass) =~ s#::#/#;
  136.     # Try to find the autosplit index file.  Eg., if the call package
  137.     # is POSIX, then $INC{POSIX.pm} is something like
  138.     # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
  139.     # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
  140.     #
  141.     # However, if @INC is a relative path, this might not work.  If,
  142.     # for example, @INC = ('lib'), then
  143.     # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
  144.     # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
  145.     #
  146.     if (defined($path = $INC{$callpack . '.pm'})) {
  147.     # Try absolute path name.
  148.     $path =~ s#^(.*)$callpack\.pm$#$1auto/$callpack/autosplit.ix#;
  149.     eval { require $path; };
  150.     # If that failed, try relative path with normal @INC searching.
  151.     if ($@) {
  152.         $path ="auto/$callpack/autosplit.ix";
  153.         eval { require $path; };
  154.     }
  155.     carp $@ if ($@);  
  156.     } 
  157. }
  158.  
  159. 1;
  160.