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