Commit | Line | Data |
---|---|---|
72b16652 GS |
1 | package File::Glob; |
2 | ||
3 | use strict; | |
7f39e0ae | 4 | our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, $DEFAULT_FLAGS); |
72b16652 | 5 | |
da4061d3 | 6 | require 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 | |
df8b709b | 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 |
72b16652 GS |
32 | ) ], |
33 | ); | |
f4cbf990 | 34 | $EXPORT_TAGS{bsd_glob} = [@{$EXPORT_TAGS{glob}}]; |
72b16652 | 35 | |
aa0c903b NC |
36 | @EXPORT_OK = (@{$EXPORT_TAGS{'glob'}}, 'csh_glob'); |
37 | ||
df8b709b | 38 | $VERSION = '1.32'; |
220398a0 PM |
39 | |
40 | sub import { | |
7d3fb230 | 41 | require Exporter; |
df5a3819 NC |
42 | local $Exporter::ExportLevel = $Exporter::ExportLevel + 1; |
43 | Exporter::import(grep { | |
44bda135 BF |
44 | my $passthrough; |
45 | if ($_ eq ':case') { | |
46 | $DEFAULT_FLAGS &= ~GLOB_NOCASE() | |
47 | } | |
48 | elsif ($_ eq ':nocase') { | |
49 | $DEFAULT_FLAGS |= GLOB_NOCASE(); | |
50 | } | |
51 | elsif ($_ eq ':globally') { | |
52 | no warnings 'redefine'; | |
53 | *CORE::GLOBAL::glob = \&File::Glob::csh_glob; | |
220398a0 | 54 | } |
44bda135 BF |
55 | elsif ($_ eq ':bsd_glob') { |
56 | no strict; *{caller."::glob"} = \&bsd_glob_override; | |
57 | $passthrough = 1; | |
58 | } | |
59 | else { | |
60 | $passthrough = 1; | |
61 | } | |
62 | $passthrough; | |
df5a3819 | 63 | } @_); |
72b16652 GS |
64 | } |
65 | ||
da4061d3 | 66 | XSLoader::load(); |
72b16652 | 67 | |
220398a0 | 68 | $DEFAULT_FLAGS = GLOB_CSH(); |
862f843b | 69 | if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos)$/) { |
220398a0 PM |
70 | $DEFAULT_FLAGS |= GLOB_NOCASE(); |
71 | } | |
72 | ||
df8b709b JK |
73 | # File::Glob::glob() removed in perl-5.30 because its prototype is different |
74 | # from CORE::glob() (use bsd_glob() instead) | |
00c80938 | 75 | sub glob { |
df8b709b JK |
76 | die "File::Glob::glob() was removed in perl 5.30. " . |
77 | "Use File::Glob::bsd_glob() instead. $!"; | |
00c80938 GS |
78 | } |
79 | ||
72b16652 GS |
80 | 1; |
81 | __END__ | |
82 | ||
83 | =head1 NAME | |
84 | ||
85 | File::Glob - Perl extension for BSD glob routine | |
86 | ||
87 | =head1 SYNOPSIS | |
88 | ||
5144542d | 89 | use File::Glob ':bsd_glob'; |
9d70ac1b | 90 | |
00c80938 GS |
91 | @list = bsd_glob('*.[ch]'); |
92 | $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR); | |
9d70ac1b | 93 | |
72b16652 GS |
94 | if (GLOB_ERROR) { |
95 | # an error occurred reading $homedir | |
96 | } | |
97 | ||
00c80938 | 98 | ## override the core glob (CORE::glob() does this automatically |
11fe14b1 | 99 | ## by default anyway, since v5.6.0) |
220398a0 | 100 | use File::Glob ':globally'; |
6bd08436 | 101 | my @sources = <*.{c,h,y}>; |
220398a0 PM |
102 | |
103 | ## override the core glob, forcing case sensitivity | |
104 | use File::Glob qw(:globally :case); | |
6bd08436 | 105 | my @sources = <*.{c,h,y}>; |
220398a0 PM |
106 | |
107 | ## override the core glob forcing case insensitivity | |
108 | use File::Glob qw(:globally :nocase); | |
6bd08436 | 109 | my @sources = <*.{c,h,y}>; |
9d70ac1b | 110 | |
6bd08436 SS |
111 | ## glob on all files in home directory |
112 | use File::Glob ':globally'; | |
113 | my @sources = <~gnat/*>; | |
72b16652 GS |
114 | |
115 | =head1 DESCRIPTION | |
116 | ||
9d70ac1b RGS |
117 | The glob angle-bracket operator C<< <> >> is a pathname generator that |
118 | implements the rules for file name pattern matching used by Unix-like shells | |
119 | such as the Bourne shell or C shell. | |
6bd08436 | 120 | |
00c80938 GS |
121 | File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is |
122 | a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). | |
123 | bsd_glob() takes a mandatory C<pattern> argument, and an optional | |
72b16652 GS |
124 | C<flags> argument, and returns a list of filenames matching the |
125 | pattern, with interpretation of the pattern modified by the C<flags> | |
00c80938 GS |
126 | variable. |
127 | ||
128 | Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). | |
129 | Note that they don't share the same prototype--CORE::glob() only accepts | |
130 | a single argument. Due to historical reasons, CORE::glob() will also | |
131 | split its argument on whitespace, treating it as multiple patterns, | |
5144542d FC |
132 | whereas bsd_glob() considers them as one pattern. But see C<:bsd_glob> |
133 | under L</EXPORTS>, below. | |
00c80938 | 134 | |
6bd08436 SS |
135 | =head2 META CHARACTERS |
136 | ||
9d70ac1b RGS |
137 | \ Quote the next metacharacter |
138 | [] Character class | |
139 | {} Multiple pattern | |
140 | * Match any string of characters | |
141 | ? Match any single character | |
142 | ~ User name home directory | |
143 | ||
144 | The metanotation C<a{b,c,d}e> is a shorthand for C<abe ace ade>. Left to | |
145 | right order is preserved, with results of matches being sorted separately | |
d2a88f5f | 146 | at a low level to preserve this order. As a special case C<{>, C<}>, and |
9d70ac1b | 147 | C<{}> are passed undisturbed. |
6bd08436 | 148 | |
5144542d FC |
149 | =head2 EXPORTS |
150 | ||
8c9e50e7 FC |
151 | See also the L</POSIX FLAGS> below, which can be exported individually. |
152 | ||
153 | =head3 C<:bsd_glob> | |
154 | ||
5144542d FC |
155 | The C<:bsd_glob> export tag exports bsd_glob() and the constants listed |
156 | below. It also overrides glob() in the calling package with one that | |
157 | behaves like bsd_glob() with regard to spaces (the space is treated as part | |
158 | of a file name), but supports iteration in scalar context; i.e., it | |
159 | preserves the core function's feature of returning the next item each time | |
160 | it is called. | |
161 | ||
8c9e50e7 FC |
162 | =head3 C<:glob> |
163 | ||
5144542d FC |
164 | The C<:glob> tag, now discouraged, is the old version of C<:bsd_glob>. It |
165 | exports the same constants and functions, but its glob() override does not | |
166 | support iteration; it returns the last file name in scalar context. That | |
167 | means this will loop forever: | |
168 | ||
169 | use File::Glob ':glob'; | |
170 | while (my $file = <* copy.txt>) { | |
171 | ... | |
172 | } | |
173 | ||
8c9e50e7 FC |
174 | =head3 C<bsd_glob> |
175 | ||
176 | This function, which is included in the two export tags listed above, | |
8fe4bbc8 EA |
177 | takes one or two arguments. The first is the glob pattern. The |
178 | second, if given, is a set of flags ORed together. The available | |
179 | flags and the default set of flags are listed below under L</POSIX FLAGS>. | |
180 | ||
181 | Remember that to use the named constants for flags you must import | |
182 | them, for example with C<:bsd_glob> described above. If not imported, | |
183 | and C<use strict> is not in effect, then the constants will be | |
184 | treated as bareword strings, which won't do what you what. | |
185 | ||
8c9e50e7 FC |
186 | |
187 | =head3 C<:nocase> and C<:case> | |
188 | ||
189 | These two export tags globally modify the default flags that bsd_glob() | |
190 | and, except on VMS, Perl's built-in C<glob> operator use. C<GLOB_NOCASE> | |
191 | is turned on or off, respectively. | |
192 | ||
193 | =head3 C<csh_glob> | |
5144542d | 194 | |
ffd7a473 FC |
195 | The csh_glob() function can also be exported, but you should not use it |
196 | directly unless you really know what you are doing. It splits the pattern | |
197 | into words and feeds each one to bsd_glob(). Perl's own glob() function | |
198 | uses this internally. | |
199 | ||
6bd08436 SS |
200 | =head2 POSIX FLAGS |
201 | ||
8fe4bbc8 EA |
202 | If no flags argument is give then C<GLOB_CSH> is set, and on VMS and |
203 | Windows systems, C<GLOB_NOCASE> too. Otherwise the flags to use are | |
204 | determined solely by the flags argument. The POSIX defined flags are: | |
72b16652 GS |
205 | |
206 | =over 4 | |
207 | ||
208 | =item C<GLOB_ERR> | |
209 | ||
00c80938 GS |
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. | |
72b16652 | 212 | |
b8ef571c JH |
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 | ||
72b16652 GS |
222 | =item C<GLOB_MARK> |
223 | ||
224 | Each pathname that is a directory that matches the pattern has a slash | |
225 | appended. | |
226 | ||
220398a0 PM |
227 | =item C<GLOB_NOCASE> |
228 | ||
229 | By default, file names are assumed to be case sensitive; this flag | |
00c80938 | 230 | makes bsd_glob() treat case differences as not significant. |
220398a0 | 231 | |
72b16652 GS |
232 | =item C<GLOB_NOCHECK> |
233 | ||
00c80938 | 234 | If the pattern does not match any pathname, then bsd_glob() returns a list |
72b16652 GS |
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 | |
00c80938 | 241 | flag prevents that sorting (speeding up bsd_glob()). |
72b16652 GS |
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 | ||
a45bd81d | 251 | Pre-process the string to expand C<{pat,pat,...}> strings like csh(1). |
72b16652 GS |
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. | |
220398a0 | 267 | (But see below for exceptions on DOSISH systems). |
72b16652 GS |
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 | |
2d5e9e5d | 276 | C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT>. |
72b16652 GS |
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 | ||
2d5e9e5d JH |
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 | ||
72b16652 GS |
297 | =head1 DIAGNOSTICS |
298 | ||
00c80938 | 299 | bsd_glob() returns a list of matching paths, possibly zero length. If an |
72b16652 GS |
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 | ||
00c80938 GS |
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> | |
72b16652 GS |
318 | set &File::Glob::ERROR. |
319 | ||
00c80938 GS |
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 | |
72b16652 GS |
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 | ||
9d70ac1b RGS |
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 | |
150b260b GS |
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. | |
72b16652 GS |
337 | |
338 | =item * | |
339 | ||
220398a0 PM |
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) | |
d2a88f5f | 342 | interferes with the use of backslash as a directory separator. The |
220398a0 | 343 | best (simplest, most portable) solution is to use forward slashes for |
d2a88f5f FC |
344 | directory separators, and backslashes for quoting. However, this does |
345 | not match "normal practice" on these systems. As a concession to user | |
220398a0 PM |
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 | ||
72b16652 GS |
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 | ||
a45bd81d GS |
356 | =back |
357 | ||
6bd08436 SS |
358 | =head1 SEE ALSO |
359 | ||
360 | L<perlfunc/glob>, glob(3) | |
361 | ||
72b16652 GS |
362 | =head1 AUTHOR |
363 | ||
0e950d83 | 364 | The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>, |
72b16652 | 365 | and is released under the artistic license. Further modifications were |
7369a524 CN |
366 | made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy |
367 | E<lt>gsar@activestate.comE<gt>, and Thomas Wegner | |
368 | E<lt>wegner_thomas@yahoo.comE<gt>. The C glob code has the | |
72b16652 GS |
369 | following copyright: |
370 | ||
e46aa1dd KW |
371 | Copyright (c) 1989, 1993 The Regents of the University of California. |
372 | All rights reserved. | |
373 | ||
374 | This code is derived from software contributed to Berkeley by | |
375 | Guido van Rossum. | |
376 | ||
377 | Redistribution and use in source and binary forms, with or without | |
378 | modification, are permitted provided that the following conditions | |
379 | are met: | |
380 | ||
381 | =over 4 | |
382 | ||
383 | =item 1. | |
384 | ||
385 | Redistributions of source code must retain the above copyright | |
386 | notice, this list of conditions and the following disclaimer. | |
387 | ||
388 | =item 2. | |
389 | ||
390 | Redistributions in binary form must reproduce the above copyright | |
391 | notice, this list of conditions and the following disclaimer in the | |
392 | documentation and/or other materials provided with the distribution. | |
393 | ||
394 | =item 3. | |
395 | ||
396 | Neither the name of the University nor the names of its contributors | |
397 | may be used to endorse or promote products derived from this software | |
398 | without specific prior written permission. | |
399 | ||
400 | =back | |
401 | ||
402 | THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND | |
403 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
404 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
405 | ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
406 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
407 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
408 | OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
409 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
410 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
411 | OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
412 | SUCH DAMAGE. | |
72b16652 GS |
413 | |
414 | =cut |