Commit | Line | Data |
---|---|---|
72b16652 GS |
1 | package File::Glob; |
2 | ||
3 | use strict; | |
7f39e0ae | 4 | our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, $DEFAULT_FLAGS); |
72b16652 | 5 | |
da4061d3 | 6 | require XSLoader; |
22bc907a | 7 | use feature 'switch'; |
72b16652 | 8 | |
72f7b9a1 | 9 | @ISA = qw(Exporter); |
72b16652 | 10 | |
00c80938 GS |
11 | # NOTE: The glob() export is only here for compatibility with 5.6.0. |
12 | # csh_glob() should not be used directly, unless you know what you're doing. | |
13 | ||
72b16652 GS |
14 | %EXPORT_TAGS = ( |
15 | 'glob' => [ qw( | |
16 | GLOB_ABEND | |
2d5e9e5d | 17 | GLOB_ALPHASORT |
72b16652 GS |
18 | GLOB_ALTDIRFUNC |
19 | GLOB_BRACE | |
220398a0 | 20 | GLOB_CSH |
72b16652 GS |
21 | GLOB_ERR |
22 | GLOB_ERROR | |
b8ef571c | 23 | GLOB_LIMIT |
72b16652 | 24 | GLOB_MARK |
220398a0 | 25 | GLOB_NOCASE |
72b16652 GS |
26 | GLOB_NOCHECK |
27 | GLOB_NOMAGIC | |
28 | GLOB_NOSORT | |
29 | GLOB_NOSPACE | |
30 | GLOB_QUOTE | |
31 | GLOB_TILDE | |
32 | glob | |
00c80938 | 33 | bsd_glob |
72b16652 GS |
34 | ) ], |
35 | ); | |
36 | ||
aa0c903b NC |
37 | @EXPORT_OK = (@{$EXPORT_TAGS{'glob'}}, 'csh_glob'); |
38 | ||
735631af | 39 | $VERSION = '1.10'; |
220398a0 PM |
40 | |
41 | sub import { | |
7d3fb230 | 42 | require Exporter; |
df5a3819 NC |
43 | local $Exporter::ExportLevel = $Exporter::ExportLevel + 1; |
44 | Exporter::import(grep { | |
45 | my $passthrough; | |
46 | given ($_) { | |
22bc907a NC |
47 | $DEFAULT_FLAGS &= ~GLOB_NOCASE() when ':case'; |
48 | $DEFAULT_FLAGS |= GLOB_NOCASE() when ':nocase'; | |
49 | when (':globally') { | |
50 | no warnings 'redefine'; | |
220398a0 PM |
51 | *CORE::GLOBAL::glob = \&File::Glob::csh_glob; |
52 | } | |
df5a3819 | 53 | $passthrough = 1; |
220398a0 | 54 | } |
df5a3819 NC |
55 | $passthrough; |
56 | } @_); | |
72b16652 GS |
57 | } |
58 | ||
da4061d3 | 59 | XSLoader::load(); |
72b16652 | 60 | |
220398a0 | 61 | $DEFAULT_FLAGS = GLOB_CSH(); |
862f843b | 62 | if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos)$/) { |
220398a0 PM |
63 | $DEFAULT_FLAGS |= GLOB_NOCASE(); |
64 | } | |
65 | ||
00c80938 GS |
66 | # File::Glob::glob() is deprecated because its prototype is different from |
67 | # CORE::glob() (use bsd_glob() instead) | |
68 | sub glob { | |
e0e8a4dc | 69 | splice @_, 1; # don't pass PL_glob_index as flags! |
00c80938 GS |
70 | goto &bsd_glob; |
71 | } | |
72 | ||
72b16652 GS |
73 | ## borrowed heavily from gsar's File::DosGlob |
74 | my %iter; | |
75 | my %entries; | |
76 | ||
77 | sub csh_glob { | |
78 | my $pat = shift; | |
79 | my $cxix = shift; | |
80 | my @pat; | |
81 | ||
82 | # glob without args defaults to $_ | |
83 | $pat = $_ unless defined $pat; | |
84 | ||
85 | # extract patterns | |
be3174d2 GS |
86 | $pat =~ s/^\s+//; # Protect against empty elements in |
87 | $pat =~ s/\s+$//; # things like < *.c> and <*.c >. | |
88 | # These alone shouldn't trigger ParseWords. | |
72b16652 GS |
89 | if ($pat =~ /\s/) { |
90 | # XXX this is needed for compatibility with the csh | |
91 | # implementation in Perl. Need to support a flag | |
92 | # to disable this behavior. | |
93 | require Text::ParseWords; | |
94 | @pat = Text::ParseWords::parse_line('\s+',0,$pat); | |
95 | } | |
96 | ||
97 | # assume global context if not provided one | |
98 | $cxix = '_G_' unless defined $cxix; | |
99 | $iter{$cxix} = 0 unless exists $iter{$cxix}; | |
100 | ||
101 | # if we're just beginning, do it all first | |
102 | if ($iter{$cxix} == 0) { | |
103 | if (@pat) { | |
220398a0 | 104 | $entries{$cxix} = [ map { doglob($_, $DEFAULT_FLAGS) } @pat ]; |
72b16652 GS |
105 | } |
106 | else { | |
220398a0 | 107 | $entries{$cxix} = [ doglob($pat, $DEFAULT_FLAGS) ]; |
72b16652 GS |
108 | } |
109 | } | |
110 | ||
111 | # chuck it all out, quick or slow | |
112 | if (wantarray) { | |
113 | delete $iter{$cxix}; | |
114 | return @{delete $entries{$cxix}}; | |
115 | } | |
116 | else { | |
117 | if ($iter{$cxix} = scalar @{$entries{$cxix}}) { | |
118 | return shift @{$entries{$cxix}}; | |
119 | } | |
120 | else { | |
121 | # return undef for EOL | |
122 | delete $iter{$cxix}; | |
123 | delete $entries{$cxix}; | |
124 | return undef; | |
125 | } | |
126 | } | |
127 | } | |
128 | ||
129 | 1; | |
130 | __END__ | |
131 | ||
132 | =head1 NAME | |
133 | ||
134 | File::Glob - Perl extension for BSD glob routine | |
135 | ||
136 | =head1 SYNOPSIS | |
137 | ||
138 | use File::Glob ':glob'; | |
9d70ac1b | 139 | |
00c80938 GS |
140 | @list = bsd_glob('*.[ch]'); |
141 | $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR); | |
9d70ac1b | 142 | |
72b16652 GS |
143 | if (GLOB_ERROR) { |
144 | # an error occurred reading $homedir | |
145 | } | |
146 | ||
00c80938 | 147 | ## override the core glob (CORE::glob() does this automatically |
11fe14b1 | 148 | ## by default anyway, since v5.6.0) |
220398a0 | 149 | use File::Glob ':globally'; |
6bd08436 | 150 | my @sources = <*.{c,h,y}>; |
220398a0 PM |
151 | |
152 | ## override the core glob, forcing case sensitivity | |
153 | use File::Glob qw(:globally :case); | |
6bd08436 | 154 | my @sources = <*.{c,h,y}>; |
220398a0 PM |
155 | |
156 | ## override the core glob forcing case insensitivity | |
157 | use File::Glob qw(:globally :nocase); | |
6bd08436 | 158 | my @sources = <*.{c,h,y}>; |
9d70ac1b | 159 | |
6bd08436 SS |
160 | ## glob on all files in home directory |
161 | use File::Glob ':globally'; | |
162 | my @sources = <~gnat/*>; | |
72b16652 GS |
163 | |
164 | =head1 DESCRIPTION | |
165 | ||
9d70ac1b RGS |
166 | The glob angle-bracket operator C<< <> >> is a pathname generator that |
167 | implements the rules for file name pattern matching used by Unix-like shells | |
168 | such as the Bourne shell or C shell. | |
6bd08436 | 169 | |
00c80938 GS |
170 | File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is |
171 | a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). | |
172 | bsd_glob() takes a mandatory C<pattern> argument, and an optional | |
72b16652 GS |
173 | C<flags> argument, and returns a list of filenames matching the |
174 | pattern, with interpretation of the pattern modified by the C<flags> | |
00c80938 GS |
175 | variable. |
176 | ||
177 | Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). | |
178 | Note that they don't share the same prototype--CORE::glob() only accepts | |
179 | a single argument. Due to historical reasons, CORE::glob() will also | |
180 | split its argument on whitespace, treating it as multiple patterns, | |
181 | whereas bsd_glob() considers them as one pattern. | |
182 | ||
6bd08436 SS |
183 | =head2 META CHARACTERS |
184 | ||
9d70ac1b RGS |
185 | \ Quote the next metacharacter |
186 | [] Character class | |
187 | {} Multiple pattern | |
188 | * Match any string of characters | |
189 | ? Match any single character | |
190 | ~ User name home directory | |
191 | ||
192 | The metanotation C<a{b,c,d}e> is a shorthand for C<abe ace ade>. Left to | |
193 | right order is preserved, with results of matches being sorted separately | |
194 | at a low level to preserve this order. As a special case C<{>, C<}>, and | |
195 | C<{}> are passed undisturbed. | |
6bd08436 SS |
196 | |
197 | =head2 POSIX FLAGS | |
198 | ||
00c80938 | 199 | The POSIX defined flags for bsd_glob() are: |
72b16652 GS |
200 | |
201 | =over 4 | |
202 | ||
203 | =item C<GLOB_ERR> | |
204 | ||
00c80938 GS |
205 | Force bsd_glob() to return an error when it encounters a directory it |
206 | cannot open or read. Ordinarily bsd_glob() continues to find matches. | |
72b16652 | 207 | |
b8ef571c JH |
208 | =item C<GLOB_LIMIT> |
209 | ||
210 | Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern expands | |
211 | to a size bigger than the system constant C<ARG_MAX> (usually found in | |
212 | limits.h). If your system does not define this constant, bsd_glob() uses | |
213 | C<sysconf(_SC_ARG_MAX)> or C<_POSIX_ARG_MAX> where available (in that | |
214 | order). You can inspect these values using the standard C<POSIX> | |
215 | extension. | |
216 | ||
72b16652 GS |
217 | =item C<GLOB_MARK> |
218 | ||
219 | Each pathname that is a directory that matches the pattern has a slash | |
220 | appended. | |
221 | ||
220398a0 PM |
222 | =item C<GLOB_NOCASE> |
223 | ||
224 | By default, file names are assumed to be case sensitive; this flag | |
00c80938 | 225 | makes bsd_glob() treat case differences as not significant. |
220398a0 | 226 | |
72b16652 GS |
227 | =item C<GLOB_NOCHECK> |
228 | ||
00c80938 | 229 | If the pattern does not match any pathname, then bsd_glob() returns a list |
72b16652 GS |
230 | consisting of only the pattern. If C<GLOB_QUOTE> is set, its effect |
231 | is present in the pattern returned. | |
232 | ||
233 | =item C<GLOB_NOSORT> | |
234 | ||
235 | By default, the pathnames are sorted in ascending ASCII order; this | |
00c80938 | 236 | flag prevents that sorting (speeding up bsd_glob()). |
72b16652 GS |
237 | |
238 | =back | |
239 | ||
240 | The FreeBSD extensions to the POSIX standard are the following flags: | |
241 | ||
242 | =over 4 | |
243 | ||
244 | =item C<GLOB_BRACE> | |
245 | ||
a45bd81d | 246 | Pre-process the string to expand C<{pat,pat,...}> strings like csh(1). |
72b16652 GS |
247 | The pattern '{}' is left unexpanded for historical reasons (and csh(1) |
248 | does the same thing to ease typing of find(1) patterns). | |
249 | ||
250 | =item C<GLOB_NOMAGIC> | |
251 | ||
252 | Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not | |
253 | contain any of the special characters "*", "?" or "[". C<NOMAGIC> is | |
254 | provided to simplify implementing the historic csh(1) globbing | |
255 | behaviour and should probably not be used anywhere else. | |
256 | ||
257 | =item C<GLOB_QUOTE> | |
258 | ||
259 | Use the backslash ('\') character for quoting: every occurrence of a | |
260 | backslash followed by a character in the pattern is replaced by that | |
261 | character, avoiding any special interpretation of the character. | |
220398a0 | 262 | (But see below for exceptions on DOSISH systems). |
72b16652 GS |
263 | |
264 | =item C<GLOB_TILDE> | |
265 | ||
266 | Expand patterns that start with '~' to user name home directories. | |
267 | ||
268 | =item C<GLOB_CSH> | |
269 | ||
270 | For convenience, C<GLOB_CSH> is a synonym for | |
2d5e9e5d | 271 | C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT>. |
72b16652 GS |
272 | |
273 | =back | |
274 | ||
275 | The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD | |
276 | extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been | |
277 | implemented in the Perl version because they involve more complex | |
278 | interaction with the underlying C structures. | |
279 | ||
2d5e9e5d JH |
280 | The following flag has been added in the Perl implementation for |
281 | csh compatibility: | |
282 | ||
283 | =over 4 | |
284 | ||
285 | =item C<GLOB_ALPHASORT> | |
286 | ||
287 | If C<GLOB_NOSORT> is not in effect, sort filenames is alphabetical | |
288 | order (case does not matter) rather than in ASCII order. | |
289 | ||
290 | =back | |
291 | ||
72b16652 GS |
292 | =head1 DIAGNOSTICS |
293 | ||
00c80938 | 294 | bsd_glob() returns a list of matching paths, possibly zero length. If an |
72b16652 GS |
295 | error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be |
296 | set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred, | |
297 | or one of the following values otherwise: | |
298 | ||
299 | =over 4 | |
300 | ||
301 | =item C<GLOB_NOSPACE> | |
302 | ||
303 | An attempt to allocate memory failed. | |
304 | ||
305 | =item C<GLOB_ABEND> | |
306 | ||
307 | The glob was stopped because an error was encountered. | |
308 | ||
309 | =back | |
310 | ||
00c80938 GS |
311 | In the case where bsd_glob() has found some matching paths, but is |
312 | interrupted by an error, it will return a list of filenames B<and> | |
72b16652 GS |
313 | set &File::Glob::ERROR. |
314 | ||
00c80938 GS |
315 | Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour |
316 | by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will | |
72b16652 GS |
317 | continue processing despite those errors, unless the C<GLOB_ERR> flag is |
318 | set. | |
319 | ||
320 | Be aware that all filenames returned from File::Glob are tainted. | |
321 | ||
322 | =head1 NOTES | |
323 | ||
324 | =over 4 | |
325 | ||
326 | =item * | |
327 | ||
9d70ac1b RGS |
328 | If you want to use multiple patterns, e.g. C<bsd_glob("a* b*")>, you should |
329 | probably throw them in a set as in C<bsd_glob("{a*,b*}")>. This is because | |
150b260b GS |
330 | the argument to bsd_glob() isn't subjected to parsing by the C shell. |
331 | Remember that you can use a backslash to escape things. | |
72b16652 GS |
332 | |
333 | =item * | |
334 | ||
220398a0 PM |
335 | On DOSISH systems, backslash is a valid directory separator character. |
336 | In this case, use of backslash as a quoting character (via GLOB_QUOTE) | |
337 | interferes with the use of backslash as a directory separator. The | |
338 | best (simplest, most portable) solution is to use forward slashes for | |
339 | directory separators, and backslashes for quoting. However, this does | |
340 | not match "normal practice" on these systems. As a concession to user | |
341 | expectation, therefore, backslashes (under GLOB_QUOTE) only quote the | |
342 | glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself. | |
343 | All other backslashes are passed through unchanged. | |
344 | ||
345 | =item * | |
346 | ||
72b16652 GS |
347 | Win32 users should use the real slash. If you really want to use |
348 | backslashes, consider using Sarathy's File::DosGlob, which comes with | |
349 | the standard Perl distribution. | |
350 | ||
7369a524 CN |
351 | =item * |
352 | ||
353 | Mac OS (Classic) users should note a few differences. Since | |
354 | Mac OS is not Unix, when the glob code encounters a tilde glob (e.g. | |
be708cc0 | 355 | ~user) and the C<GLOB_TILDE> flag is used, it simply returns that |
7369a524 CN |
356 | pattern without doing any expansion. |
357 | ||
358 | Glob on Mac OS is case-insensitive by default (if you don't use any | |
359 | flags). If you specify any flags at all and still want glob | |
360 | to be case-insensitive, you must include C<GLOB_NOCASE> in the flags. | |
361 | ||
362 | The path separator is ':' (aka colon), not '/' (aka slash). Mac OS users | |
363 | should be careful about specifying relative pathnames. While a full path | |
364 | always begins with a volume name, a relative pathname should always | |
365 | begin with a ':'. If specifying a volume name only, a trailing ':' is | |
366 | required. | |
367 | ||
be708cc0 JH |
368 | The specification of pathnames in glob patterns adheres to the usual Mac |
369 | OS conventions: The path separator is a colon ':', not a slash '/'. A | |
370 | full path always begins with a volume name. A relative pathname on Mac | |
371 | OS must always begin with a ':', except when specifying a file or | |
372 | directory name in the current working directory, where the leading colon | |
373 | is optional. If specifying a volume name only, a trailing ':' is | |
374 | required. Due to these rules, a glob like E<lt>*:E<gt> will find all | |
375 | mounted volumes, while a glob like E<lt>*E<gt> or E<lt>:*E<gt> will find | |
376 | all files and directories in the current directory. | |
377 | ||
378 | Note that updirs in the glob pattern are resolved before the matching begins, | |
379 | i.e. a pattern like "*HD:t?p::a*" will be matched as "*HD:a*". Note also, | |
380 | that a single trailing ':' in the pattern is ignored (unless it's a volume | |
381 | name pattern like "*HD:"), i.e. a glob like E<lt>:*:E<gt> will find both | |
382 | directories I<and> files (and not, as one might expect, only directories). | |
383 | You can, however, use the C<GLOB_MARK> flag to distinguish (without a file | |
384 | test) directory names from file names. | |
385 | ||
386 | If the C<GLOB_MARK> flag is set, all directory paths will have a ':' appended. | |
387 | Since a directory like 'lib:' is I<not> a valid I<relative> path on Mac OS, | |
388 | both a leading and a trailing colon will be added, when the directory name in | |
389 | question doesn't contain any colons (e.g. 'lib' becomes ':lib:'). | |
390 | ||
a45bd81d GS |
391 | =back |
392 | ||
6bd08436 SS |
393 | =head1 SEE ALSO |
394 | ||
395 | L<perlfunc/glob>, glob(3) | |
396 | ||
72b16652 GS |
397 | =head1 AUTHOR |
398 | ||
0e950d83 | 399 | The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>, |
72b16652 | 400 | and is released under the artistic license. Further modifications were |
7369a524 CN |
401 | made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy |
402 | E<lt>gsar@activestate.comE<gt>, and Thomas Wegner | |
403 | E<lt>wegner_thomas@yahoo.comE<gt>. The C glob code has the | |
72b16652 GS |
404 | following copyright: |
405 | ||
0e950d83 GS |
406 | Copyright (c) 1989, 1993 The Regents of the University of California. |
407 | All rights reserved. | |
3cb6de81 | 408 | |
0e950d83 GS |
409 | This code is derived from software contributed to Berkeley by |
410 | Guido van Rossum. | |
411 | ||
412 | Redistribution and use in source and binary forms, with or without | |
413 | modification, are permitted provided that the following conditions | |
414 | are met: | |
415 | ||
416 | 1. Redistributions of source code must retain the above copyright | |
417 | notice, this list of conditions and the following disclaimer. | |
418 | 2. Redistributions in binary form must reproduce the above copyright | |
419 | notice, this list of conditions and the following disclaimer in the | |
420 | documentation and/or other materials provided with the distribution. | |
421 | 3. Neither the name of the University nor the names of its contributors | |
422 | may be used to endorse or promote products derived from this software | |
423 | without specific prior written permission. | |
424 | ||
425 | THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
426 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
427 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
428 | ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
429 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
430 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
431 | OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
432 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
433 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
434 | OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
435 | SUCH DAMAGE. | |
72b16652 GS |
436 | |
437 | =cut |