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