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