[perl5.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_01';
}

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 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;
	}
    }

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