This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Module-Load to CPAN version 0.24
[perl5.git] / cpan / Module-Load / lib / Module / Load.pm
1 package Module::Load;
2
3 $VERSION = '0.24';
4
5 use strict;
6 use File::Spec ();
7
8 sub import {
9     my $who = _who();
10
11     {   no strict 'refs';
12         *{"${who}::load"} = *load;
13     }
14 }
15
16 sub load (*;@)  {
17     my $mod = shift or return;
18     my $who = _who();
19
20     if( _is_file( $mod ) ) {
21         require $mod;
22     } else {
23         LOAD: {
24             my $err;
25             for my $flag ( qw[1 0] ) {
26                 my $file = _to_file( $mod, $flag);
27                 eval { require $file };
28                 $@ ? $err .= $@ : last LOAD;
29             }
30             die $err if $err;
31         }
32     }
33
34     ### This addresses #41883: Module::Load cannot import
35     ### non-Exporter module. ->import() routines weren't
36     ### properly called when load() was used.
37     {   no strict 'refs';
38         my $import;
39         if (@_ and $import = $mod->can('import')) {
40             unshift @_, $mod;
41             goto &$import;
42         }
43     }
44 }
45
46 sub _to_file{
47     local $_    = shift;
48     my $pm      = shift || '';
49
50     ## trailing blanks ignored by default. [rt #69886]
51     my @parts = split /::|'/, $_, -1;
52     ## make sure that we can't hop out of @INC
53     shift @parts if @parts && !$parts[0];
54
55     ### because of [perl #19213], see caveats ###
56     my $file = $^O eq 'MSWin32'
57                     ? join "/", @parts
58                     : File::Spec->catfile( @parts );
59
60     $file   .= '.pm' if $pm;
61
62     ### on perl's before 5.10 (5.9.5@31746) if you require
63     ### a file in VMS format, it's stored in %INC in VMS
64     ### format. Therefor, better unixify it first
65     ### Patch in reply to John Malmbergs patch (as mentioned
66     ### above) on p5p Tue 21 Aug 2007 04:55:07
67     $file = VMS::Filespec::unixify($file) if $^O eq 'VMS';
68
69     return $file;
70 }
71
72 sub _who { (caller(1))[0] }
73
74 sub _is_file {
75     local $_ = shift;
76     return  /^\./               ? 1 :
77             /[^\w:']/           ? 1 :
78             undef
79     #' silly bbedit..
80 }
81
82
83 1;
84
85 __END__
86
87 =pod
88
89 =head1 NAME
90
91 Module::Load - runtime require of both modules and files
92
93 =head1 SYNOPSIS
94
95         use Module::Load;
96
97     my $module = 'Data:Dumper';
98     load Data::Dumper;      # loads that module
99     load 'Data::Dumper';    # ditto
100     load $module            # tritto
101
102     my $script = 'some/script.pl'
103     load $script;
104     load 'some/script.pl';      # use quotes because of punctuations
105
106     load thing;             # try 'thing' first, then 'thing.pm'
107
108     load CGI, ':standard'   # like 'use CGI qw[:standard]'
109
110
111 =head1 DESCRIPTION
112
113 C<load> eliminates the need to know whether you are trying to require
114 either a file or a module.
115
116 If you consult C<perldoc -f require> you will see that C<require> will
117 behave differently when given a bareword or a string.
118
119 In the case of a string, C<require> assumes you are wanting to load a
120 file. But in the case of a bareword, it assumes you mean a module.
121
122 This gives nasty overhead when you are trying to dynamically require
123 modules at runtime, since you will need to change the module notation
124 (C<Acme::Comment>) to a file notation fitting the particular platform
125 you are on.
126
127 C<load> eliminates the need for this overhead and will just DWYM.
128
129 =head1 Rules
130
131 C<load> has the following rules to decide what it thinks you want:
132
133 =over 4
134
135 =item *
136
137 If the argument has any characters in it other than those matching
138 C<\w>, C<:> or C<'>, it must be a file
139
140 =item *
141
142 If the argument matches only C<[\w:']>, it must be a module
143
144 =item *
145
146 If the argument matches only C<\w>, it could either be a module or a
147 file. We will try to find C<file.pm> first in C<@INC> and if that
148 fails, we will try to find C<file> in @INC.  If both fail, we die with
149 the respective error messages.
150
151 =back
152
153 =head1 Caveats
154
155 Because of a bug in perl (#19213), at least in version 5.6.1, we have
156 to hardcode the path separator for a require on Win32 to be C</>, like
157 on Unix rather than the Win32 C<\>. Otherwise perl will not read its
158 own %INC accurately double load files if they are required again, or
159 in the worst case, core dump.
160
161 C<Module::Load> cannot do implicit imports, only explicit imports.
162 (in other words, you always have to specify explicitly what you wish
163 to import from a module, even if the functions are in that modules'
164 C<@EXPORT>)
165
166 =head1 ACKNOWLEDGEMENTS
167
168 Thanks to Jonas B. Nielsen for making explicit imports work.
169
170 =head1 BUG REPORTS
171
172 Please report bugs or other issues to E<lt>bug-module-load@rt.cpan.org<gt>.
173
174 =head1 AUTHOR
175
176 This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
177
178 =head1 COPYRIGHT
179
180 This library is free software; you may redistribute and/or modify it
181 under the same terms as Perl itself.
182
183
184 =cut