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