Commit | Line | Data |
8990e307 |
1 | package AutoLoader; |
a0d0e21e |
2 | use Carp; |
1a4c2889 |
3 | $DB::sub = $DB::sub; # Avoid warning |
8990e307 |
4 | |
f06db76b |
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; |
e14baed2 |
14 | @ISA = qw(Exporter AutoLoader); |
f06db76b |
15 | |
16 | =head1 DESCRIPTION |
17 | |
21c92a1d |
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 | |
e14baed2 |
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 | |
21c92a1d |
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 |
e14baed2 |
88 | individual files. The B<ExtUtils::MakeMaker> will invoke B<AutoSplit> |
89 | automatically if the B<AutoLoader> is used in a module source file. |
21c92a1d |
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. |
f06db76b |
97 | |
e14baed2 |
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 | |
f06db76b |
102 | =cut |
103 | |
8990e307 |
104 | AUTOLOAD { |
7c366566 |
105 | my $name = "auto/$AUTOLOAD.al"; |
e14baed2 |
106 | # Braces used on the s/// below to preserve $1 et al. |
107 | {$name =~ s#::#/#g} |
108 | my $save = $@; |
8990e307 |
109 | eval {require $name}; |
110 | if ($@) { |
e14baed2 |
111 | if (substr($AUTOLOAD,-9) eq '::DESTROY') { |
4633a7c4 |
112 | *$AUTOLOAD = sub {}; |
e14baed2 |
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 | } |
a0d0e21e |
126 | } |
8990e307 |
127 | } |
e14baed2 |
128 | $@ = $save; |
5b930e62 |
129 | $DB::sub = $AUTOLOAD; # Now debugger know where we are. |
8990e307 |
130 | goto &$AUTOLOAD; |
131 | } |
f06db76b |
132 | |
c2960299 |
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 ($@); |
f06db76b |
156 | } |
f06db76b |
157 | } |
8990e307 |
158 | |
159 | 1; |