Commit | Line | Data |
8990e307 |
1 | package AutoLoader; |
a0d0e21e |
2 | use Carp; |
1a4c2889 |
3 | $DB::sub = $DB::sub; # Avoid warning |
8990e307 |
4 | |
f06db76b |
5 | =head1 NAME |
6 | |
7 | AutoLoader - load functions only on demand |
8 | |
9 | =head1 SYNOPSIS |
10 | |
11 | package FOOBAR; |
12 | use Exporter; |
13 | use AutoLoader; |
14 | @ISA = (Exporter, AutoLoader); |
15 | |
16 | =head1 DESCRIPTION |
17 | |
21c92a1d |
18 | This module tells its users that functions in the FOOBAR package are |
19 | to be autoloaded from F<auto/$AUTOLOAD.al>. See |
20 | L<perlsub/"Autoloading"> and L<AutoSplit>. |
21 | |
22 | =head2 __END__ |
23 | |
24 | The module using the autoloader should have the special marker C<__END__> |
25 | prior to the actual subroutine declarations. All code that is before the |
26 | marker will be loaded and compiled when the module is used. At the marker, |
27 | perl will cease reading and parsing. See also the B<AutoSplit> module, a |
28 | utility that automatically splits a module into a collection of files for |
29 | autoloading. |
30 | |
31 | When a subroutine not yet in memory is called, the C<AUTOLOAD> function |
32 | attempts to locate it in a directory relative to the location of the module |
33 | file itself. As an example, assume F<POSIX.pm> is located in |
34 | F</usr/local/lib/perl5/POSIX.pm>. The autoloader will look for perl |
35 | subroutines for this package in F</usr/local/lib/perl5/auto/POSIX/*.al>. |
36 | The C<.al> file is named using the subroutine name, sans package. |
37 | |
38 | =head2 Package Lexicals |
39 | |
40 | Package lexicals declared with C<my> in the main block of a package using |
41 | the B<AutoLoader> will not be visible to auto-loaded functions, due to the |
42 | fact that the given scope ends at the C<__END__> marker. A module using such |
43 | variables as package globals will not work properly under the B<AutoLoader>. |
44 | |
45 | The C<vars> pragma (see L<perlmod/"vars">) may be used in such situations |
46 | as an alternative to explicitly qualifying all globals with the package |
47 | namespace. Variables pre-declared with this pragma will be visible to any |
48 | autoloaded routines (but will not be invisible outside the package, |
49 | unfortunately). |
50 | |
51 | =head2 AutoLoader vs. SelfLoader |
52 | |
53 | The B<AutoLoader> is a counterpart to the B<SelfLoader> module. Both delay |
54 | the loading of subroutines, but the B<SelfLoader> accomplishes the goal via |
55 | the C<__DATA__> marker rather than C<__END__>. While this avoids the use of |
56 | a hierarchy of disk files and the associated open/close for each routine |
57 | loaded, the B<SelfLoader> suffers a disadvantage in the one-time parsing of |
58 | the lines after C<__DATA__>, after which routines are cached. B<SelfLoader> |
59 | can also handle multiple packages in a file. |
60 | |
61 | B<AutoLoader> only reads code as it is requested, and in many cases should be |
62 | faster, but requires a machanism like B<AutoSplit> be used to create the |
63 | individual files. |
64 | |
65 | =head1 CAVEAT |
66 | |
67 | On systems with restrictions on file name length, the file corresponding to a |
68 | subroutine may have a shorter name that the routine itself. This can lead to |
69 | conflicting file names. The I<AutoSplit> package warns of these potential |
70 | conflicts when used to split a module. |
f06db76b |
71 | |
72 | =cut |
73 | |
8990e307 |
74 | AUTOLOAD { |
7c366566 |
75 | my $name = "auto/$AUTOLOAD.al"; |
8990e307 |
76 | $name =~ s#::#/#g; |
77 | eval {require $name}; |
78 | if ($@) { |
a0d0e21e |
79 | # The load might just have failed because the filename was too |
80 | # long for some old SVR3 systems which treat long names as errors. |
81 | # If we can succesfully truncate a long name then it's worth a go. |
82 | # There is a slight risk that we could pick up the wrong file here |
83 | # but autosplit should have warned about that when splitting. |
84 | if ($name =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){ |
85 | eval {require $name}; |
86 | } |
748a9306 |
87 | elsif ($AUTOLOAD =~ /::DESTROY$/) { |
4633a7c4 |
88 | # eval "sub $AUTOLOAD {}"; |
89 | *$AUTOLOAD = sub {}; |
748a9306 |
90 | } |
a0d0e21e |
91 | if ($@){ |
92 | $@ =~ s/ at .*\n//; |
93 | croak $@; |
94 | } |
8990e307 |
95 | } |
5b930e62 |
96 | $DB::sub = $AUTOLOAD; # Now debugger know where we are. |
8990e307 |
97 | goto &$AUTOLOAD; |
98 | } |
f06db76b |
99 | |
c2960299 |
100 | sub import { |
101 | my ($callclass, $callfile, $callline,$path,$callpack) = caller(0); |
102 | ($callpack = $callclass) =~ s#::#/#; |
103 | # Try to find the autosplit index file. Eg., if the call package |
104 | # is POSIX, then $INC{POSIX.pm} is something like |
105 | # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in |
106 | # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that. |
107 | # |
108 | # However, if @INC is a relative path, this might not work. If, |
109 | # for example, @INC = ('lib'), then |
110 | # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require |
111 | # 'auto/POSIX/autosplit.ix' (without the leading 'lib'). |
112 | # |
113 | if (defined($path = $INC{$callpack . '.pm'})) { |
114 | # Try absolute path name. |
115 | $path =~ s#^(.*)$callpack\.pm$#$1auto/$callpack/autosplit.ix#; |
116 | eval { require $path; }; |
117 | # If that failed, try relative path with normal @INC searching. |
118 | if ($@) { |
119 | $path ="auto/$callpack/autosplit.ix"; |
120 | eval { require $path; }; |
121 | } |
122 | carp $@ if ($@); |
f06db76b |
123 | } |
f06db76b |
124 | } |
8990e307 |
125 | |
126 | 1; |