[p5sagit/p5-mst-13.2.git] / lib / AutoLoader.pm

package AutoLoader;

use strict;
use 5.006_001;

our($VERSION, $AUTOLOAD);

my $is_dosish;
my $is_epoc;
my $is_vms;
my $is_macos;

BEGIN {
    $is_dosish = $^O eq 'dos' || $^O eq 'os2' || $^O eq 'MSWin32' || $^O eq 'NetWare';
    $is_epoc = $^O eq 'epoc';
    $is_vms = $^O eq 'VMS';
    $is_macos = $^O eq 'MacOS';
    $VERSION = '5.64';
}

AUTOLOAD {
    my $sub = $AUTOLOAD;
    my $filename = AutoLoader::find_filename( $sub );

    my $save = $@;
    local $!; # Do not munge the value. 
    eval { local $SIG{__DIE__}; require $filename };
    if ($@) {
	if (substr($sub,-9) eq '::DESTROY') {
	    no strict 'refs';
	    *$sub = sub {};
	    $@ = undef;
	} elsif ($@ =~ /^Can't locate/) {
	    # The load might just have failed because the filename was too
	    # long for some old SVR3 systems which treat long names as errors.
	    # If we can successfully truncate a long name then it's worth a go.
	    # There is a slight risk that we could pick up the wrong file here
	    # but autosplit should have warned about that when splitting.
	    if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
		eval { local $SIG{__DIE__}; require $filename };
	    }
	}
	if ($@){
	    $@ =~ s/ at .*\n//;
	    my $error = $@;
	    require Carp;
	    Carp::croak($error);
	}
    }
    $@ = $save;
    goto &$sub;
}

sub can {
    my ($self, $method) = @_;

    my $parent          = $self->SUPER::can( $method );
    return $parent if $parent;

    my $package         = ref( $self ) || $self;
    my $filename        = AutoLoader::find_filename( $package . '::' . $method );
    local $@;
    return unless eval { require $filename };

    no strict 'refs';
    return \&{ $package . '::' . $method };
}

sub find_filename {
    my $sub = shift;
    my $filename;
    # Braces used to preserve $1 et al.
    {
	# Try to find the autoloaded file from the package-qualified
	# name of the sub. e.g., if the sub needed is
	# Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
	# something like '/usr/lib/perl5/Getopt/Long.pm', and the
	# autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
	#
	# However, if @INC is a relative path, this might not work.  If,
	# for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
	# 'lib/Getopt/Long.pm', and we want to require
	# 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
	# In this case, we simple prepend the 'auto/' and let the
	# C<require> take care of the searching for us.

	my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
	$pkg =~ s#::#/#g;
	if (defined($filename = $INC{"$pkg.pm"})) {
	    if ($is_macos) {
		$pkg =~ tr#/#:#;
		$filename = undef
		  unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
	    } else {
		$filename = undef
		  unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
	    }

	    # if the file exists, then make sure that it is a
	    # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
	    # or './lib/auto/foo/bar.al'.  This avoids C<require> searching
	    # (and failing) to find the 'lib/auto/foo/bar.al' because it
	    # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').

	    if (defined $filename and -r $filename) {
		unless ($filename =~ m|^/|s) {
		    if ($is_dosish) {
			unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
			    if ($^O ne 'NetWare') {
				$filename = "./$filename";
			    } else {
				$filename = "$filename";
			    }
			}
		    }
		    elsif ($is_epoc) {
			unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
			     $filename = "./$filename";
			}
		    }
		    elsif ($is_vms) {
			# XXX todo by VMSmiths
			$filename = "./$filename";
		    }
		    elsif (!$is_macos) {
			$filename = "./$filename";
		    }
		}
	    }
	    else {
		$filename = undef;
	    }
	}
	unless (defined $filename) {
	    # let C<require> do the searching
	    $filename = "auto/$sub.al";
	    $filename =~ s#::#/#g;
	}
    }
    return $filename;
}

sub import {
    my $pkg = shift;
    my $callpkg = caller;

    #
    # Export symbols, but not by accident of inheritance.
    #

    if ($pkg eq 'AutoLoader') {
	if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) {
	    no strict 'refs';
	    *{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD;
	    *{ $callpkg . '::can'      } = \&can;
	}
    }

    #
    # Try to find the autosplit index file.  Eg., if the call package
    # is POSIX, then $INC{POSIX.pm} is something like
    # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
    # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
    #
    # However, if @INC is a relative path, this might not work.  If,
    # for example, @INC = ('lib'), then
    # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
    # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
    #

    (my $calldir = $callpkg) =~ s#::#/#g;
    my $path = $INC{$calldir . '.pm'};
    if (defined($path)) {
	# Try absolute path name.
	if ($is_macos) {
	    (my $malldir = $calldir) =~ tr#/#:#;
	    $path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s;
	} else {
	    $path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#;
	}

	eval { require $path; };
	# If that failed, try relative path with normal @INC searching.
	if ($@) {
	    $path ="auto/$calldir/autosplit.ix";
	    eval { require $path; };
	}
	if ($@) {
	    my $error = $@;
	    require Carp;
	    Carp::carp($error);
	}
    } 
}

sub unimport {
    my $callpkg = caller;

    no strict 'refs';

    for my $exported (qw( AUTOLOAD can )) {
	my $symname = $callpkg . '::' . $exported;
	undef *{ $symname } if \&{ $symname } == \&{ $exported };
	*{ $symname } = \&{ $symname };
    }
}

1;

__END__

=head1 NAME

AutoLoader - load subroutines only on demand

=head1 SYNOPSIS

    package Foo;
    use AutoLoader 'AUTOLOAD';   # import the default AUTOLOAD subroutine

    package Bar;
    use AutoLoader;              # don't import AUTOLOAD, define our own
    sub AUTOLOAD {
        ...
        $AutoLoader::AUTOLOAD = "...";
        goto &AutoLoader::AUTOLOAD;
    }

=head1 DESCRIPTION

The B<AutoLoader> module works with the B<AutoSplit> module and the
C<__END__> token to defer the loading of some subroutines until they are
used rather than loading them all at once.

To use B<AutoLoader>, the author of a module has to place the
definitions of subroutines to be autoloaded after an C<__END__> token.
(See L<perldata>.)  The B<AutoSplit> module can then be run manually to
extract the definitions into individual files F<auto/funcname.al>.

B<AutoLoader> implements an AUTOLOAD subroutine.  When an undefined
subroutine in is called in a client module of B<AutoLoader>,
B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
file with a name related to the location of the file from which the
client module was read.  As an example, if F<POSIX.pm> is located in
F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
the C<.al> file has the same name as the subroutine, sans package.  If
such a file exists, AUTOLOAD will read and evaluate it,
thus (presumably) defining the needed subroutine.  AUTOLOAD will then
C<goto> the newly defined subroutine.

Once this process completes for a given function, it is defined, so
future calls to the subroutine will bypass the AUTOLOAD mechanism.

=head2 Subroutine Stubs

In order for object method lookup and/or prototype checking to operate
correctly even when methods have not yet been defined it is necessary to
"forward declare" each subroutine (as in C<sub NAME;>).  See
L<perlsub/"SYNOPSIS">.  Such forward declaration creates "subroutine
stubs", which are place holders with no code.

The AutoSplit and B<AutoLoader> modules automate the creation of forward
declarations.  The AutoSplit module creates an 'index' file containing
forward declarations of all the AutoSplit subroutines.  When the
AutoLoader module is 'use'd it loads these declarations into its callers
package.

Because of this mechanism it is important that B<AutoLoader> is always
C<use>d and not C<require>d.

=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine

In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
explicitly import it:

    use AutoLoader 'AUTOLOAD';

=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine

Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
They typically need to check for some special cases (such as constants)
and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.

Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
Instead, they should define their own AUTOLOAD subroutines along these
lines:

    use AutoLoader;
    use Carp;

    sub AUTOLOAD {
        my $sub = $AUTOLOAD;
        (my $constname = $sub) =~ s/.*:://;
        my $val = constant($constname, @_ ? $_[0] : 0);
        if ($! != 0) {
            if ($! =~ /Invalid/ || $!{EINVAL}) {
                $AutoLoader::AUTOLOAD = $sub;
                goto &AutoLoader::AUTOLOAD;
            }
            else {
                croak "Your vendor has not defined constant $constname";
            }
        }
        *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
        goto &$sub;
    }

If any module's own AUTOLOAD subroutine has no need to fallback to the
AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
subroutines), then that module should not use B<AutoLoader> at all.

=head2 Package Lexicals

Package lexicals declared with C<my> in the main block of a package
using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
the fact that the given scope ends at the C<__END__> marker.  A module
using such variables as package globals will not work properly under the
B<AutoLoader>.

The C<vars> pragma (see L<perlmod/"vars">) may be used in such
situations as an alternative to explicitly qualifying all globals with
the package namespace.  Variables pre-declared with this pragma will be
visible to any autoloaded routines (but will not be invisible outside
the package, unfortunately).

=head2 Not Using AutoLoader

You can stop using AutoLoader by simply

	no AutoLoader;

=head2 B<AutoLoader> vs. B<SelfLoader>

The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
loading of subroutines.

B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
While this avoids the use of a hierarchy of disk files and the
associated open/close for each routine loaded, B<SelfLoader> suffers a
startup speed disadvantage in the one-time parsing of the lines after
C<__DATA__>, after which routines are cached.  B<SelfLoader> can also
handle multiple packages in a file.

B<AutoLoader> only reads code as it is requested, and in many cases
should be faster, but requires a mechanism like B<AutoSplit> be used to
create the individual files.  L<ExtUtils::MakeMaker> will invoke
B<AutoSplit> automatically if B<AutoLoader> is used in a module source
file.

=head1 CAVEATS

AutoLoaders prior to Perl 5.002 had a slightly different interface.  Any
old modules which use B<AutoLoader> should be changed to the new calling
style.  Typically this just means changing a require to a use, adding
the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
from C<@ISA>.

On systems with restrictions on file name length, the file corresponding
to a subroutine may have a shorter name that the routine itself.  This
can lead to conflicting file names.  The I<AutoSplit> package warns of
these potential conflicts when used to split a module.

AutoLoader may fail to find the autosplit files (or even find the wrong
ones) in cases where C<@INC> contains relative paths, B<and> the program
does C<chdir>.

=head1 SEE ALSO

L<SelfLoader> - an autoloader that doesn't use external files.

=head1 AUTHOR

C<AutoLoader> is maintained by the perl5-porters. Please direct
any questions to the canonical mailing list. Anything that
is applicable to the CPAN release can be sent to its maintainer,
though.

Author and Maintainer: The Perl5-Porters <perl5-porters@perl.org>

Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>

=head1 COPYRIGHT AND LICENSE

This package has been part of the perl core since the first release
of perl5. It has been released separately to CPAN so older installations
can benefit from bug fixes.

This package has the same copyright and license as the perl core:

             Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999,
        2000, 2001, 2002, 2003, 2004, 2005, 2006 by Larry Wall and others
    
			    All rights reserved.
    
    This program is free software; you can redistribute it and/or modify
    it under the terms of either:
    
	a) the GNU General Public License as published by the Free
	Software Foundation; either version 1, or (at your option) any
	later version, or
    
	b) the "Artistic License" which comes with this Kit.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either
    the GNU General Public License or the Artistic License for more details.
    
    You should have received a copy of the Artistic License with this
    Kit, in the file named "Artistic".  If not, I'll be glad to provide one.
    
    You should also have received a copy of the GNU General Public License
    along with this program in the file named "Copying". If not, write to the 
    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
    02111-1307, USA or visit their web page on the internet at
    http://www.gnu.org/copyleft/gpl.html.
    
    For those of you that choose to use the GNU General Public License,
    my interpretation of the GNU General Public License is that no Perl
    script falls under the terms of the GPL unless you explicitly put
    said script under the terms of the GPL yourself.  Furthermore, any
    object code linked with perl does not automatically fall under the
    terms of the GPL, provided such object code only adds definitions
    of subroutines and variables, and does not otherwise impair the
    resulting interpreter from executing any standard Perl script.  I
    consider linking in C subroutines in this manner to be the moral
    equivalent of defining subroutines in the Perl language itself.  You
    may sell such an object file as proprietary provided that you provide
    or offer to provide the Perl source, as specified by the GNU General
    Public License.  (This is merely an alternate way of specifying input
    to the program.)  You may also sell a binary produced by the dumping of
    a running Perl script that belongs to you, provided that you provide or
    offer to provide the Perl source as specified by the GPL.  (The
    fact that a Perl interpreter and your code are in the same binary file
    is, in this case, a form of mere aggregation.)  This is my interpretation
    of the GPL.  If you still have concerns or difficulties understanding
    my intent, feel free to contact me.  Of course, the Artistic License
    spells all this out for your protection, so you may prefer to use that.

=cut
Commit	Line	Data
8990e307	1	package AutoLoader;
21c92a1d	2
04c1a02b	3	use strict;
3b825e41	4	use 5.006_001;
04c1a02b	5
04c1a02b	6	our($VERSION, $AUTOLOAD);
f06db76b	7
adaafad2	8	my $is_dosish;
ed79a026	9	my $is_epoc;
adaafad2	10	my $is_vms;
084592ab	11	my $is_macos;
adaafad2	12
1be0b951	13	BEGIN {
2986a63f	14	$is_dosish = $^O eq 'dos' \|\| $^O eq 'os2' \|\| $^O eq 'MSWin32' \|\| $^O eq 'NetWare';
ed79a026	15	$is_epoc = $^O eq 'epoc';
adaafad2	16	$is_vms = $^O eq 'VMS';
084592ab	17	$is_macos = $^O eq 'MacOS';
7a752413	18	$VERSION = '5.64';
1be0b951	19	}
f06db76b	20
8990e307	21	AUTOLOAD {
7d4fbd98	22	my $sub = $AUTOLOAD;
00bb01c7	23	my $filename = AutoLoader::find_filename( $sub );
	24
	25	my $save = $@;
	26	local $!; # Do not munge the value.
	27	eval { local $SIG{__DIE__}; require $filename };
	28	if ($@) {
	29	if (substr($sub,-9) eq '::DESTROY') {
	30	no strict 'refs';
	31	*$sub = sub {};
	32	$@ = undef;
	33	} elsif ($@ =~ /^Can't locate/) {
	34	# The load might just have failed because the filename was too
	35	# long for some old SVR3 systems which treat long names as errors.
	36	# If we can successfully truncate a long name then it's worth a go.
	37	# There is a slight risk that we could pick up the wrong file here
	38	# but autosplit should have warned about that when splitting.
	39	if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
	40	eval { local $SIG{__DIE__}; require $filename };
	41	}
	42	}
	43	if ($@){
	44	$@ =~ s/ at .*\n//;
	45	my $error = $@;
	46	require Carp;
	47	Carp::croak($error);
	48	}
	49	}
	50	$@ = $save;
	51	goto &$sub;
	52	}
	53
	54	sub can {
	55	my ($self, $method) = @_;
	56
	57	my $parent = $self->SUPER::can( $method );
	58	return $parent if $parent;
	59
	60	my $package = ref( $self ) \|\| $self;
	61	my $filename = AutoLoader::find_filename( $package . '::' . $method );
	62	local $@;
	63	return unless eval { require $filename };
	64
	65	no strict 'refs';
	66	return \&{ $package . '::' . $method };
	67	}
	68
	69	sub find_filename {
	70	my $sub = shift;
7d4fbd98	71	my $filename;
5a556d17	72	# Braces used to preserve $1 et al.
5a556d17	73	{
adaafad2	74	# Try to find the autoloaded file from the package-qualified
	75	# name of the sub. e.g., if the sub needed is
	76	# Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
	77	# something like '/usr/lib/perl5/Getopt/Long.pm', and the
	78	# autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
	79	#
	80	# However, if @INC is a relative path, this might not work. If,
	81	# for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
	82	# 'lib/Getopt/Long.pm', and we want to require
	83	# 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
	84	# In this case, we simple prepend the 'auto/' and let the
	85	# C<require> take care of the searching for us.
	86
7d4fbd98	87	my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
adaafad2	88	$pkg =~ s#::#/#g;
7d4fbd98	89	if (defined($filename = $INC{"$pkg.pm"})) {
084592ab	90	if ($is_macos) {
084592ab	91	$pkg =~ tr#/#:#;
017a05de	92	$filename = undef
017a05de	93	unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
084592ab	94	} else {
017a05de	95	$filename = undef
017a05de	96	unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
084592ab	97	}
adaafad2	98
	99	# if the file exists, then make sure that it is a
	100	# a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
	101	# or './lib/auto/foo/bar.al'. This avoids C<require> searching
	102	# (and failing) to find the 'lib/auto/foo/bar.al' because it
	103	# looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
	104
3256a4f8	105	if (defined $filename and -r $filename) {
14a089c5	106	unless ($filename =~ m\|^/\|s) {
adaafad2	107	if ($is_dosish) {
14a089c5	108	unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
00bb01c7	109	if ($^O ne 'NetWare') {
	110	$filename = "./$filename";
	111	} else {
	112	$filename = "$filename";
	113	}
adaafad2	114	}
adaafad2	115	}
ed79a026	116	elsif ($is_epoc) {
	117	unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
	118	$filename = "./$filename";
	119	}
4d6b4052	120	}
4d6b4052	121	elsif ($is_vms) {
7d4fbd98	122	# XXX todo by VMSmiths
7d4fbd98	123	$filename = "./$filename";
adaafad2	124	}
084592ab	125	elsif (!$is_macos) {
7d4fbd98	126	$filename = "./$filename";
adaafad2	127	}
	128	}
	129	}
	130	else {
7d4fbd98	131	$filename = undef;
adaafad2	132	}
adaafad2	133	}
7d4fbd98	134	unless (defined $filename) {
adaafad2	135	# let C<require> do the searching
7d4fbd98	136	$filename = "auto/$sub.al";
7d4fbd98	137	$filename =~ s#::#/#g;
adaafad2	138	}
5a556d17	139	}
00bb01c7	140	return $filename;
8990e307	141	}
1be0b951	142
c2960299	143	sub import {
1be0b951	144	my $pkg = shift;
	145	my $callpkg = caller;
	146
	147	#
	148	# Export symbols, but not by accident of inheritance.
	149	#
	150
e3d0cac0	151	if ($pkg eq 'AutoLoader') {
00bb01c7	152	if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) {
	153	no strict 'refs';
	154	*{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD;
	155	*{ $callpkg . '::can' } = \&can;
	156	}
e3d0cac0	157	}
1be0b951	158
1be0b951	159	#
c2960299	160	# Try to find the autosplit index file. Eg., if the call package
	161	# is POSIX, then $INC{POSIX.pm} is something like
	162	# '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
	163	# '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
	164	#
	165	# However, if @INC is a relative path, this might not work. If,
	166	# for example, @INC = ('lib'), then
	167	# $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
	168	# 'auto/POSIX/autosplit.ix' (without the leading 'lib').
	169	#
1be0b951	170
1c1c7f20	171	(my $calldir = $callpkg) =~ s#::#/#g;
1be0b951	172	my $path = $INC{$calldir . '.pm'};
1be0b951	173	if (defined($path)) {
c2960299	174	# Try absolute path name.
4d6b4052	175	if ($is_macos) {
	176	(my $malldir = $calldir) =~ tr#/#:#;
	177	$path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s;
	178	} else {
	179	$path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#;
	180	}
	181
c2960299	182	eval { require $path; };
	183	# If that failed, try relative path with normal @INC searching.
	184	if ($@) {
1be0b951	185	$path ="auto/$calldir/autosplit.ix";
c2960299	186	eval { require $path; };
c2960299	187	}
fb73857a	188	if ($@) {
	189	my $error = $@;
	190	require Carp;
	191	Carp::carp($error);
	192	}
f06db76b	193	}
f06db76b	194	}
8990e307	195
cb0cff20	196	sub unimport {
7412bda7	197	my $callpkg = caller;
	198
	199	no strict 'refs';
00bb01c7	200
	201	for my $exported (qw( AUTOLOAD can )) {
	202	my $symname = $callpkg . '::' . $exported;
	203	undef *{ $symname } if \&{ $symname } == \&{ $exported };
	204	*{ $symname } = \&{ $symname };
	205	}
cb0cff20	206	}
cb0cff20	207
8990e307	208	1;
1be0b951	209
	210	__END__
	211
	212	=head1 NAME
	213
	214	AutoLoader - load subroutines only on demand
	215
	216	=head1 SYNOPSIS
	217
	218	package Foo;
	219	use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine
	220
	221	package Bar;
	222	use AutoLoader; # don't import AUTOLOAD, define our own
	223	sub AUTOLOAD {
	224	...
	225	$AutoLoader::AUTOLOAD = "...";
	226	goto &AutoLoader::AUTOLOAD;
	227	}
	228
	229	=head1 DESCRIPTION
	230
	231	The B<AutoLoader> module works with the B<AutoSplit> module and the
	232	C<__END__> token to defer the loading of some subroutines until they are
	233	used rather than loading them all at once.
	234
	235	To use B<AutoLoader>, the author of a module has to place the
	236	definitions of subroutines to be autoloaded after an C<__END__> token.
	237	(See L<perldata>.) The B<AutoSplit> module can then be run manually to
	238	extract the definitions into individual files F<auto/funcname.al>.
	239
	240	B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined
	241	subroutine in is called in a client module of B<AutoLoader>,
	242	B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
	243	file with a name related to the location of the file from which the
	244	client module was read. As an example, if F<POSIX.pm> is located in
	245	F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
	246	subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
	247	the C<.al> file has the same name as the subroutine, sans package. If
	248	such a file exists, AUTOLOAD will read and evaluate it,
	249	thus (presumably) defining the needed subroutine. AUTOLOAD will then
	250	C<goto> the newly defined subroutine.
	251
f610777f	252	Once this process completes for a given function, it is defined, so
1be0b951	253	future calls to the subroutine will bypass the AUTOLOAD mechanism.
	254
	255	=head2 Subroutine Stubs
	256
	257	In order for object method lookup and/or prototype checking to operate
	258	correctly even when methods have not yet been defined it is necessary to
	259	"forward declare" each subroutine (as in C<sub NAME;>). See
	260	L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine
	261	stubs", which are place holders with no code.
	262
	263	The AutoSplit and B<AutoLoader> modules automate the creation of forward
	264	declarations. The AutoSplit module creates an 'index' file containing
	265	forward declarations of all the AutoSplit subroutines. When the
	266	AutoLoader module is 'use'd it loads these declarations into its callers
	267	package.
	268
	269	Because of this mechanism it is important that B<AutoLoader> is always
	270	C<use>d and not C<require>d.
	271
	272	=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
	273
	274	In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
	275	explicitly import it:
	276
	277	use AutoLoader 'AUTOLOAD';
	278
	279	=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
	280
	281	Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
	282	They typically need to check for some special cases (such as constants)
	283	and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
	284
	285	Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
	286	Instead, they should define their own AUTOLOAD subroutines along these
	287	lines:
	288
	289	use AutoLoader;
fb73857a	290	use Carp;
1be0b951	291
1be0b951	292	sub AUTOLOAD {
7d4fbd98	293	my $sub = $AUTOLOAD;
7d4fbd98	294	(my $constname = $sub) =~ s/.*:://;
1be0b951	295	my $val = constant($constname, @_ ? $_[0] : 0);
1be0b951	296	if ($! != 0) {
265f5c4a	297	if ($! =~ /Invalid/ \|\| $!{EINVAL}) {
7d4fbd98	298	$AutoLoader::AUTOLOAD = $sub;
1be0b951	299	goto &AutoLoader::AUTOLOAD;
	300	}
	301	else {
	302	croak "Your vendor has not defined constant $constname";
	303	}
	304	}
7d4fbd98	305	*$sub = sub { $val }; # same as: eval "sub $sub { $val }";
7d4fbd98	306	goto &$sub;
1be0b951	307	}
	308
	309	If any module's own AUTOLOAD subroutine has no need to fallback to the
	310	AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
	311	subroutines), then that module should not use B<AutoLoader> at all.
	312
	313	=head2 Package Lexicals
	314
	315	Package lexicals declared with C<my> in the main block of a package
	316	using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
	317	the fact that the given scope ends at the C<__END__> marker. A module
	318	using such variables as package globals will not work properly under the
	319	B<AutoLoader>.
	320
	321	The C<vars> pragma (see L<perlmod/"vars">) may be used in such
	322	situations as an alternative to explicitly qualifying all globals with
	323	the package namespace. Variables pre-declared with this pragma will be
	324	visible to any autoloaded routines (but will not be invisible outside
	325	the package, unfortunately).
	326
cb0cff20	327	=head2 Not Using AutoLoader
	328
	329	You can stop using AutoLoader by simply
	330
	331	no AutoLoader;
	332
1be0b951	333	=head2 B<AutoLoader> vs. B<SelfLoader>
	334
	335	The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
	336	loading of subroutines.
	337
	338	B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
	339	While this avoids the use of a hierarchy of disk files and the
	340	associated open/close for each routine loaded, B<SelfLoader> suffers a
	341	startup speed disadvantage in the one-time parsing of the lines after
	342	C<__DATA__>, after which routines are cached. B<SelfLoader> can also
	343	handle multiple packages in a file.
	344
	345	B<AutoLoader> only reads code as it is requested, and in many cases
f610777f	346	should be faster, but requires a mechanism like B<AutoSplit> be used to
1be0b951	347	create the individual files. L<ExtUtils::MakeMaker> will invoke
	348	B<AutoSplit> automatically if B<AutoLoader> is used in a module source
	349	file.
	350
	351	=head1 CAVEATS
	352
	353	AutoLoaders prior to Perl 5.002 had a slightly different interface. Any
	354	old modules which use B<AutoLoader> should be changed to the new calling
	355	style. Typically this just means changing a require to a use, adding
	356	the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
	357	from C<@ISA>.
	358
	359	On systems with restrictions on file name length, the file corresponding
	360	to a subroutine may have a shorter name that the routine itself. This
	361	can lead to conflicting file names. The I<AutoSplit> package warns of
	362	these potential conflicts when used to split a module.
	363
adaafad2	364	AutoLoader may fail to find the autosplit files (or even find the wrong
	365	ones) in cases where C<@INC> contains relative paths, B<and> the program
	366	does C<chdir>.
	367
1be0b951	368	=head1 SEE ALSO
	369
	370	L<SelfLoader> - an autoloader that doesn't use external files.
	371
7a752413	372	=head1 AUTHOR
	373
	374	C<AutoLoader> is maintained by the perl5-porters. Please direct
	375	any questions to the canonical mailing list. Anything that
	376	is applicable to the CPAN release can be sent to its maintainer,
	377	though.
	378
	379	Author and Maintainer: The Perl5-Porters <perl5-porters@perl.org>
	380
	381	Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>
	382
	383	=head1 COPYRIGHT AND LICENSE
	384
	385	This package has been part of the perl core since the first release
	386	of perl5. It has been released separately to CPAN so older installations
	387	can benefit from bug fixes.
	388
	389	This package has the same copyright and license as the perl core:
	390
	391	Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999,
	392	2000, 2001, 2002, 2003, 2004, 2005, 2006 by Larry Wall and others
	393
	394	All rights reserved.
	395
	396	This program is free software; you can redistribute it and/or modify
	397	it under the terms of either:
	398
	399	a) the GNU General Public License as published by the Free
	400	Software Foundation; either version 1, or (at your option) any
	401	later version, or
	402
	403	b) the "Artistic License" which comes with this Kit.
	404
	405	This program is distributed in the hope that it will be useful,
	406	but WITHOUT ANY WARRANTY; without even the implied warranty of
	407	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
	408	the GNU General Public License or the Artistic License for more details.
	409
	410	You should have received a copy of the Artistic License with this
	411	Kit, in the file named "Artistic". If not, I'll be glad to provide one.
	412
	413	You should also have received a copy of the GNU General Public License
	414	along with this program in the file named "Copying". If not, write to the
	415	Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
	416	02111-1307, USA or visit their web page on the internet at
	417	http://www.gnu.org/copyleft/gpl.html.
	418
	419	For those of you that choose to use the GNU General Public License,
	420	my interpretation of the GNU General Public License is that no Perl
	421	script falls under the terms of the GPL unless you explicitly put
	422	said script under the terms of the GPL yourself. Furthermore, any
	423	object code linked with perl does not automatically fall under the
	424	terms of the GPL, provided such object code only adds definitions
	425	of subroutines and variables, and does not otherwise impair the
	426	resulting interpreter from executing any standard Perl script. I
	427	consider linking in C subroutines in this manner to be the moral
	428	equivalent of defining subroutines in the Perl language itself. You
	429	may sell such an object file as proprietary provided that you provide
	430	or offer to provide the Perl source, as specified by the GNU General
	431	Public License. (This is merely an alternate way of specifying input
	432	to the program.) You may also sell a binary produced by the dumping of
	433	a running Perl script that belongs to you, provided that you provide or
	434	offer to provide the Perl source as specified by the GPL. (The
	435	fact that a Perl interpreter and your code are in the same binary file
436	is, in this case, a form of mere aggregation.) This is my interpretation
437	of the GPL. If you still have concerns or difficulties understanding
438	my intent, feel free to contact me. Of course, the Artistic License
439	spells all this out for your protection, so you may prefer to use that.
440
1be0b951	441	=cut