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