home *** CD-ROM | disk | FTP | other *** search
/ PC World 2004 November / PCWorld_2004-11_cd.bin / software / topware / activeperl / ActivePerl-5.8.4.810-MSWin32-x86.exe / ActivePerl-5.8.4.810 / Perl / lib / lib.pm < prev    next >
Text File  |  2004-06-01  |  6KB  |  207 lines
  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. To avoid memory leaks, all trailing duplicate entries in @INC are
  155. removed.
  156.  
  157. =head2 Deleting directories from @INC
  158.  
  159. You should normally only add directories to @INC.  If you need to
  160. delete directories from @INC take care to only delete those which you
  161. added yourself or which you are certain are not needed by other modules
  162. in your script.  Other modules may have added directories which they
  163. need for correct operation.
  164.  
  165. The C<no lib> statement deletes all instances of each named directory
  166. from @INC.
  167.  
  168. For each directory in LIST (called $dir here) the lib module also
  169. checks to see if a directory called $dir/$archname/auto exists.
  170. If so the $dir/$archname directory is assumed to be a corresponding
  171. architecture specific directory and is also deleted from @INC.
  172.  
  173. =head2 Restoring original @INC
  174.  
  175. When the lib module is first loaded it records the current value of @INC
  176. in an array C<@lib::ORIG_INC>. To restore @INC to that value you
  177. can say
  178.  
  179.     @INC = @lib::ORIG_INC;
  180.  
  181. =head1 CAVEATS
  182.  
  183. In order to keep lib.pm small and simple, it only works with Unix
  184. filepaths.  This doesn't mean it only works on Unix, but non-Unix
  185. users must first translate their file paths to Unix conventions.
  186.  
  187.     # VMS users wanting to put [.stuff.moo] into 
  188.     # their @INC would write
  189.     use lib 'stuff/moo';
  190.  
  191. =head1 NOTES
  192.  
  193. In the future, this module will likely use File::Spec for determining
  194. paths, as it does now for Mac OS (where Unix-style or Mac-style paths
  195. work, and Unix-style paths are converted properly to Mac-style paths
  196. before being added to @INC).
  197.  
  198. =head1 SEE ALSO
  199.  
  200. FindBin - optional module which deals with paths relative to the source file.
  201.  
  202. =head1 AUTHOR
  203.  
  204. Tim Bunce, 2nd June 1995.
  205.  
  206. =cut
  207.