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

package AutoLoader;

use strict;
use 5.006_001;

our($VERSION, $AUTOLOAD);

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

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

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') {
	    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 import {
    my $pkg = shift;
    my $callpkg = caller;

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

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