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