Commit | Line | Data |
0819efc5 |
1 | package Module::Load; |
2 | |
3 | $VERSION = '0.10'; |
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; |
59 | |
60 | return $file; |
61 | } |
62 | |
63 | sub _who { (caller(1))[0] } |
64 | |
65 | sub _is_file { |
66 | local $_ = shift; |
67 | return /^\./ ? 1 : |
68 | /[^\w:']/ ? 1 : |
69 | undef |
70 | #' silly bbedit.. |
71 | } |
72 | |
73 | |
74 | 1; |
75 | |
76 | __END__ |
77 | |
78 | =pod |
79 | |
80 | =head1 NAME |
81 | |
82 | Module::Load - runtime require of both modules and files |
83 | |
84 | =head1 SYNOPSIS |
85 | |
86 | use Module::Load; |
87 | |
88 | my $module = 'Data:Dumper'; |
89 | load Data::Dumper; # loads that module |
90 | load 'Data::Dumper'; # ditto |
91 | load $module # tritto |
92 | |
93 | my $script = 'some/script.pl' |
94 | load $script; |
95 | load 'some/script.pl'; # use quotes because of punctuations |
96 | |
97 | load thing; # try 'thing' first, then 'thing.pm' |
98 | |
99 | load CGI, ':standard' # like 'use CGI qw[:standard]' |
100 | |
101 | |
102 | =head1 DESCRIPTION |
103 | |
104 | C<load> eliminates the need to know whether you are trying to require |
105 | either a file or a module. |
106 | |
107 | If you consult C<perldoc -f require> you will see that C<require> will |
108 | behave differently when given a bareword or a string. |
109 | |
110 | In the case of a string, C<require> assumes you are wanting to load a |
111 | file. But in the case of a bareword, it assumes you mean a module. |
112 | |
113 | This gives nasty overhead when you are trying to dynamically require |
114 | modules at runtime, since you will need to change the module notation |
115 | (C<Acme::Comment>) to a file notation fitting the particular platform |
116 | you are on. |
117 | |
118 | C<load> eliminates the need for this overhead and will just DWYM. |
119 | |
120 | =head1 Rules |
121 | |
122 | C<load> has the following rules to decide what it thinks you want: |
123 | |
124 | =over 4 |
125 | |
126 | =item * |
127 | |
128 | If the argument has any characters in it other than those matching |
129 | C<\w>, C<:> or C<'>, it must be a file |
130 | |
131 | =item * |
132 | |
133 | If the argument matches only C<[\w:']>, it must be a module |
134 | |
135 | =item * |
136 | |
137 | If the argument matches only C<\w>, it could either be a module or a |
138 | file. We will try to find C<file> first in C<@INC> and if that fails, |
139 | we will try to find C<file.pm> in @INC. |
140 | If both fail, we die with the respective error messages. |
141 | |
142 | =back |
143 | |
144 | =head1 Caveats |
145 | |
146 | Because of a bug in perl (#19213), at least in version 5.6.1, we have |
147 | to hardcode the path separator for a require on Win32 to be C</>, like |
148 | on Unix rather than the Win32 C<\>. Otherwise perl will not read its |
149 | own %INC accurately double load files if they are required again, or |
150 | in the worst case, core dump. |
151 | |
152 | C<Module::Load> cannot do implicit imports, only explicit imports. |
153 | (in other words, you always have to specify explicitly what you wish |
154 | to import from a module, even if the functions are in that modules' |
155 | C<@EXPORT>) |
156 | |
157 | =head1 AUTHOR |
158 | |
159 | This module by Jos Boumans E<lt>kane@cpan.orgE<gt>. |
160 | |
161 | Thanks to Jonas B. Nielsen for making explicit imports work. |
162 | |
163 | =head1 COPYRIGHT |
164 | |
165 | This module is |
166 | copyright (c) 2002 Jos Boumans E<lt>kane@cpan.orgE<gt>. |
167 | All rights reserved. |
168 | |
169 | This library is free software; |
170 | you may redistribute and/or modify it under the same |
171 | terms as Perl itself. |
172 | |
173 | =cut |