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