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

AUTOLOAD {
    my $sub = $AUTOLOAD;
    my $filename = AutoLoader::find_filename( $sub );

    my $save = $@;
    local $!; # Do not munge the value. 
    eval { local $SIG{__DIE__}; require $filename };
    if ($@) {
	if (substr($sub,-9) eq '::DESTROY') {
	    no strict 'refs';
	    *$sub = sub {};
	    $@ = undef;
	} elsif ($@ =~ /^Can't locate/) {
	    # The load might just have failed because the filename was too
	    # long for some old SVR3 systems which treat long names as errors.
	    # If we can successfully truncate a long name then it's worth a go.
	    # There is a slight risk that we could pick up the wrong file here
	    # but autosplit should have warned about that when splitting.
	    if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
		eval { local $SIG{__DIE__}; require $filename };
	    }
	}
	if ($@){
	    $@ =~ s/ at .*\n//;
	    my $error = $@;
	    require Carp;
	    Carp::croak($error);
	}
    }
    $@ = $save;
    goto &$sub;
}

sub find_filename {
    my $sub = shift;
    my $filename;
    # Braces used to preserve $1 et al.
    {
	# Try to find the autoloaded file from the package-qualified
	# name of the sub. e.g., if the sub needed is
	# Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
	# something like '/usr/lib/perl5/Getopt/Long.pm', and the
	# autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
	#
	# However, if @INC is a relative path, this might not work.  If,
	# for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
	# 'lib/Getopt/Long.pm', and we want to require
	# 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
	# In this case, we simple prepend the 'auto/' and let the
	# C<require> take care of the searching for us.

	my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
	$pkg =~ s#::#/#g;
	if (defined($filename = $INC{"$pkg.pm"})) {
	    if ($is_macos) {
		$pkg =~ tr#/#:#;
		$filename = undef
		  unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto:$pkg:$func.al#s;
	    } else {
		$filename = undef
		  unless $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
	    }

	    # if the file exists, then make sure that it is a
	    # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
	    # or './lib/auto/foo/bar.al'.  This avoids C<require> searching
	    # (and failing) to find the 'lib/auto/foo/bar.al' because it
	    # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').

	    if (defined $filename and -r $filename) {
		unless ($filename =~ m|^/|s) {
		    if ($is_dosish) {
			unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
			    if ($^O ne 'NetWare') {
				$filename = "./$filename";
			    } else {
				$filename = "$filename";
			    }
			}
		    }
		    elsif ($is_epoc) {
			unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
			     $filename = "./$filename";
			}
		    }
		    elsif ($is_vms) {
			# XXX todo by VMSmiths
			$filename = "./$filename";
		    }
		    elsif (!$is_macos) {
			$filename = "./$filename";
		    }
		}
	    }
	    else {
		$filename = undef;
	    }
	}
	unless (defined $filename) {
	    # let C<require> do the searching
	    $filename = "auto/$sub.al";
	    $filename =~ s#::#/#g;
	}
    }
    return $filename;
}

sub import {
    my $pkg = shift;
    my $callpkg = caller;

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

    if ($pkg eq 'AutoLoader') {
	if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) {
	    no strict 'refs';
	    *{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD;
	}
    }

    #
    # Try to find the autosplit index file.  Eg., if the call package
    # is POSIX, then $INC{POSIX.pm} is something like
    # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
    # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
    #
    # However, if @INC is a relative path, this might not work.  If,
    # for example, @INC = ('lib'), then
    # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
    # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
    #

    (my $calldir = $callpkg) =~ s#::#/#g;
    my $path = $INC{$calldir . '.pm'};
    if (defined($path)) {
	# Try absolute path name, but only eval it if the
        # transformation from module path to autosplit.ix path
        # succeeded!
	my $replaced_okay;
	if ($is_macos) {
	    (my $malldir = $calldir) =~ tr#/#:#;
	    $replaced_okay = ($path =~ s#^(.*)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s);
	} else {
	    $replaced_okay = ($path =~ s#^(.*)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#);
	}

	eval { require $path; } if $replaced_okay;
	# If that failed, try relative path with normal @INC searching.
	if (!$replaced_okay or $@) {
	    $path ="auto/$calldir/autosplit.ix";
	    eval { require $path; };
	}
	if ($@) {
	    my $error = $@;
	    require Carp;
	    Carp::carp($error);
	}
    } 
}

sub unimport {
    my $callpkg = caller;

    no strict 'refs';

    for my $exported (qw( AUTOLOAD )) {
	my $symname = $callpkg . '::' . $exported;
	undef *{ $symname } if \&{ $symname } == \&{ $exported };
	*{ $symname } = \&{ $symname };
    }
}

1;

__END__

=head1 NAME

AutoLoader - load subroutines only on demand

=head1 SYNOPSIS

    package Foo;
    use AutoLoader 'AUTOLOAD';   # import the default AUTOLOAD subroutine

    package Bar;
    use AutoLoader;              # don't import AUTOLOAD, define our own
    sub AUTOLOAD {
        ...
        $AutoLoader::AUTOLOAD = "...";
        goto &AutoLoader::AUTOLOAD;
    }

=head1 DESCRIPTION

The B<AutoLoader> module works with the B<AutoSplit> module and the
C<__END__> token to defer the loading of some subroutines until they are
used rather than loading them all at once.

To use B<AutoLoader>, the author of a module has to place the
definitions of subroutines to be autoloaded after an C<__END__> token.
(See L<perldata>.)  The B<AutoSplit> module can then be run manually to
extract the definitions into individual files F<auto/funcname.al>.

B<AutoLoader> implements an AUTOLOAD subroutine.  When an undefined
subroutine in is called in a client module of B<AutoLoader>,
B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
file with a name related to the location of the file from which the
client module was read.  As an example, if F<POSIX.pm> is located in
F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
the C<.al> file has the same name as the subroutine, sans package.  If
such a file exists, AUTOLOAD will read and evaluate it,
thus (presumably) defining the needed subroutine.  AUTOLOAD will then
C<goto> the newly defined subroutine.

Once this process completes for a given function, it is defined, so
future calls to the subroutine will bypass the AUTOLOAD mechanism.

=head2 Subroutine Stubs

In order for object method lookup and/or prototype checking to operate
correctly even when methods have not yet been defined it is necessary to
"forward declare" each subroutine (as in C<sub NAME;>).  See
L<perlsub/"SYNOPSIS">.  Such forward declaration creates "subroutine
stubs", which are place holders with no code.

The AutoSplit and B<AutoLoader> modules automate the creation of forward
declarations.  The AutoSplit module creates an 'index' file containing
forward declarations of all the AutoSplit subroutines.  When the
AutoLoader module is 'use'd it loads these declarations into its callers
package.

Because of this mechanism it is important that B<AutoLoader> is always
C<use>d and not C<require>d.

=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine

In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
explicitly import it:

    use AutoLoader 'AUTOLOAD';

=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine

Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
They typically need to check for some special cases (such as constants)
and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.

Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
Instead, they should define their own AUTOLOAD subroutines along these
lines:

    use AutoLoader;
    use Carp;

    sub AUTOLOAD {
        my $sub = $AUTOLOAD;
        (my $constname = $sub) =~ s/.*:://;
        my $val = constant($constname, @_ ? $_[0] : 0);
        if ($! != 0) {
            if ($! =~ /Invalid/ || $!{EINVAL}) {
                $AutoLoader::AUTOLOAD = $sub;
                goto &AutoLoader::AUTOLOAD;
            }
            else {
                croak "Your vendor has not defined constant $constname";
            }
        }
        *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
        goto &$sub;
    }

If any module's own AUTOLOAD subroutine has no need to fallback to the
AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
subroutines), then that module should not use B<AutoLoader> at all.

=head2 Package Lexicals

Package lexicals declared with C<my> in the main block of a package
using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
the fact that the given scope ends at the C<__END__> marker.  A module
using such variables as package globals will not work properly under the
B<AutoLoader>.

The C<vars> pragma (see L<perlmod/"vars">) may be used in such
situations as an alternative to explicitly qualifying all globals with
the package namespace.  Variables pre-declared with this pragma will be
visible to any autoloaded routines (but will not be invisible outside
the package, unfortunately).

=head2 Not Using AutoLoader

You can stop using AutoLoader by simply

	no AutoLoader;

=head2 B<AutoLoader> vs. B<SelfLoader>

The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
loading of subroutines.

B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
While this avoids the use of a hierarchy of disk files and the
associated open/close for each routine loaded, B<SelfLoader> suffers a
startup speed disadvantage in the one-time parsing of the lines after
C<__DATA__>, after which routines are cached.  B<SelfLoader> can also
handle multiple packages in a file.

B<AutoLoader> only reads code as it is requested, and in many cases
should be faster, but requires a mechanism like B<AutoSplit> be used to
create the individual files.  L<ExtUtils::MakeMaker> will invoke
B<AutoSplit> automatically if B<AutoLoader> is used in a module source
file.

=head1 CAVEATS

AutoLoaders prior to Perl 5.002 had a slightly different interface.  Any
old modules which use B<AutoLoader> should be changed to the new calling
style.  Typically this just means changing a require to a use, adding
the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
from C<@ISA>.

On systems with restrictions on file name length, the file corresponding
to a subroutine may have a shorter name that the routine itself.  This
can lead to conflicting file names.  The I<AutoSplit> package warns of
these potential conflicts when used to split a module.

AutoLoader may fail to find the autosplit files (or even find the wrong
ones) in cases where C<@INC> contains relative paths, B<and> the program
does C<chdir>.

=head1 SEE ALSO

L<SelfLoader> - an autoloader that doesn't use external files.

=head1 AUTHOR

C<AutoLoader> is maintained by the perl5-porters. Please direct
any questions to the canonical mailing list. Anything that
is applicable to the CPAN release can be sent to its maintainer,
though.

Author and Maintainer: The Perl5-Porters <perl5-porters@perl.org>

Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>

=head1 COPYRIGHT AND LICENSE

This package has been part of the perl core since the first release
of perl5. It has been released separately to CPAN so older installations
can benefit from bug fixes.

This package has the same copyright and license as the perl core:

             Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999,
        2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
        by Larry Wall and others
    
			    All rights reserved.
    
    This program is free software; you can redistribute it and/or modify
    it under the terms of either:
    
	a) the GNU General Public License as published by the Free
	Software Foundation; either version 1, or (at your option) any
	later version, or
    
	b) the "Artistic License" which comes with this Kit.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either
    the GNU General Public License or the Artistic License for more details.
    
    You should have received a copy of the Artistic License with this
    Kit, in the file named "Artistic".  If not, I'll be glad to provide one.
    
    You should also have received a copy of the GNU General Public License
    along with this program in the file named "Copying". If not, write to the 
    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
    02111-1307, USA or visit their web page on the internet at
    http://www.gnu.org/copyleft/gpl.html.
    
    For those of you that choose to use the GNU General Public License,
    my interpretation of the GNU General Public License is that no Perl
    script falls under the terms of the GPL unless you explicitly put
    said script under the terms of the GPL yourself.  Furthermore, any
    object code linked with perl does not automatically fall under the
    terms of the GPL, provided such object code only adds definitions
    of subroutines and variables, and does not otherwise impair the
    resulting interpreter from executing any standard Perl script.  I
    consider linking in C subroutines in this manner to be the moral
    equivalent of defining subroutines in the Perl language itself.  You
    may sell such an object file as proprietary provided that you provide
    or offer to provide the Perl source, as specified by the GNU General
    Public License.  (This is merely an alternate way of specifying input
    to the program.)  You may also sell a binary produced by the dumping of
    a running Perl script that belongs to you, provided that you provide or
    offer to provide the Perl source as specified by the GPL.  (The
    fact that a Perl interpreter and your code are in the same binary file
    is, in this case, a form of mere aggregation.)  This is my interpretation
    of the GPL.  If you still have concerns or difficulties understanding
    my intent, feel free to contact me.  Of course, the Artistic License
    spells all this out for your protection, so you may prefer to use that.

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