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