[Summary view] [Print] [Text view]

   1  package Module::Load;
   2  
   3  $VERSION = '0.12';
   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      ### 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';
  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  
 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  
 172  =head1 AUTHOR
 173  
 174  This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
 175  
 176  =head1 COPYRIGHT
 177  
 178  This library is free software; you may redistribute and/or modify it 
 179  under the same terms as Perl itself.
 180  
 181  
 182  =cut