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