lib/lib.pm

   1 package lib;
   2
   3 @ORIG_INC = ();         # (avoid typo warning)
   4 @ORIG_INC = @INC;       # take a handy copy of 'original' value
   5
   6
   7 sub import {
   8     shift;
   9     unshift(@INC, @_);
  10 }
  11
  12
  13 sub unimport {
  14     shift;
  15     my $mode = shift if $_[0] =~ m/^:[A-Z]+/;
  16
  17     my %names;
  18     foreach(@_) { ++$names{$_} };
  19
  20     if ($mode and $mode eq ':ALL') {
  21         # Remove ALL instances of each named directory.
  22         @INC = grep { !exists $names{$_} } @INC;
  23     } else {
  24         # Remove INITIAL instance(s) of each named directory.
  25         @INC = grep { --$names{$_} < 0   } @INC;
  26     }
  27 }
  28
  29 __END__
  30
  31 =head1 NAME
  32
  33 lib - manipulate @INC at compile time
  34
  35 =head1 SYNOPSIS
  36
  37     use lib LIST;
  38
  39     no lib LIST;
  40
  41 =head1 DESCRIPTION
  42
  43 This is a small simple module which simplifies the manipulation of @INC
  44 at compile time.
  45
  46 It is typically used to add extra directories to perl's search path so
  47 that later C<use> or C<require> statements will find modules which are
  48 not located on perl's default search path.
  49
  50
  51 =head2 ADDING DIRECTORIES TO @INC
  52
  53 The parameters to C<use lib> are added to the start of the perl search
  54 path. Saying
  55
  56     use lib LIST;
  57
  58 is the same as saying
  59
  60     BEGIN { unshift(@INC, LIST) }
  61
  62
  63 =head2 DELETING DIRECTORIES FROM @INC
  64
  65 You should normally only add directories to @INC.  If you need to
  66 delete directories from @INC take care to only delete those which you
  67 added yourself or which you are certain are not needed by other modules
  68 in your script.  Other modules may have added directories which they
  69 need for correct operation.
  70
  71 By default the C<no lib> statement deletes the I<first> instance of
  72 each named directory from @INC.  To delete multiple instances of the
  73 same name from @INC you can specify the name multiple times.
  74
  75 To delete I<all> instances of I<all> the specified names from @INC you can
  76 specify ':ALL' as the first parameter of C<no lib>. For example:
  77
  78     no lib qw(:ALL .);
  79
  80
  81 =head2 RESTORING ORIGINAL @INC
  82
  83 When the lib module is first loaded it records the current value of @INC
  84 in an array C<@lib::ORIG_INC>. To restore @INC to that value you
  85 can say either
  86
  87     @INC = @lib::ORIG_INC;
  88
  89 or
  90
  91     no  lib @INC;
  92     use lib @lib::ORIG_INC;
  93
  94 =head1 SEE ALSO
  95
  96 AddINC - optional module which deals with paths relative to the source file.
  97
  98 =head1 AUTHOR
  99
 100 Tim Bunce, 2nd June 1995.
 101
 102 =cut
 103