1package Module::Load;
2
3$VERSION = '0.34';
4
5use strict;
6use warnings;
7use File::Spec ();
8
9sub import {
10    my $who = _who();
11    my $h; shift;
12
13    {   no strict 'refs';
14
15        @_ or (
16            *{"${who}::load"} = \&load, # compat to prev version
17            *{"${who}::autoload"} = \&autoload,
18            return
19        );
20
21        map { $h->{$_} = () if defined $_ } @_;
22
23        (exists $h->{none} or exists $h->{''})
24            and shift, last;
25
26        ((exists $h->{autoload} and shift,1) or (exists $h->{all} and shift))
27            and *{"${who}::autoload"} = \&autoload;
28
29        ((exists $h->{load} and shift,1) or exists $h->{all})
30            and *{"${who}::load"} = \&load;
31
32        ((exists $h->{load_remote} and shift,1) or exists $h->{all})
33            and *{"${who}::load_remote"} = \&load_remote;
34
35        ((exists $h->{autoload_remote} and shift,1) or exists $h->{all})
36            and *{"${who}::autoload_remote"} = \&autoload_remote;
37
38    }
39
40}
41
42sub load(*;@){
43    goto &_load;
44}
45
46sub autoload(*;@){
47    unshift @_, 'autoimport';
48    goto &_load;
49}
50
51sub load_remote($$;@){
52    my ($dst, $src, @exp) = @_;
53
54    eval "package $dst;Module::Load::load('$src', qw/@exp/);";
55    $@ && die "$@";
56}
57
58sub autoload_remote($$;@){
59    my ($dst, $src, @exp) = @_;
60
61    eval "package $dst;Module::Load::autoload('$src', qw/@exp/);";
62    $@ && die "$@";
63}
64
65sub _load{
66    my $autoimport = $_[0] eq 'autoimport' and shift;
67    my $mod = shift or return;
68    my $who = _who();
69
70    if( _is_file( $mod ) ) {
71        require $mod;
72    } else {
73        LOAD: {
74            my $err;
75            for my $flag ( qw[1 0] ) {
76                my $file = _to_file( $mod, $flag);
77                eval { require $file };
78                $@ ? $err .= $@ : last LOAD;
79            }
80            die $err if $err;
81        }
82    }
83
84    ### This addresses #41883: Module::Load cannot import
85    ### non-Exporter module. ->import() routines weren't
86    ### properly called when load() was used.
87
88    {   no strict 'refs';
89        my $import;
90
91    ((@_ or $autoimport) and (
92        $import = $mod->can('import')
93        ) and (
94        unshift(@_, $mod),
95        goto &$import
96        )
97    );
98    }
99
100}
101
102sub _to_file{
103    local $_    = shift;
104    my $pm      = shift || '';
105
106    ## trailing blanks ignored by default. [rt #69886]
107    my @parts = split /::|'/, $_, -1;
108    ## make sure that we can't hop out of @INC
109    shift @parts if @parts && !$parts[0];
110
111    ### because of [perl #19213], see caveats ###
112    my $file = $^O eq 'MSWin32'
113                    ? join "/", @parts
114                    : File::Spec->catfile( @parts );
115
116    $file   .= '.pm' if $pm;
117
118    ### on perl's before 5.10 (5.9.5@31746) if you require
119    ### a file in VMS format, it's stored in %INC in VMS
120    ### format. Therefor, better unixify it first
121    ### Patch in reply to John Malmbergs patch (as mentioned
122    ### above) on p5p Tue 21 Aug 2007 04:55:07
123    $file = VMS::Filespec::unixify($file) if $^O eq 'VMS';
124
125    return $file;
126}
127
128sub _who { (caller(1))[0] }
129
130sub _is_file {
131    local $_ = shift;
132    return  /^\./               ? 1 :
133            /[^\w:']/           ? 1 :
134            undef
135    #' silly bbedit..
136}
137
138
1391;
140
141__END__
142
143=pod
144
145=head1 NAME
146
147Module::Load - runtime require of both modules and files
148
149=head1 SYNOPSIS
150
151  use Module::Load;
152
153  my $module = 'Data::Dumper';
154
155  load Data::Dumper;     # loads that module, but not import any functions
156                         # -> cannot use 'Dumper' function
157
158  load 'Data::Dumper';   # ditto
159  load $module           # tritto
160
161  autoload Data::Dumper; # loads that module and imports the default functions
162                         # -> can use 'Dumper' function
163
164  my $script = 'some/script.pl'
165  load $script;
166  load 'some/script.pl';  # use quotes because of punctuations
167
168  load thing;             # try 'thing' first, then 'thing.pm'
169
170  load CGI, ':all';       # like 'use CGI qw[:standard]'
171
172=head1 DESCRIPTION
173
174C<Module::Load> eliminates the need to know whether you are trying
175to require either a file or a module.
176
177If you consult C<perldoc -f require> you will see that C<require> will
178behave differently when given a bareword or a string.
179
180In the case of a string, C<require> assumes you are wanting to load a
181file. But in the case of a bareword, it assumes you mean a module.
182
183This gives nasty overhead when you are trying to dynamically require
184modules at runtime, since you will need to change the module notation
185(C<Acme::Comment>) to a file notation fitting the particular platform
186you are on.
187
188C<Module::Load> eliminates the need for this overhead and will
189just DWYM.
190
191=head2 Difference between C<load> and C<autoload>
192
193C<Module::Load> imports the two functions - C<load> and C<autoload>
194
195C<autoload> imports the default functions automatically,
196but C<load> do not import any functions.
197
198C<autoload> is usable under C<BEGIN{};>.
199
200Both the functions can import the functions that are specified.
201
202Following codes are same.
203
204  load File::Spec::Functions, qw/splitpath/;
205
206  autoload File::Spec::Functions, qw/splitpath/;
207
208=head1 FUNCTIONS
209
210=over 4
211
212=item load
213
214Loads a specified module.
215
216See L</Rules> for detailed loading rule.
217
218=item autoload
219
220Loads a specified module and imports the default functions.
221
222Except importing the functions, 'autoload' is same as 'load'.
223
224=item load_remote
225
226Loads a specified module to the specified package.
227
228  use Module::Load 'load_remote';
229
230  my $pkg = 'Other::Package';
231
232  load_remote $pkg, 'Data::Dumper'; # load a module to 'Other::Package'
233                                    # but do not import 'Dumper' function
234
235A module for loading must be quoted.
236
237Except specifing the package and quoting module name,
238'load_remote' is same as 'load'.
239
240=item autoload_remote
241
242Loads a specified module and imports the default functions to the specified package.
243
244  use Module::Load 'autoload_remote';
245
246  my $pkg = 'Other::Package';
247
248  autoload_remote $pkg, 'Data::Dumper'; # load a module to 'Other::Package'
249                                        # and imports 'Dumper' function
250
251A module for loading must be quoted.
252
253Except specifing the package and quoting module name,
254'autoload_remote' is same as 'load_remote'.
255
256=back
257
258=head1 Rules
259
260All functions have the following rules to decide what it thinks
261you want:
262
263=over 4
264
265=item *
266
267If the argument has any characters in it other than those matching
268C<\w>, C<:> or C<'>, it must be a file
269
270=item *
271
272If the argument matches only C<[\w:']>, it must be a module
273
274=item *
275
276If the argument matches only C<\w>, it could either be a module or a
277file. We will try to find C<file.pm> first in C<@INC> and if that
278fails, we will try to find C<file> in @INC.  If both fail, we die with
279the respective error messages.
280
281=back
282
283=head1 IMPORTS THE FUNCTIONS
284
285'load' and 'autoload' are imported by default, but 'load_remote' and
286'autoload_remote' are not imported.
287
288To use 'load_remote' or 'autoload_remote', specify at 'use'.
289
290=over 4
291
292=item "load","autoload","load_remote","autoload_remote"
293
294Imports the selected functions.
295
296  # imports 'load' and 'autoload' (default)
297  use Module::Load;
298
299  # imports 'autoload' only
300  use Module::Load 'autoload';
301
302  # imports 'autoload' and 'autoload_remote', but don't import 'load';
303  use Module::Load qw/autoload autoload_remote/;
304
305=item 'all'
306
307Imports all the functions.
308
309  use Module::Load 'all'; # imports load, autoload, load_remote, autoload_remote
310
311=item '','none',undef
312
313Not import any functions (C<load> and C<autoload> are not imported).
314
315  use Module::Load '';
316
317  use Module::Load 'none';
318
319  use Module::Load undef;
320
321=back
322
323=head1 Caveats
324
325Because of a bug in perl (#19213), at least in version 5.6.1, we have
326to hardcode the path separator for a require on Win32 to be C</>, like
327on Unix rather than the Win32 C<\>. Otherwise perl will not read its
328own %INC accurately double load files if they are required again, or
329in the worst case, core dump.
330
331C<Module::Load> cannot do implicit imports, only explicit imports.
332(in other words, you always have to specify explicitly what you wish
333to import from a module, even if the functions are in that modules'
334C<@EXPORT>)
335
336=head1 SEE ALSO
337
338L<Module::Runtime> provides functions for loading modules,
339checking the validity of a module name,
340converting a module name to partial C<.pm> path,
341and related utility functions.
342
343L<"require" in perlfunc|https://metacpan.org/pod/perlfunc#require>
344and
345L<"use" in perlfunc|https://metacpan.org/pod/perlfunc#use>.
346
347L<Mojo::Loader> is a "class loader and plugin framework",
348and is included in the
349L<Mojolicious|https://metacpan.org/release/Mojolicious> distribution.
350
351L<Module::Loader> is a module for finding and loading modules
352in a given namespace, inspired by C<Mojo::Loader>.
353
354
355=head1 ACKNOWLEDGEMENTS
356
357Thanks to Jonas B. Nielsen for making explicit imports work.
358
359=head1 BUG REPORTS
360
361Please report bugs or other issues to E<lt>bug-module-load@rt.cpan.org<gt>.
362
363=head1 AUTHOR
364
365This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
366
367=head1 COPYRIGHT
368
369This library is free software; you may redistribute and/or modify it
370under the same terms as Perl itself.
371
372=cut
373