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

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 =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
	    } else {
		$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 (-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.

=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';
00bb01c7	18	$VERSION = '5.61';
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 NIS	72	# Braces used to preserve $1 et al.
5a556d17 NIS	73	{
adaafad2 GS	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 CN	90	if ($is_macos) {
	91	$pkg =~ tr#/#:#;
	92	$filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
	93	} else {
	94	$filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
	95	}
adaafad2 GS	96
	97	# if the file exists, then make sure that it is a
	98	# a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
	99	# or './lib/auto/foo/bar.al'. This avoids C<require> searching
	100	# (and failing) to find the 'lib/auto/foo/bar.al' because it
	101	# looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
	102
7d4fbd98	103	if (-r $filename) {
14a089c5	104	unless ($filename =~ m\|^/\|s) {
adaafad2	105	if ($is_dosish) {
14a089c5	106	unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
00bb01c7	107	if ($^O ne 'NetWare') {
	108	$filename = "./$filename";
	109	} else {
	110	$filename = "$filename";
	111	}
adaafad2 GS	112	}
adaafad2 GS	113	}
ed79a026 OF	114	elsif ($is_epoc) {
	115	unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
	116	$filename = "./$filename";
	117	}
4d6b4052 JH	118	}
4d6b4052 JH	119	elsif ($is_vms) {
7d4fbd98 GS	120	# XXX todo by VMSmiths
7d4fbd98 GS	121	$filename = "./$filename";
adaafad2	122	}
084592ab	123	elsif (!$is_macos) {
7d4fbd98	124	$filename = "./$filename";
adaafad2 GS	125	}
	126	}
	127	}
	128	else {
7d4fbd98	129	$filename = undef;
adaafad2 GS	130	}
adaafad2 GS	131	}
7d4fbd98	132	unless (defined $filename) {
adaafad2	133	# let C<require> do the searching
7d4fbd98 GS	134	$filename = "auto/$sub.al";
7d4fbd98 GS	135	$filename =~ s#::#/#g;
adaafad2	136	}
5a556d17	137	}
00bb01c7	138	return $filename;
8990e307	139	}
1be0b951	140
c2960299	141	sub import {
1be0b951 CS	142	my $pkg = shift;
	143	my $callpkg = caller;
	144
	145	#
	146	# Export symbols, but not by accident of inheritance.
	147	#
	148
e3d0cac0	149	if ($pkg eq 'AutoLoader') {
00bb01c7	150	if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) {
	151	no strict 'refs';
	152	*{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD;
	153	*{ $callpkg . '::can' } = \&can;
	154	}
e3d0cac0	155	}
1be0b951 CS	156
1be0b951 CS	157	#
c2960299 AD	158	# Try to find the autosplit index file. Eg., if the call package
	159	# is POSIX, then $INC{POSIX.pm} is something like
	160	# '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
	161	# '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
	162	#
	163	# However, if @INC is a relative path, this might not work. If,
	164	# for example, @INC = ('lib'), then
	165	# $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
	166	# 'auto/POSIX/autosplit.ix' (without the leading 'lib').
	167	#
1be0b951	168
1c1c7f20	169	(my $calldir = $callpkg) =~ s#::#/#g;
1be0b951 CS	170	my $path = $INC{$calldir . '.pm'};
1be0b951 CS	171	if (defined($path)) {
c2960299	172	# Try absolute path name.
4d6b4052 JH	173	if ($is_macos) {
	174	(my $malldir = $calldir) =~ tr#/#:#;
	175	$path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s;
	176	} else {
	177	$path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#;
	178	}
	179
c2960299 AD	180	eval { require $path; };
	181	# If that failed, try relative path with normal @INC searching.
	182	if ($@) {
1be0b951	183	$path ="auto/$calldir/autosplit.ix";
c2960299 AD	184	eval { require $path; };
c2960299 AD	185	}
fb73857a	186	if ($@) {
	187	my $error = $@;
	188	require Carp;
	189	Carp::carp($error);
	190	}
f06db76b	191	}
f06db76b	192	}
8990e307	193
cb0cff20	194	sub unimport {
7412bda7	195	my $callpkg = caller;
	196
	197	no strict 'refs';
00bb01c7	198
	199	for my $exported (qw( AUTOLOAD can )) {
	200	my $symname = $callpkg . '::' . $exported;
	201	undef *{ $symname } if \&{ $symname } == \&{ $exported };
	202	*{ $symname } = \&{ $symname };
	203	}
cb0cff20 JH	204	}
cb0cff20 JH	205
8990e307	206	1;
1be0b951 CS	207
	208	__END__
	209
	210	=head1 NAME
	211
	212	AutoLoader - load subroutines only on demand
	213
	214	=head1 SYNOPSIS
	215
	216	package Foo;
	217	use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine
	218
	219	package Bar;
	220	use AutoLoader; # don't import AUTOLOAD, define our own
	221	sub AUTOLOAD {
	222	...
	223	$AutoLoader::AUTOLOAD = "...";
	224	goto &AutoLoader::AUTOLOAD;
	225	}
	226
	227	=head1 DESCRIPTION
	228
	229	The B<AutoLoader> module works with the B<AutoSplit> module and the
	230	C<__END__> token to defer the loading of some subroutines until they are
	231	used rather than loading them all at once.
	232
	233	To use B<AutoLoader>, the author of a module has to place the
	234	definitions of subroutines to be autoloaded after an C<__END__> token.
	235	(See L<perldata>.) The B<AutoSplit> module can then be run manually to
	236	extract the definitions into individual files F<auto/funcname.al>.
	237
	238	B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined
	239	subroutine in is called in a client module of B<AutoLoader>,
	240	B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
	241	file with a name related to the location of the file from which the
	242	client module was read. As an example, if F<POSIX.pm> is located in
	243	F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
	244	subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
	245	the C<.al> file has the same name as the subroutine, sans package. If
	246	such a file exists, AUTOLOAD will read and evaluate it,
	247	thus (presumably) defining the needed subroutine. AUTOLOAD will then
	248	C<goto> the newly defined subroutine.
	249
f610777f	250	Once this process completes for a given function, it is defined, so
1be0b951 CS	251	future calls to the subroutine will bypass the AUTOLOAD mechanism.
	252
	253	=head2 Subroutine Stubs
	254
	255	In order for object method lookup and/or prototype checking to operate
	256	correctly even when methods have not yet been defined it is necessary to
	257	"forward declare" each subroutine (as in C<sub NAME;>). See
	258	L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine
	259	stubs", which are place holders with no code.
	260
	261	The AutoSplit and B<AutoLoader> modules automate the creation of forward
	262	declarations. The AutoSplit module creates an 'index' file containing
	263	forward declarations of all the AutoSplit subroutines. When the
	264	AutoLoader module is 'use'd it loads these declarations into its callers
	265	package.
	266
	267	Because of this mechanism it is important that B<AutoLoader> is always
	268	C<use>d and not C<require>d.
	269
	270	=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
	271
	272	In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
	273	explicitly import it:
	274
	275	use AutoLoader 'AUTOLOAD';
	276
	277	=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
	278
	279	Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
	280	They typically need to check for some special cases (such as constants)
	281	and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
	282
	283	Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
	284	Instead, they should define their own AUTOLOAD subroutines along these
	285	lines:
	286
	287	use AutoLoader;
fb73857a	288	use Carp;
1be0b951 CS	289
1be0b951 CS	290	sub AUTOLOAD {
7d4fbd98 GS	291	my $sub = $AUTOLOAD;
7d4fbd98 GS	292	(my $constname = $sub) =~ s/.*:://;
1be0b951 CS	293	my $val = constant($constname, @_ ? $_[0] : 0);
1be0b951 CS	294	if ($! != 0) {
265f5c4a	295	if ($! =~ /Invalid/ \|\| $!{EINVAL}) {
7d4fbd98	296	$AutoLoader::AUTOLOAD = $sub;
1be0b951 CS	297	goto &AutoLoader::AUTOLOAD;
	298	}
	299	else {
	300	croak "Your vendor has not defined constant $constname";
	301	}
	302	}
7d4fbd98 GS	303	*$sub = sub { $val }; # same as: eval "sub $sub { $val }";
7d4fbd98 GS	304	goto &$sub;
1be0b951 CS	305	}
	306
	307	If any module's own AUTOLOAD subroutine has no need to fallback to the
	308	AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
	309	subroutines), then that module should not use B<AutoLoader> at all.
	310
	311	=head2 Package Lexicals
	312
	313	Package lexicals declared with C<my> in the main block of a package
	314	using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
	315	the fact that the given scope ends at the C<__END__> marker. A module
	316	using such variables as package globals will not work properly under the
	317	B<AutoLoader>.
	318
	319	The C<vars> pragma (see L<perlmod/"vars">) may be used in such
	320	situations as an alternative to explicitly qualifying all globals with
	321	the package namespace. Variables pre-declared with this pragma will be
	322	visible to any autoloaded routines (but will not be invisible outside
	323	the package, unfortunately).
	324
cb0cff20 JH	325	=head2 Not Using AutoLoader
	326
	327	You can stop using AutoLoader by simply
	328
	329	no AutoLoader;
	330
1be0b951 CS	331	=head2 B<AutoLoader> vs. B<SelfLoader>
	332
	333	The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
	334	loading of subroutines.
	335
	336	B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
	337	While this avoids the use of a hierarchy of disk files and the
	338	associated open/close for each routine loaded, B<SelfLoader> suffers a
	339	startup speed disadvantage in the one-time parsing of the lines after
	340	C<__DATA__>, after which routines are cached. B<SelfLoader> can also
	341	handle multiple packages in a file.
	342
	343	B<AutoLoader> only reads code as it is requested, and in many cases
f610777f	344	should be faster, but requires a mechanism like B<AutoSplit> be used to
1be0b951 CS	345	create the individual files. L<ExtUtils::MakeMaker> will invoke
	346	B<AutoSplit> automatically if B<AutoLoader> is used in a module source
	347	file.
	348
	349	=head1 CAVEATS
	350
	351	AutoLoaders prior to Perl 5.002 had a slightly different interface. Any
	352	old modules which use B<AutoLoader> should be changed to the new calling
	353	style. Typically this just means changing a require to a use, adding
	354	the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
	355	from C<@ISA>.
	356
	357	On systems with restrictions on file name length, the file corresponding
	358	to a subroutine may have a shorter name that the routine itself. This
	359	can lead to conflicting file names. The I<AutoSplit> package warns of
	360	these potential conflicts when used to split a module.
	361
adaafad2 GS	362	AutoLoader may fail to find the autosplit files (or even find the wrong
	363	ones) in cases where C<@INC> contains relative paths, B<and> the program
	364	does C<chdir>.
	365
1be0b951 CS	366	=head1 SEE ALSO
	367
	368	L<SelfLoader> - an autoloader that doesn't use external files.
	369
	370	=cut