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