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