Commit | Line | Data |
---|---|---|
f8881bd9 AD |
1 | package SelfLoader; |
2 | use Carp; | |
3 | require Exporter; | |
4 | @ISA = qw(Exporter); | |
5 | @EXPORT = qw(AUTOLOAD); | |
52128c7b A |
6 | $VERSION = "1.08"; |
7 | sub Version {$VERSION} | |
f8881bd9 AD |
8 | $DEBUG = 0; |
9 | ||
10 | my %Cache; # private cache for all SelfLoader's client packages | |
11 | ||
12 | AUTOLOAD { | |
13 | print STDERR "SelfLoader::AUTOLOAD for $AUTOLOAD\n" if $DEBUG; | |
c7675058 JG |
14 | my $SL_code = $Cache{$AUTOLOAD}; |
15 | unless ($SL_code) { | |
f8881bd9 AD |
16 | # Maybe this pack had stubs before __DATA__, and never initialized. |
17 | # Or, this maybe an automatic DESTROY method call when none exists. | |
18 | $AUTOLOAD =~ m/^(.*)::/; | |
19 | SelfLoader->_load_stubs($1) unless exists $Cache{"${1}::<DATA"}; | |
c7675058 JG |
20 | $SL_code = $Cache{$AUTOLOAD}; |
21 | $SL_code = "sub $AUTOLOAD { }" | |
22 | if (!$SL_code and $AUTOLOAD =~ m/::DESTROY$/); | |
23 | croak "Undefined subroutine $AUTOLOAD" unless $SL_code; | |
f8881bd9 | 24 | } |
c7675058 JG |
25 | print STDERR "SelfLoader::AUTOLOAD eval: $SL_code\n" if $DEBUG; |
26 | eval $SL_code; | |
f8881bd9 AD |
27 | if ($@) { |
28 | $@ =~ s/ at .*\n//; | |
29 | croak $@; | |
30 | } | |
31 | defined(&$AUTOLOAD) || die "SelfLoader inconsistency error"; | |
32 | delete $Cache{$AUTOLOAD}; | |
33 | goto &$AUTOLOAD | |
34 | } | |
35 | ||
36 | sub load_stubs { shift->_load_stubs((caller)[0]) } | |
37 | ||
38 | sub _load_stubs { | |
39 | my($self, $callpack) = @_; | |
40 | my $fh = \*{"${callpack}::DATA"}; | |
41 | my $currpack = $callpack; | |
42 | my($line,$name,@lines, @stubs, $protoype); | |
43 | ||
44 | print STDERR "SelfLoader::load_stubs($callpack)\n" if $DEBUG; | |
45 | croak("$callpack doesn't contain an __DATA__ token") | |
46 | unless fileno($fh); | |
47 | $Cache{"${currpack}::<DATA"} = 1; # indicate package is cached | |
48 | ||
52128c7b | 49 | local($/) = "\n"; |
40da2db3 | 50 | while(defined($line = <$fh>) and $line !~ m/^__END__/) { |
c7675058 | 51 | if ($line =~ m/^sub\s+([\w:]+)\s*(\([\\\$\@\%\&\*\;]*\))?/) { |
f8881bd9 AD |
52 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); |
53 | $protoype = $2; | |
54 | @lines = ($line); | |
55 | if (index($1,'::') == -1) { # simple sub name | |
56 | $name = "${currpack}::$1"; | |
57 | } else { # sub name with package | |
58 | $name = $1; | |
59 | $name =~ m/^(.*)::/; | |
60 | if (defined(&{"${1}::AUTOLOAD"})) { | |
61 | \&{"${1}::AUTOLOAD"} == \&SelfLoader::AUTOLOAD || | |
62 | die 'SelfLoader Error: attempt to specify Selfloading', | |
63 | " sub $name in non-selfloading module $1"; | |
64 | } else { | |
65 | $self->export($1,'AUTOLOAD'); | |
66 | } | |
67 | } | |
68 | } elsif ($line =~ m/^package\s+([\w:]+)/) { # A package declared | |
69 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); | |
70 | $self->_package_defined($line); | |
71 | $name = ''; | |
72 | @lines = (); | |
73 | $currpack = $1; | |
74 | $Cache{"${currpack}::<DATA"} = 1; # indicate package is cached | |
75 | if (defined(&{"${1}::AUTOLOAD"})) { | |
76 | \&{"${1}::AUTOLOAD"} == \&SelfLoader::AUTOLOAD || | |
77 | die 'SelfLoader Error: attempt to specify Selfloading', | |
78 | " package $currpack which already has AUTOLOAD"; | |
79 | } else { | |
80 | $self->export($currpack,'AUTOLOAD'); | |
81 | } | |
82 | } else { | |
83 | push(@lines,$line); | |
84 | } | |
85 | } | |
86 | close($fh) unless defined($line) && $line =~ /^__END__\s*DATA/; # __END__ | |
87 | push(@stubs, $self->_add_to_cache($name, $currpack, \@lines, $protoype)); | |
88 | eval join('', @stubs) if @stubs; | |
89 | } | |
90 | ||
91 | ||
92 | sub _add_to_cache { | |
93 | my($self,$fullname,$pack,$lines, $protoype) = @_; | |
94 | return () unless $fullname; | |
95 | carp("Redefining sub $fullname") if exists $Cache{$fullname}; | |
96 | $Cache{$fullname} = join('', "package $pack; ",@$lines); | |
97 | print STDERR "SelfLoader cached $fullname: $Cache{$fullname}" if $DEBUG; | |
98 | # return stub to be eval'd | |
99 | defined($protoype) ? "sub $fullname $protoype;" : "sub $fullname;" | |
100 | } | |
101 | ||
102 | sub _package_defined {} | |
103 | ||
104 | 1; | |
105 | __END__ | |
cb1a09d0 | 106 | |
f8881bd9 AD |
107 | =head1 NAME |
108 | ||
109 | SelfLoader - load functions only on demand | |
110 | ||
111 | =head1 SYNOPSIS | |
112 | ||
113 | package FOOBAR; | |
114 | use SelfLoader; | |
115 | ||
116 | ... (initializing code) | |
117 | ||
118 | __DATA__ | |
119 | sub {.... | |
120 | ||
121 | ||
122 | =head1 DESCRIPTION | |
123 | ||
124 | This module tells its users that functions in the FOOBAR package are to be | |
463e8aa9 | 125 | autoloaded from after the C<__DATA__> token. See also |
126 | L<perlsub/"Autoloading">. | |
f8881bd9 AD |
127 | |
128 | =head2 The __DATA__ token | |
129 | ||
463e8aa9 | 130 | The C<__DATA__> token tells the perl compiler that the perl code |
131 | for compilation is finished. Everything after the C<__DATA__> token | |
f8881bd9 | 132 | is available for reading via the filehandle FOOBAR::DATA, |
463e8aa9 | 133 | where FOOBAR is the name of the current package when the C<__DATA__> |
134 | token is reached. This works just the same as C<__END__> does in | |
135 | package 'main', but for other modules data after C<__END__> is not | |
f610777f | 136 | automatically retrievable, whereas data after C<__DATA__> is. |
463e8aa9 | 137 | The C<__DATA__> token is not recognized in versions of perl prior to |
f8881bd9 AD |
138 | 5.001m. |
139 | ||
463e8aa9 | 140 | Note that it is possible to have C<__DATA__> tokens in the same package |
141 | in multiple files, and that the last C<__DATA__> token in a given | |
f8881bd9 | 142 | package that is encountered by the compiler is the one accessible |
463e8aa9 | 143 | by the filehandle. This also applies to C<__END__> and main, i.e. if |
144 | the 'main' program has an C<__END__>, but a module 'require'd (_not_ 'use'd) | |
145 | by that program has a 'package main;' declaration followed by an 'C<__DATA__>', | |
146 | then the C<DATA> filehandle is set to access the data after the C<__DATA__> | |
147 | in the module, _not_ the data after the C<__END__> token in the 'main' | |
f8881bd9 AD |
148 | program, since the compiler encounters the 'require'd file later. |
149 | ||
150 | =head2 SelfLoader autoloading | |
151 | ||
463e8aa9 | 152 | The B<SelfLoader> works by the user placing the C<__DATA__> |
153 | token I<after> perl code which needs to be compiled and | |
154 | run at 'require' time, but I<before> subroutine declarations | |
f8881bd9 AD |
155 | that can be loaded in later - usually because they may never |
156 | be called. | |
157 | ||
463e8aa9 | 158 | The B<SelfLoader> will read from the FOOBAR::DATA filehandle to |
159 | load in the data after C<__DATA__>, and load in any subroutine | |
f8881bd9 | 160 | when it is called. The costs are the one-time parsing of the |
463e8aa9 | 161 | data after C<__DATA__>, and a load delay for the _first_ |
f8881bd9 AD |
162 | call of any autoloaded function. The benefits (hopefully) |
163 | are a speeded up compilation phase, with no need to load | |
164 | functions which are never used. | |
165 | ||
463e8aa9 | 166 | The B<SelfLoader> will stop reading from C<__DATA__> if |
167 | it encounters the C<__END__> token - just as you would expect. | |
168 | If the C<__END__> token is present, and is followed by the | |
169 | token DATA, then the B<SelfLoader> leaves the FOOBAR::DATA | |
f8881bd9 AD |
170 | filehandle open on the line after that token. |
171 | ||
463e8aa9 | 172 | The B<SelfLoader> exports the C<AUTOLOAD> subroutine to the |
173 | package using the B<SelfLoader>, and this loads the called | |
f8881bd9 AD |
174 | subroutine when it is first called. |
175 | ||
176 | There is no advantage to putting subroutines which will _always_ | |
463e8aa9 | 177 | be called after the C<__DATA__> token. |
f8881bd9 AD |
178 | |
179 | =head2 Autoloading and package lexicals | |
180 | ||
181 | A 'my $pack_lexical' statement makes the variable $pack_lexical | |
463e8aa9 | 182 | local _only_ to the file up to the C<__DATA__> token. Subroutines |
f8881bd9 AD |
183 | declared elsewhere _cannot_ see these types of variables, |
184 | just as if you declared subroutines in the package but in another | |
185 | file, they cannot see these variables. | |
186 | ||
187 | So specifically, autoloaded functions cannot see package | |
463e8aa9 | 188 | lexicals (this applies to both the B<SelfLoader> and the Autoloader). |
189 | The C<vars> pragma provides an alternative to defining package-level | |
190 | globals that will be visible to autoloaded routines. See the documentation | |
191 | on B<vars> in the pragma section of L<perlmod>. | |
f8881bd9 AD |
192 | |
193 | =head2 SelfLoader and AutoLoader | |
194 | ||
463e8aa9 | 195 | The B<SelfLoader> can replace the AutoLoader - just change 'use AutoLoader' |
196 | to 'use SelfLoader' (though note that the B<SelfLoader> exports | |
f8881bd9 AD |
197 | the AUTOLOAD function - but if you have your own AUTOLOAD and |
198 | are using the AutoLoader too, you probably know what you're doing), | |
463e8aa9 | 199 | and the C<__END__> token to C<__DATA__>. You will need perl version 5.001m |
f8881bd9 AD |
200 | or later to use this (version 5.001 with all patches up to patch m). |
201 | ||
463e8aa9 | 202 | There is no need to inherit from the B<SelfLoader>. |
f8881bd9 | 203 | |
463e8aa9 | 204 | The B<SelfLoader> works similarly to the AutoLoader, but picks up the |
205 | subs from after the C<__DATA__> instead of in the 'lib/auto' directory. | |
f610777f | 206 | There is a maintenance gain in not needing to run AutoSplit on the module |
f8881bd9 AD |
207 | at installation, and a runtime gain in not needing to keep opening and |
208 | closing files to load subs. There is a runtime loss in needing | |
463e8aa9 | 209 | to parse the code after the C<__DATA__>. Details of the B<AutoLoader> and |
210 | another view of these distinctions can be found in that module's | |
211 | documentation. | |
f8881bd9 AD |
212 | |
213 | =head2 __DATA__, __END__, and the FOOBAR::DATA filehandle. | |
214 | ||
215 | This section is only relevant if you want to use | |
463e8aa9 | 216 | the C<FOOBAR::DATA> together with the B<SelfLoader>. |
217 | ||
218 | Data after the C<__DATA__> token in a module is read using the | |
219 | FOOBAR::DATA filehandle. C<__END__> can still be used to denote the end | |
220 | of the C<__DATA__> section if followed by the token DATA - this is supported | |
221 | by the B<SelfLoader>. The C<FOOBAR::DATA> filehandle is left open if an | |
222 | C<__END__> followed by a DATA is found, with the filehandle positioned at | |
223 | the start of the line after the C<__END__> token. If no C<__END__> token is | |
224 | present, or an C<__END__> token with no DATA token on the same line, then | |
225 | the filehandle is closed. | |
226 | ||
227 | The B<SelfLoader> reads from wherever the current | |
228 | position of the C<FOOBAR::DATA> filehandle is, until the | |
229 | EOF or C<__END__>. This means that if you want to use | |
f8881bd9 AD |
230 | that filehandle (and ONLY if you want to), you should either |
231 | ||
232 | 1. Put all your subroutine declarations immediately after | |
463e8aa9 | 233 | the C<__DATA__> token and put your own data after those |
234 | declarations, using the C<__END__> token to mark the end | |
235 | of subroutine declarations. You must also ensure that the B<SelfLoader> | |
1fef88e7 | 236 | reads first by calling 'SelfLoader-E<gt>load_stubs();', or by using a |
f8881bd9 AD |
237 | function which is selfloaded; |
238 | ||
239 | or | |
240 | ||
463e8aa9 | 241 | 2. You should read the C<FOOBAR::DATA> filehandle first, leaving |
f8881bd9 AD |
242 | the handle open and positioned at the first line of subroutine |
243 | declarations. | |
244 | ||
245 | You could conceivably do both. | |
246 | ||
247 | =head2 Classes and inherited methods. | |
248 | ||
249 | For modules which are not classes, this section is not relevant. | |
250 | This section is only relevant if you have methods which could | |
251 | be inherited. | |
252 | ||
253 | A subroutine stub (or forward declaration) looks like | |
254 | ||
255 | sub stub; | |
256 | ||
257 | i.e. it is a subroutine declaration without the body of the | |
258 | subroutine. For modules which are not classes, there is no real | |
259 | need for stubs as far as autoloading is concerned. | |
260 | ||
261 | For modules which ARE classes, and need to handle inherited methods, | |
262 | stubs are needed to ensure that the method inheritance mechanism works | |
263 | properly. You can load the stubs into the module at 'require' time, by | |
1fef88e7 | 264 | adding the statement 'SelfLoader-E<gt>load_stubs();' to the module to do |
f8881bd9 AD |
265 | this. |
266 | ||
463e8aa9 | 267 | The alternative is to put the stubs in before the C<__DATA__> token BEFORE |
268 | releasing the module, and for this purpose the C<Devel::SelfStubber> | |
f8881bd9 AD |
269 | module is available. However this does require the extra step of ensuring |
270 | that the stubs are in the module. If this is done I strongly recommend | |
271 | that this is done BEFORE releasing the module - it should NOT be done | |
272 | at install time in general. | |
273 | ||
274 | =head1 Multiple packages and fully qualified subroutine names | |
275 | ||
276 | Subroutines in multiple packages within the same file are supported - but you | |
463e8aa9 | 277 | should note that this requires exporting the C<SelfLoader::AUTOLOAD> to |
f8881bd9 | 278 | every package which requires it. This is done automatically by the |
463e8aa9 | 279 | B<SelfLoader> when it first loads the subs into the cache, but you should |
280 | really specify it in the initialization before the C<__DATA__> by putting | |
f8881bd9 AD |
281 | a 'use SelfLoader' statement in each package. |
282 | ||
283 | Fully qualified subroutine names are also supported. For example, | |
284 | ||
285 | __DATA__ | |
286 | sub foo::bar {23} | |
287 | package baz; | |
288 | sub dob {32} | |
289 | ||
463e8aa9 | 290 | will all be loaded correctly by the B<SelfLoader>, and the B<SelfLoader> |
f8881bd9 | 291 | will ensure that the packages 'foo' and 'baz' correctly have the |
463e8aa9 | 292 | B<SelfLoader> C<AUTOLOAD> method when the data after C<__DATA__> is first |
293 | parsed. | |
f8881bd9 AD |
294 | |
295 | =cut |