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