lib/SelfLoader.pm

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