summaryrefslogtreecommitdiff
path: root/systems/texlive/tlnet/tlpkg/tlperl/lib/Module/Load.pm
blob: 28294eee569175fdb51a94bbc4d8a55fd6392fab (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
package Module::Load;

use strict;
use warnings;
use File::Spec ();

our $VERSION = '0.36';


sub import {
    my $who = _who();
    my $h; shift;

    {   no strict 'refs';

        @_ or (
            *{"${who}::load"} = \&load, # compat to prev version
            *{"${who}::autoload"} = \&autoload,
            return
        );

        map { $h->{$_} = () if defined $_ } @_;

        (exists $h->{none} or exists $h->{''})
            and shift, last;

        ((exists $h->{autoload} and shift,1) or (exists $h->{all} and shift))
            and *{"${who}::autoload"} = \&autoload;

        ((exists $h->{load} and shift,1) or exists $h->{all})
            and *{"${who}::load"} = \&load;

        ((exists $h->{load_remote} and shift,1) or exists $h->{all})
            and *{"${who}::load_remote"} = \&load_remote;

        ((exists $h->{autoload_remote} and shift,1) or exists $h->{all})
            and *{"${who}::autoload_remote"} = \&autoload_remote;

    }

}

sub load(*;@){
    goto &_load;
}

sub autoload(*;@){
    unshift @_, 'autoimport';
    goto &_load;
}

sub load_remote($$;@){
    my ($dst, $src, @exp) = @_;

    eval "package $dst;Module::Load::load('$src', qw/@exp/);";
    $@ && die "$@";
}

sub autoload_remote($$;@){
    my ($dst, $src, @exp) = @_;

    eval "package $dst;Module::Load::autoload('$src', qw/@exp/);";
    $@ && die "$@";
}

sub _load{
    my $autoimport = $_[0] eq 'autoimport' and shift;
    my $mod = shift or return;
    my $who = _who();

    if( _is_file( $mod ) ) {
        require $mod;
    } else {
        LOAD: {
            my $err;
            for my $flag ( qw[1 0] ) {
                my $file = _to_file( $mod, $flag);
                eval { require $file };
                $@ ? $err .= $@ : last LOAD;
            }
            die $err if $err;
        }
    }

    ### This addresses #41883: Module::Load cannot import
    ### non-Exporter module. ->import() routines weren't
    ### properly called when load() was used.

    {   no strict 'refs';
        my $import;

    ((@_ or $autoimport) and (
        $import = $mod->can('import')
        ) and (
        unshift(@_, $mod),
        goto &$import
        )
    );
    }

}

sub _to_file{
    local $_    = shift;
    my $pm      = shift || '';

    ## trailing blanks ignored by default. [rt #69886]
    my @parts = split /::|'/, $_, -1;
    ## make sure that we can't hop out of @INC
    shift @parts if @parts && !$parts[0];

    ### because of [perl #19213], see caveats ###
    my $file = $^O eq 'MSWin32'
                    ? join "/", @parts
                    : File::Spec->catfile( @parts );

    $file   .= '.pm' if $pm;

    ### on perl's before 5.10 (5.9.5@31746) if you require
    ### a file in VMS format, it's stored in %INC in VMS
    ### format. Therefor, better unixify it first
    ### Patch in reply to John Malmbergs patch (as mentioned
    ### above) on p5p Tue 21 Aug 2007 04:55:07
    $file = VMS::Filespec::unixify($file) if $^O eq 'VMS';

    return $file;
}

sub _who { (caller(1))[0] }

sub _is_file {
    local $_ = shift;
    return  /^\./               ? 1 :
            /[^\w:']/           ? 1 :
            undef
    #' silly bbedit..
}


1;

__END__

=pod

=head1 NAME

Module::Load - runtime require of both modules and files

=head1 SYNOPSIS

  use Module::Load;

  my $module = 'Data::Dumper';

  load Data::Dumper;     # loads that module, but not import any functions
                         # -> cannot use 'Dumper' function

  load 'Data::Dumper';   # ditto
  load $module           # tritto

  autoload Data::Dumper; # loads that module and imports the default functions
                         # -> can use 'Dumper' function

  my $script = 'some/script.pl'
  load $script;
  load 'some/script.pl';  # use quotes because of punctuations

  load thing;             # try 'thing' first, then 'thing.pm'

  load CGI, ':all';       # like 'use CGI qw[:standard]'

=head1 DESCRIPTION

C<Module::Load> eliminates the need to know whether you are trying
to require either a file or a module.

If you consult C<perldoc -f require> you will see that C<require> will
behave differently when given a bareword or a string.

In the case of a string, C<require> assumes you are wanting to load a
file. But in the case of a bareword, it assumes you mean a module.

This gives nasty overhead when you are trying to dynamically require
modules at runtime, since you will need to change the module notation
(C<Acme::Comment>) to a file notation fitting the particular platform
you are on.

C<Module::Load> eliminates the need for this overhead and will
just DWYM.

=head2 Difference between C<load> and C<autoload>

C<Module::Load> imports the two functions - C<load> and C<autoload>

C<autoload> imports the default functions automatically,
but C<load> do not import any functions.

C<autoload> is usable under C<BEGIN{};>.

Both the functions can import the functions that are specified.

Following codes are same.

  load File::Spec::Functions, qw/splitpath/;

  autoload File::Spec::Functions, qw/splitpath/;

=head1 FUNCTIONS

=over 4

=item load

Loads a specified module.

See L</Rules> for detailed loading rule.

=item autoload

Loads a specified module and imports the default functions.

Except importing the functions, 'autoload' is same as 'load'.

=item load_remote

Loads a specified module to the specified package.

  use Module::Load 'load_remote';

  my $pkg = 'Other::Package';

  load_remote $pkg, 'Data::Dumper'; # load a module to 'Other::Package'
                                    # but do not import 'Dumper' function

A module for loading must be quoted.

Except specifing the package and quoting module name,
'load_remote' is same as 'load'.

=item autoload_remote

Loads a specified module and imports the default functions to the specified package.

  use Module::Load 'autoload_remote';

  my $pkg = 'Other::Package';

  autoload_remote $pkg, 'Data::Dumper'; # load a module to 'Other::Package'
                                        # and imports 'Dumper' function

A module for loading must be quoted.

Except specifing the package and quoting module name,
'autoload_remote' is same as 'load_remote'.

=back

=head1 Rules

All functions have the following rules to decide what it thinks
you want:

=over 4

=item *

If the argument has any characters in it other than those matching
C<\w>, C<:> or C<'>, it must be a file

=item *

If the argument matches only C<[\w:']>, it must be a module

=item *

If the argument matches only C<\w>, it could either be a module or a
file. We will try to find C<file.pm> first in C<@INC> and if that
fails, we will try to find C<file> in @INC.  If both fail, we die with
the respective error messages.

=back

=head1 IMPORTS THE FUNCTIONS

'load' and 'autoload' are imported by default, but 'load_remote' and
'autoload_remote' are not imported.

To use 'load_remote' or 'autoload_remote', specify at 'use'.

=over 4

=item "load","autoload","load_remote","autoload_remote"

Imports the selected functions.

  # imports 'load' and 'autoload' (default)
  use Module::Load;

  # imports 'autoload' only
  use Module::Load 'autoload';

  # imports 'autoload' and 'autoload_remote', but don't import 'load';
  use Module::Load qw/autoload autoload_remote/;

=item 'all'

Imports all the functions.

  use Module::Load 'all'; # imports load, autoload, load_remote, autoload_remote

=item '','none',undef

Not import any functions (C<load> and C<autoload> are not imported).

  use Module::Load '';

  use Module::Load 'none';

  use Module::Load undef;

=back

=head1 Caveats

Because of a bug in perl (#19213), at least in version 5.6.1, we have
to hardcode the path separator for a require on Win32 to be C</>, like
on Unix rather than the Win32 C<\>. Otherwise perl will not read its
own %INC accurately double load files if they are required again, or
in the worst case, core dump.

C<Module::Load> cannot do implicit imports, only explicit imports.
(in other words, you always have to specify explicitly what you wish
to import from a module, even if the functions are in that modules'
C<@EXPORT>)

=head1 SEE ALSO

L<Module::Runtime> provides functions for loading modules,
checking the validity of a module name,
converting a module name to partial C<.pm> path,
and related utility functions.

L<"require" in perlfunc|https://metacpan.org/pod/perlfunc#require>
and
L<"use" in perlfunc|https://metacpan.org/pod/perlfunc#use>.

L<Mojo::Loader> is a "class loader and plugin framework",
and is included in the
L<Mojolicious|https://metacpan.org/release/Mojolicious> distribution.

L<Module::Loader> is a module for finding and loading modules
in a given namespace, inspired by C<Mojo::Loader>.


=head1 ACKNOWLEDGEMENTS

Thanks to Jonas B. Nielsen for making explicit imports work.

=head1 BUG REPORTS

Please report bugs or other issues to E<lt>bug-module-load@rt.cpan.orgE<gt>.

=head1 AUTHOR

This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.

=head1 COPYRIGHT

This library is free software; you may redistribute and/or modify it
under the same terms as Perl itself.

=cut