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

package AutoLoader;

use 5.005_64;
our(@EXPORT, @EXPORT_OK, $VERSION);

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

BEGIN {
    require Exporter;
    @EXPORT = @EXPORT = ();
    @EXPORT_OK = @EXPORT_OK = qw(AUTOLOAD);
    $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.58';
}

AUTOLOAD {
    my $sub = $AUTOLOAD;
    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;
	}
    }
    my $save = $@;
    local $!; # Do not munge the value. 
    eval { local $SIG{__DIE__}; require $filename };
    if ($@) {
	if (substr($sub,-9) eq '::DESTROY') {
	    *$sub = sub {};
	} else {
	    # 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 succesfully 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 import {
    my $pkg = shift;
    my $callpkg = caller;

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

    if ($pkg eq 'AutoLoader') {
      local $Exporter::ExportLevel = 1;
      Exporter::import $pkg, @_;
    }

    #
    # 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.
	$path =~ s#^(.*)$calldir\.pm$#$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;
  eval "package $callpkg; sub AUTOLOAD;";
}

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
17f410f9	3	use 5.005_64;
17f410f9	4	our(@EXPORT, @EXPORT_OK, $VERSION);
f06db76b	5
adaafad2	6	my $is_dosish;
ed79a026	7	my $is_epoc;
adaafad2	8	my $is_vms;
084592ab	9	my $is_macos;
adaafad2	10
1be0b951	11	BEGIN {
1be0b951	12	require Exporter;
e3d0cac0	13	@EXPORT = @EXPORT = ();
e3d0cac0	14	@EXPORT_OK = @EXPORT_OK = qw(AUTOLOAD);
2986a63f	15	$is_dosish = $^O eq 'dos' \|\| $^O eq 'os2' \|\| $^O eq 'MSWin32' \|\| $^O eq 'NetWare';
ed79a026	16	$is_epoc = $^O eq 'epoc';
adaafad2	17	$is_vms = $^O eq 'VMS';
084592ab	18	$is_macos = $^O eq 'MacOS';
084592ab	19	$VERSION = '5.58';
1be0b951	20	}
f06db76b	21
8990e307	22	AUTOLOAD {
7d4fbd98	23	my $sub = $AUTOLOAD;
7d4fbd98	24	my $filename;
5a556d17	25	# Braces used to preserve $1 et al.
5a556d17	26	{
adaafad2	27	# Try to find the autoloaded file from the package-qualified
	28	# name of the sub. e.g., if the sub needed is
	29	# Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
	30	# something like '/usr/lib/perl5/Getopt/Long.pm', and the
	31	# autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
	32	#
	33	# However, if @INC is a relative path, this might not work. If,
	34	# for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
	35	# 'lib/Getopt/Long.pm', and we want to require
	36	# 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
	37	# In this case, we simple prepend the 'auto/' and let the
	38	# C<require> take care of the searching for us.
	39
7d4fbd98	40	my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
adaafad2	41	$pkg =~ s#::#/#g;
7d4fbd98	42	if (defined($filename = $INC{"$pkg.pm"})) {
084592ab	43	if ($is_macos) {
	44	$pkg =~ tr#/#:#;
	45	$filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
	46	} else {
	47	$filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
	48	}
adaafad2	49
	50	# if the file exists, then make sure that it is a
	51	# a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
	52	# or './lib/auto/foo/bar.al'. This avoids C<require> searching
	53	# (and failing) to find the 'lib/auto/foo/bar.al' because it
	54	# looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
	55
7d4fbd98	56	if (-r $filename) {
14a089c5	57	unless ($filename =~ m\|^/\|s) {
adaafad2	58	if ($is_dosish) {
14a089c5	59	unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
2986a63f	60	if ($^O ne 'NetWare') {
	61	$filename = "./$filename";
	62	} else {
	63	$filename = "$filename";
	64	}
adaafad2	65	}
adaafad2	66	}
ed79a026	67	elsif ($is_epoc) {
	68	unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
	69	$filename = "./$filename";
	70	}
	71	}elsif ($is_vms) {
7d4fbd98	72	# XXX todo by VMSmiths
7d4fbd98	73	$filename = "./$filename";
adaafad2	74	}
084592ab	75	elsif (!$is_macos) {
7d4fbd98	76	$filename = "./$filename";
adaafad2	77	}
	78	}
	79	}
	80	else {
7d4fbd98	81	$filename = undef;
adaafad2	82	}
adaafad2	83	}
7d4fbd98	84	unless (defined $filename) {
adaafad2	85	# let C<require> do the searching
7d4fbd98	86	$filename = "auto/$sub.al";
7d4fbd98	87	$filename =~ s#::#/#g;
adaafad2	88	}
5a556d17	89	}
e14baed2	90	my $save = $@;
212caf55	91	local $!; # Do not munge the value.
7d4fbd98	92	eval { local $SIG{__DIE__}; require $filename };
8990e307	93	if ($@) {
7d4fbd98	94	if (substr($sub,-9) eq '::DESTROY') {
7d4fbd98	95	*$sub = sub {};
e14baed2	96	} else {
	97	# The load might just have failed because the filename was too
	98	# long for some old SVR3 systems which treat long names as errors.
	99	# If we can succesfully truncate a long name then it's worth a go.
	100	# There is a slight risk that we could pick up the wrong file here
	101	# but autosplit should have warned about that when splitting.
7d4fbd98	102	if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
7d4fbd98	103	eval { local $SIG{__DIE__}; require $filename };
e14baed2	104	}
	105	if ($@){
	106	$@ =~ s/ at .*\n//;
fb73857a	107	my $error = $@;
	108	require Carp;
	109	Carp::croak($error);
e14baed2	110	}
a0d0e21e	111	}
8990e307	112	}
e14baed2	113	$@ = $save;
7d4fbd98	114	goto &$sub;
8990e307	115	}
1be0b951	116
c2960299	117	sub import {
1be0b951	118	my $pkg = shift;
	119	my $callpkg = caller;
	120
	121	#
	122	# Export symbols, but not by accident of inheritance.
	123	#
	124
e3d0cac0	125	if ($pkg eq 'AutoLoader') {
	126	local $Exporter::ExportLevel = 1;
	127	Exporter::import $pkg, @_;
	128	}
1be0b951	129
1be0b951	130	#
c2960299	131	# Try to find the autosplit index file. Eg., if the call package
	132	# is POSIX, then $INC{POSIX.pm} is something like
	133	# '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
	134	# '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
	135	#
	136	# However, if @INC is a relative path, this might not work. If,
	137	# for example, @INC = ('lib'), then
	138	# $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
	139	# 'auto/POSIX/autosplit.ix' (without the leading 'lib').
	140	#
1be0b951	141
1c1c7f20	142	(my $calldir = $callpkg) =~ s#::#/#g;
1be0b951	143	my $path = $INC{$calldir . '.pm'};
1be0b951	144	if (defined($path)) {
c2960299	145	# Try absolute path name.
1be0b951	146	$path =~ s#^(.*)$calldir\.pm$#$1auto/$calldir/autosplit.ix#;
c2960299	147	eval { require $path; };
	148	# If that failed, try relative path with normal @INC searching.
	149	if ($@) {
1be0b951	150	$path ="auto/$calldir/autosplit.ix";
c2960299	151	eval { require $path; };
c2960299	152	}
fb73857a	153	if ($@) {
	154	my $error = $@;
	155	require Carp;
	156	Carp::carp($error);
	157	}
f06db76b	158	}
f06db76b	159	}
8990e307	160
cb0cff20	161	sub unimport {
	162	my $callpkg = caller;
	163	eval "package $callpkg; sub AUTOLOAD;";
	164	}
	165
8990e307	166	1;
1be0b951	167
	168	__END__
	169
	170	=head1 NAME
	171
	172	AutoLoader - load subroutines only on demand
	173
	174	=head1 SYNOPSIS
	175
	176	package Foo;
	177	use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine
	178
	179	package Bar;
	180	use AutoLoader; # don't import AUTOLOAD, define our own
	181	sub AUTOLOAD {
	182	...
	183	$AutoLoader::AUTOLOAD = "...";
	184	goto &AutoLoader::AUTOLOAD;
	185	}
	186
	187	=head1 DESCRIPTION
	188
	189	The B<AutoLoader> module works with the B<AutoSplit> module and the
	190	C<__END__> token to defer the loading of some subroutines until they are
	191	used rather than loading them all at once.
	192
	193	To use B<AutoLoader>, the author of a module has to place the
	194	definitions of subroutines to be autoloaded after an C<__END__> token.
	195	(See L<perldata>.) The B<AutoSplit> module can then be run manually to
	196	extract the definitions into individual files F<auto/funcname.al>.
	197
	198	B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined
	199	subroutine in is called in a client module of B<AutoLoader>,
	200	B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
	201	file with a name related to the location of the file from which the
	202	client module was read. As an example, if F<POSIX.pm> is located in
	203	F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
	204	subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
	205	the C<.al> file has the same name as the subroutine, sans package. If
	206	such a file exists, AUTOLOAD will read and evaluate it,
	207	thus (presumably) defining the needed subroutine. AUTOLOAD will then
	208	C<goto> the newly defined subroutine.
	209
f610777f	210	Once this process completes for a given function, it is defined, so
1be0b951	211	future calls to the subroutine will bypass the AUTOLOAD mechanism.
	212
	213	=head2 Subroutine Stubs
	214
	215	In order for object method lookup and/or prototype checking to operate
	216	correctly even when methods have not yet been defined it is necessary to
	217	"forward declare" each subroutine (as in C<sub NAME;>). See
	218	L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine
	219	stubs", which are place holders with no code.
	220
	221	The AutoSplit and B<AutoLoader> modules automate the creation of forward
	222	declarations. The AutoSplit module creates an 'index' file containing
	223	forward declarations of all the AutoSplit subroutines. When the
	224	AutoLoader module is 'use'd it loads these declarations into its callers
	225	package.
	226
	227	Because of this mechanism it is important that B<AutoLoader> is always
	228	C<use>d and not C<require>d.
	229
	230	=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
	231
	232	In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
	233	explicitly import it:
	234
	235	use AutoLoader 'AUTOLOAD';
	236
	237	=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
	238
	239	Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
	240	They typically need to check for some special cases (such as constants)
	241	and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
	242
	243	Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
	244	Instead, they should define their own AUTOLOAD subroutines along these
	245	lines:
	246
	247	use AutoLoader;
fb73857a	248	use Carp;
1be0b951	249
1be0b951	250	sub AUTOLOAD {
7d4fbd98	251	my $sub = $AUTOLOAD;
7d4fbd98	252	(my $constname = $sub) =~ s/.*:://;
1be0b951	253	my $val = constant($constname, @_ ? $_[0] : 0);
1be0b951	254	if ($! != 0) {
265f5c4a	255	if ($! =~ /Invalid/ \|\| $!{EINVAL}) {
7d4fbd98	256	$AutoLoader::AUTOLOAD = $sub;
1be0b951	257	goto &AutoLoader::AUTOLOAD;
	258	}
	259	else {
	260	croak "Your vendor has not defined constant $constname";
	261	}
	262	}
7d4fbd98	263	*$sub = sub { $val }; # same as: eval "sub $sub { $val }";
7d4fbd98	264	goto &$sub;
1be0b951	265	}
	266
	267	If any module's own AUTOLOAD subroutine has no need to fallback to the
	268	AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
	269	subroutines), then that module should not use B<AutoLoader> at all.
	270
	271	=head2 Package Lexicals
	272
	273	Package lexicals declared with C<my> in the main block of a package
	274	using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
	275	the fact that the given scope ends at the C<__END__> marker. A module
	276	using such variables as package globals will not work properly under the
	277	B<AutoLoader>.
	278
	279	The C<vars> pragma (see L<perlmod/"vars">) may be used in such
	280	situations as an alternative to explicitly qualifying all globals with
	281	the package namespace. Variables pre-declared with this pragma will be
	282	visible to any autoloaded routines (but will not be invisible outside
	283	the package, unfortunately).
	284
cb0cff20	285	=head2 Not Using AutoLoader
	286
	287	You can stop using AutoLoader by simply
	288
	289	no AutoLoader;
	290
1be0b951	291	=head2 B<AutoLoader> vs. B<SelfLoader>
	292
	293	The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
	294	loading of subroutines.
	295
	296	B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
	297	While this avoids the use of a hierarchy of disk files and the
	298	associated open/close for each routine loaded, B<SelfLoader> suffers a
	299	startup speed disadvantage in the one-time parsing of the lines after
	300	C<__DATA__>, after which routines are cached. B<SelfLoader> can also
	301	handle multiple packages in a file.
	302
	303	B<AutoLoader> only reads code as it is requested, and in many cases
f610777f	304	should be faster, but requires a mechanism like B<AutoSplit> be used to
1be0b951	305	create the individual files. L<ExtUtils::MakeMaker> will invoke
	306	B<AutoSplit> automatically if B<AutoLoader> is used in a module source
	307	file.
	308
	309	=head1 CAVEATS
	310
	311	AutoLoaders prior to Perl 5.002 had a slightly different interface. Any
	312	old modules which use B<AutoLoader> should be changed to the new calling
	313	style. Typically this just means changing a require to a use, adding
	314	the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
	315	from C<@ISA>.
	316
	317	On systems with restrictions on file name length, the file corresponding
	318	to a subroutine may have a shorter name that the routine itself. This
	319	can lead to conflicting file names. The I<AutoSplit> package warns of
	320	these potential conflicts when used to split a module.
	321
adaafad2	322	AutoLoader may fail to find the autosplit files (or even find the wrong
	323	ones) in cases where C<@INC> contains relative paths, B<and> the program
	324	does C<chdir>.
	325
1be0b951	326	=head1 SEE ALSO
	327
	328	L<SelfLoader> - an autoloader that doesn't use external files.
	329
	330	=cut