3 $DB::sub = $DB::sub; # Avoid warning
7 AutoLoader - load functions only on demand
14 @ISA = qw(Exporter AutoLoader);
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>.
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
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.
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
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:
51 use AutoLoader; # load stubs
53 sub import {} # hide AutoLoader::import
55 You can also set up autoloading by importing the AUTOLOAD function
56 instead of inheriting from B<AutoLoader>:
59 use AutoLoader; # load stubs
60 *AUTOLOAD = \&AutoLoader::AUTOLOAD;
63 =head2 Package Lexicals
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>.
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,
76 =head2 AutoLoader vs. SelfLoader
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.
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.
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.
101 my $name = "auto/$AUTOLOAD.al";
102 # Braces used on the s/// below to preserve $1 et al.
105 eval {require $name};
107 if (substr($AUTOLOAD,-9) eq '::DESTROY') {
110 # The load might just have failed because the filename was too
111 # long for some old SVR3 systems which treat long names as errors.
112 # If we can succesfully truncate a long name then it's worth a go.
113 # There is a slight risk that we could pick up the wrong file here
114 # but autosplit should have warned about that when splitting.
115 if ($name =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
116 eval {require $name};
125 $DB::sub = $AUTOLOAD; # Now debugger know where we are.
130 my ($callclass, $callfile, $callline,$path,$callpack) = caller(0);
131 ($callpack = $callclass) =~ s#::#/#;
132 # Try to find the autosplit index file. Eg., if the call package
133 # is POSIX, then $INC{POSIX.pm} is something like
134 # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
135 # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
137 # However, if @INC is a relative path, this might not work. If,
138 # for example, @INC = ('lib'), then
139 # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
140 # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
142 if (defined($path = $INC{$callpack . '.pm'})) {
143 # Try absolute path name.
144 $path =~ s#^(.*)$callpack\.pm$#$1auto/$callpack/autosplit.ix#;
145 eval { require $path; };
146 # If that failed, try relative path with normal @INC searching.
148 $path ="auto/$callpack/autosplit.ix";
149 eval { require $path; };