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