Commit | Line | Data |
248f3028 |
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.62'; |
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 ($path !~ /\.par$/i && -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 | lib.pm also checks if directories called $dir/$version and $dir/$version/$archname |
154 | exist and adds these directories to @INC. |
155 | |
156 | The current value of C<$archname> can be found with this command: |
157 | |
158 | perl -V:archname |
159 | |
160 | The corresponding command to get the current value of C<$version> is: |
161 | |
162 | perl -V:version |
163 | |
164 | To avoid memory leaks, all trailing duplicate entries in @INC are |
165 | removed. |
166 | |
167 | =head2 Deleting directories from @INC |
168 | |
169 | You should normally only add directories to @INC. If you need to |
170 | delete directories from @INC take care to only delete those which you |
171 | added yourself or which you are certain are not needed by other modules |
172 | in your script. Other modules may have added directories which they |
173 | need for correct operation. |
174 | |
175 | The C<no lib> statement deletes all instances of each named directory |
176 | from @INC. |
177 | |
178 | For each directory in LIST (called $dir here) the lib module also |
179 | checks to see if a directory called $dir/$archname/auto exists. |
180 | If so the $dir/$archname directory is assumed to be a corresponding |
181 | architecture specific directory and is also deleted from @INC. |
182 | |
183 | =head2 Restoring original @INC |
184 | |
185 | When the lib module is first loaded it records the current value of @INC |
186 | in an array C<@lib::ORIG_INC>. To restore @INC to that value you |
187 | can say |
188 | |
189 | @INC = @lib::ORIG_INC; |
190 | |
191 | =head1 CAVEATS |
192 | |
193 | In order to keep lib.pm small and simple, it only works with Unix |
194 | filepaths. This doesn't mean it only works on Unix, but non-Unix |
195 | users must first translate their file paths to Unix conventions. |
196 | |
197 | # VMS users wanting to put [.stuff.moo] into |
198 | # their @INC would write |
199 | use lib 'stuff/moo'; |
200 | |
201 | =head1 NOTES |
202 | |
203 | In the future, this module will likely use File::Spec for determining |
204 | paths, as it does now for Mac OS (where Unix-style or Mac-style paths |
205 | work, and Unix-style paths are converted properly to Mac-style paths |
206 | before being added to @INC). |
207 | |
208 | If you try to add a file to @INC as follows: |
209 | |
210 | use lib 'this_is_a_file.txt'; |
211 | |
212 | C<lib> will warn about this. The sole exceptions are files with the |
213 | C<.par> extension which are intended to be used as libraries. |
214 | |
215 | =head1 SEE ALSO |
216 | |
217 | FindBin - optional module which deals with paths relative to the source file. |
218 | |
219 | PAR - optional module which can treat C<.par> files as Perl libraries. |
220 | |
221 | =head1 AUTHOR |
222 | |
223 | Tim Bunce, 2nd June 1995. |
224 | |
225 | C<lib> is maintained by the perl5-porters. Please direct |
226 | any questions to the canonical mailing list. Anything that |
227 | is applicable to the CPAN release can be sent to its maintainer, |
228 | though. |
229 | |
230 | Maintainer: The Perl5-Porters <perl5-porters@perl.org> |
231 | |
232 | Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org> |
233 | |
234 | =head1 COPYRIGHT AND LICENSE |
235 | |
236 | This package has been part of the perl core since perl 5.001. |
237 | It has been released separately to CPAN so older installations |
238 | can benefit from bug fixes. |
239 | |
240 | This package has the same copyright and license as the perl core. |
241 | |
242 | =cut |