| 1 | package SelfLoader; |
| 2 | use Carp; |
| 3 | require Exporter; |
| 4 | @ISA = qw(Exporter); |
| 5 | @EXPORT = qw(AUTOLOAD); |
| 6 | $VERSION = "1.08"; |
| 7 | sub Version {$VERSION} |
| 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; |
| 14 | my $SL_code = $Cache{$AUTOLOAD}; |
| 15 | unless ($SL_code) { |
| 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"}; |
| 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; |
| 24 | } |
| 25 | print STDERR "SelfLoader::AUTOLOAD eval: $SL_code\n" if $DEBUG; |
| 26 | eval $SL_code; |
| 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 | |
| 49 | local($/) = "\n"; |
| 50 | while(defined($line = <$fh>) and $line !~ m/^__END__/) { |
| 51 | if ($line =~ m/^sub\s+([\w:]+)\s*(\([\\\$\@\%\&\*\;]*\))?/) { |
| 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__ |
| 106 | |
| 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 |
| 125 | autoloaded from after the C<__DATA__> token. See also |
| 126 | L<perlsub/"Autoloading">. |
| 127 | |
| 128 | =head2 The __DATA__ token |
| 129 | |
| 130 | The C<__DATA__> token tells the perl compiler that the perl code |
| 131 | for compilation is finished. Everything after the C<__DATA__> token |
| 132 | is available for reading via the filehandle FOOBAR::DATA, |
| 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 |
| 136 | automatically retrievable, whereas data after C<__DATA__> is. |
| 137 | The C<__DATA__> token is not recognized in versions of perl prior to |
| 138 | 5.001m. |
| 139 | |
| 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 |
| 142 | package that is encountered by the compiler is the one accessible |
| 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' |
| 148 | program, since the compiler encounters the 'require'd file later. |
| 149 | |
| 150 | =head2 SelfLoader autoloading |
| 151 | |
| 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 |
| 155 | that can be loaded in later - usually because they may never |
| 156 | be called. |
| 157 | |
| 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 |
| 160 | when it is called. The costs are the one-time parsing of the |
| 161 | data after C<__DATA__>, and a load delay for the _first_ |
| 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 | |
| 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 |
| 170 | filehandle open on the line after that token. |
| 171 | |
| 172 | The B<SelfLoader> exports the C<AUTOLOAD> subroutine to the |
| 173 | package using the B<SelfLoader>, and this loads the called |
| 174 | subroutine when it is first called. |
| 175 | |
| 176 | There is no advantage to putting subroutines which will _always_ |
| 177 | be called after the C<__DATA__> token. |
| 178 | |
| 179 | =head2 Autoloading and package lexicals |
| 180 | |
| 181 | A 'my $pack_lexical' statement makes the variable $pack_lexical |
| 182 | local _only_ to the file up to the C<__DATA__> token. Subroutines |
| 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 |
| 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>. |
| 192 | |
| 193 | =head2 SelfLoader and AutoLoader |
| 194 | |
| 195 | The B<SelfLoader> can replace the AutoLoader - just change 'use AutoLoader' |
| 196 | to 'use SelfLoader' (though note that the B<SelfLoader> exports |
| 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), |
| 199 | and the C<__END__> token to C<__DATA__>. You will need perl version 5.001m |
| 200 | or later to use this (version 5.001 with all patches up to patch m). |
| 201 | |
| 202 | There is no need to inherit from the B<SelfLoader>. |
| 203 | |
| 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. |
| 206 | There is a maintenance gain in not needing to run AutoSplit on the module |
| 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 |
| 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. |
| 212 | |
| 213 | =head2 __DATA__, __END__, and the FOOBAR::DATA filehandle. |
| 214 | |
| 215 | This section is only relevant if you want to use |
| 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 |
| 230 | that filehandle (and ONLY if you want to), you should either |
| 231 | |
| 232 | 1. Put all your subroutine declarations immediately after |
| 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> |
| 236 | reads first by calling 'SelfLoader-E<gt>load_stubs();', or by using a |
| 237 | function which is selfloaded; |
| 238 | |
| 239 | or |
| 240 | |
| 241 | 2. You should read the C<FOOBAR::DATA> filehandle first, leaving |
| 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 |
| 264 | adding the statement 'SelfLoader-E<gt>load_stubs();' to the module to do |
| 265 | this. |
| 266 | |
| 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> |
| 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 |
| 277 | should note that this requires exporting the C<SelfLoader::AUTOLOAD> to |
| 278 | every package which requires it. This is done automatically by the |
| 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 |
| 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 | |
| 290 | will all be loaded correctly by the B<SelfLoader>, and the B<SelfLoader> |
| 291 | will ensure that the packages 'foo' and 'baz' correctly have the |
| 292 | B<SelfLoader> C<AUTOLOAD> method when the data after C<__DATA__> is first |
| 293 | parsed. |
| 294 | |
| 295 | =cut |