[Summary view] [Print] [Text view]

   1  package lib;
   2  
   3  # THIS FILE IS AUTOMATICALLY GENERATED FROM lib_pm.PL.
   4  # ANY CHANGES TO THIS FILE WILL BE OVERWRITTEN BY THE NEXT PERL BUILD.
   5  
   6  use Config;
   7  
   8  use strict;
   9  
  10  my $archname         = $Config{archname};
  11  my $version          = $Config{version};
  12  my @inc_version_list = reverse split / /, $Config{inc_version_list};
  13  
  14  
  15  our @ORIG_INC = @INC;    # take a handy copy of 'original' value
  16  our $VERSION = '0.5565';
  17  my $Is_MacOS = $^O eq 'MacOS';
  18  my $Mac_FS;
  19  if ($Is_MacOS) {
  20      require File::Spec;
  21      $Mac_FS = eval { require Mac::FileSpec::Unixish };
  22  }
  23  
  24  sub import {
  25      shift;
  26  
  27      my %names;
  28      foreach (reverse @_) {
  29      my $path = $_;        # we'll be modifying it, so break the alias
  30      if ($path eq '') {
  31          require Carp;
  32          Carp::carp("Empty compile time value given to use lib");
  33      }
  34  
  35      $path = _nativize($path);
  36  
  37      if (-e $path && ! -d _) {
  38          require Carp;
  39          Carp::carp("Parameter to use lib must be directory, not file");
  40      }
  41      unshift(@INC, $path);
  42      # Add any previous version directories we found at configure time
  43      foreach my $incver (@inc_version_list)
  44      {
  45          my $dir = $Is_MacOS
  46          ? File::Spec->catdir( $path, $incver )
  47          : "$path/$incver";
  48          unshift(@INC, $dir) if -d $dir;
  49      }
  50      # Put a corresponding archlib directory in front of $path if it
  51      # looks like $path has an archlib directory below it.
  52      my($arch_auto_dir, $arch_dir, $version_dir, $version_arch_dir)
  53          = _get_dirs($path);
  54      unshift(@INC, $arch_dir)         if -d $arch_auto_dir;
  55      unshift(@INC, $version_dir)      if -d $version_dir;
  56      unshift(@INC, $version_arch_dir) if -d $version_arch_dir;
  57      }
  58  
  59      # remove trailing duplicates
  60      @INC = grep { ++$names{$_} == 1 } @INC;
  61      return;
  62  }
  63  
  64  
  65  sub unimport {
  66      shift;
  67  
  68      my %names;
  69      foreach (@_) {
  70      my $path = _nativize($_);
  71  
  72      my($arch_auto_dir, $arch_dir, $version_dir, $version_arch_dir)
  73          = _get_dirs($path);
  74      ++$names{$path};
  75      ++$names{$arch_dir}         if -d $arch_auto_dir;
  76      ++$names{$version_dir}      if -d $version_dir;
  77      ++$names{$version_arch_dir} if -d $version_arch_dir;
  78      }
  79  
  80      # Remove ALL instances of each named directory.
  81      @INC = grep { !exists $names{$_} } @INC;
  82      return;
  83  }
  84  
  85  sub _get_dirs {
  86      my($dir) = @_;
  87      my($arch_auto_dir, $arch_dir, $version_dir, $version_arch_dir);
  88  
  89      # we could use this for all platforms in the future, but leave it
  90      # Mac-only for now, until there is more time for testing it.
  91      if ($Is_MacOS) {
  92      $arch_auto_dir    = File::Spec->catdir( $dir, $archname, 'auto' );
  93      $arch_dir         = File::Spec->catdir( $dir, $archname, );
  94      $version_dir      = File::Spec->catdir( $dir, $version );
  95      $version_arch_dir = File::Spec->catdir( $dir, $version, $archname );
  96      } else {
  97      $arch_auto_dir    = "$dir/$archname/auto";
  98      $arch_dir         = "$dir/$archname";
  99      $version_dir      = "$dir/$version";
 100      $version_arch_dir = "$dir/$version/$archname";
 101      }
 102      return($arch_auto_dir, $arch_dir, $version_dir, $version_arch_dir);
 103  }
 104  
 105  sub _nativize {
 106      my($dir) = @_;
 107  
 108      if ($Is_MacOS && $Mac_FS && ! -d $dir) {
 109      $dir = Mac::FileSpec::Unixish::nativize($dir);
 110      $dir .= ":" unless $dir =~ /:$/;
 111      }
 112  
 113      return $dir;
 114  }
 115  
 116  1;
 117  __END__
 118  
 119  =head1 NAME
 120  
 121  lib - manipulate @INC at compile time
 122  
 123  =head1 SYNOPSIS
 124  
 125      use lib LIST;
 126  
 127      no lib LIST;
 128  
 129  =head1 DESCRIPTION
 130  
 131  This is a small simple module which simplifies the manipulation of @INC
 132  at compile time.
 133  
 134  It is typically used to add extra directories to perl's search path so
 135  that later C<use> or C<require> statements will find modules which are
 136  not located on perl's default search path.
 137  
 138  =head2 Adding directories to @INC
 139  
 140  The parameters to C<use lib> are added to the start of the perl search
 141  path. Saying
 142  
 143      use lib LIST;
 144  
 145  is I<almost> the same as saying
 146  
 147      BEGIN { unshift(@INC, LIST) }
 148  
 149  For each directory in LIST (called $dir here) the lib module also
 150  checks to see if a directory called $dir/$archname/auto exists.
 151  If so the $dir/$archname directory is assumed to be a corresponding
 152  architecture specific directory and is added to @INC in front of $dir.
 153  
 154  The current value of C<$archname> can be found with this command:
 155  
 156      perl -V:archname
 157  
 158  To avoid memory leaks, all trailing duplicate entries in @INC are
 159  removed.
 160  
 161  =head2 Deleting directories from @INC
 162  
 163  You should normally only add directories to @INC.  If you need to
 164  delete directories from @INC take care to only delete those which you
 165  added yourself or which you are certain are not needed by other modules
 166  in your script.  Other modules may have added directories which they
 167  need for correct operation.
 168  
 169  The C<no lib> statement deletes all instances of each named directory
 170  from @INC.
 171  
 172  For each directory in LIST (called $dir here) the lib module also
 173  checks to see if a directory called $dir/$archname/auto exists.
 174  If so the $dir/$archname directory is assumed to be a corresponding
 175  architecture specific directory and is also deleted from @INC.
 176  
 177  =head2 Restoring original @INC
 178  
 179  When the lib module is first loaded it records the current value of @INC
 180  in an array C<@lib::ORIG_INC>. To restore @INC to that value you
 181  can say
 182  
 183      @INC = @lib::ORIG_INC;
 184  
 185  =head1 CAVEATS
 186  
 187  In order to keep lib.pm small and simple, it only works with Unix
 188  filepaths.  This doesn't mean it only works on Unix, but non-Unix
 189  users must first translate their file paths to Unix conventions.
 190  
 191      # VMS users wanting to put [.stuff.moo] into 
 192      # their @INC would write
 193      use lib 'stuff/moo';
 194  
 195  =head1 NOTES
 196  
 197  In the future, this module will likely use File::Spec for determining
 198  paths, as it does now for Mac OS (where Unix-style or Mac-style paths
 199  work, and Unix-style paths are converted properly to Mac-style paths
 200  before being added to @INC).
 201  
 202  =head1 SEE ALSO
 203  
 204  FindBin - optional module which deals with paths relative to the source file.
 205  
 206  =head1 AUTHOR
 207  
 208  Tim Bunce, 2nd June 1995.
 209  
 210  =cut