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