Commit | Line | Data |
---|---|---|
e50aee73 AD |
1 | package lib; |
2 | ||
774d564b | 3 | use vars qw(@ORIG_INC); |
4633a7c4 LW |
4 | use Config; |
5 | ||
6 | my $archname = $Config{'archname'}; | |
7 | ||
e50aee73 AD |
8 | @ORIG_INC = @INC; # take a handy copy of 'original' value |
9 | ||
10 | ||
11 | sub import { | |
12 | shift; | |
aeb5d71d GS |
13 | |
14 | my %names; | |
a5f75d66 | 15 | foreach (reverse @_) { |
016609bc | 16 | if ($_ eq '') { |
af3dad46 | 17 | require Carp; |
774d564b | 18 | Carp::carp("Empty compile time value given to use lib"); |
af3dad46 | 19 | } |
20408e3c GS |
20 | if (-e && ! -d _) { |
21 | require Carp; | |
22 | Carp::carp("Parameter to use lib must be directory, not file"); | |
23 | } | |
4633a7c4 LW |
24 | unshift(@INC, $_); |
25 | # Put a corresponding archlib directory infront of $_ if it | |
26 | # looks like $_ has an archlib directory below it. | |
774d564b | 27 | if (-d "$_/$archname") { |
28 | unshift(@INC, "$_/$archname") if -d "$_/$archname/auto"; | |
29 | unshift(@INC, "$_/$archname/$]") if -d "$_/$archname/$]/auto"; | |
30 | } | |
4633a7c4 | 31 | } |
abef537a GS |
32 | |
33 | # remove trailing duplicates | |
34 | @INC = grep { ++$names{$_} == 1 } @INC; | |
35 | return; | |
e50aee73 AD |
36 | } |
37 | ||
38 | ||
39 | sub unimport { | |
40 | shift; | |
e50aee73 AD |
41 | |
42 | my %names; | |
aeb5d71d | 43 | foreach (@_) { |
4633a7c4 LW |
44 | ++$names{$_}; |
45 | ++$names{"$_/$archname"} if -d "$_/$archname/auto"; | |
46 | } | |
e50aee73 | 47 | |
aeb5d71d GS |
48 | # Remove ALL instances of each named directory. |
49 | @INC = grep { !exists $names{$_} } @INC; | |
abef537a | 50 | return; |
e50aee73 AD |
51 | } |
52 | ||
4633a7c4 | 53 | 1; |
e50aee73 AD |
54 | __END__ |
55 | ||
56 | =head1 NAME | |
57 | ||
58 | lib - manipulate @INC at compile time | |
59 | ||
60 | =head1 SYNOPSIS | |
61 | ||
62 | use lib LIST; | |
63 | ||
64 | no lib LIST; | |
65 | ||
66 | =head1 DESCRIPTION | |
67 | ||
68 | This is a small simple module which simplifies the manipulation of @INC | |
69 | at compile time. | |
70 | ||
71 | It is typically used to add extra directories to perl's search path so | |
72 | that later C<use> or C<require> statements will find modules which are | |
73 | not located on perl's default search path. | |
74 | ||
aeb5d71d | 75 | =head2 Adding directories to @INC |
e50aee73 AD |
76 | |
77 | The parameters to C<use lib> are added to the start of the perl search | |
78 | path. Saying | |
79 | ||
80 | use lib LIST; | |
81 | ||
4633a7c4 | 82 | is I<almost> the same as saying |
e50aee73 AD |
83 | |
84 | BEGIN { unshift(@INC, LIST) } | |
85 | ||
4633a7c4 LW |
86 | For each directory in LIST (called $dir here) the lib module also |
87 | checks to see if a directory called $dir/$archname/auto exists. | |
88 | If so the $dir/$archname directory is assumed to be a corresponding | |
89 | architecture specific directory and is added to @INC in front of $dir. | |
90 | ||
aeb5d71d GS |
91 | To avoid memory leaks, all trailing duplicate entries in @INC are |
92 | removed. | |
4633a7c4 | 93 | |
aeb5d71d | 94 | =head2 Deleting directories from @INC |
e50aee73 AD |
95 | |
96 | You should normally only add directories to @INC. If you need to | |
97 | delete directories from @INC take care to only delete those which you | |
98 | added yourself or which you are certain are not needed by other modules | |
99 | in your script. Other modules may have added directories which they | |
100 | need for correct operation. | |
101 | ||
aeb5d71d GS |
102 | The C<no lib> statement deletes all instances of each named directory |
103 | from @INC. | |
e50aee73 | 104 | |
4633a7c4 LW |
105 | For each directory in LIST (called $dir here) the lib module also |
106 | checks to see if a directory called $dir/$archname/auto exists. | |
107 | If so the $dir/$archname directory is assumed to be a corresponding | |
108 | architecture specific directory and is also deleted from @INC. | |
109 | ||
aeb5d71d | 110 | =head2 Restoring original @INC |
e50aee73 AD |
111 | |
112 | When the lib module is first loaded it records the current value of @INC | |
113 | in an array C<@lib::ORIG_INC>. To restore @INC to that value you | |
4633a7c4 | 114 | can say |
e50aee73 AD |
115 | |
116 | @INC = @lib::ORIG_INC; | |
117 | ||
e50aee73 AD |
118 | |
119 | =head1 SEE ALSO | |
120 | ||
af3dad46 | 121 | FindBin - optional module which deals with paths relative to the source file. |
e50aee73 AD |
122 | |
123 | =head1 AUTHOR | |
124 | ||
125 | Tim Bunce, 2nd June 1995. | |
126 | ||
127 | =cut |