cpan/Module-Load/lib/Module/Load.pm

   1 package Module::Load;
   2
   3 $VERSION = '0.22';
   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