lib/Module/Load.pm

   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