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