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