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