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