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