This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
add File::BSDGlob as File::Glob and load it at compile-time
[perl5.git] / ext / File / Glob / Glob.pm
CommitLineData
72b16652
GS
1package File::Glob;
2
3use strict;
4use Carp;
5use vars qw($VERSION @ISA @EXPORT_OK @EXPORT_FAIL %EXPORT_TAGS $AUTOLOAD);
6
7require Exporter;
8require DynaLoader;
9require AutoLoader;
10
11@ISA = qw(Exporter DynaLoader AutoLoader);
12
13@EXPORT_OK = qw(
14 globally
15 csh_glob
16 glob
17 GLOB_ABEND
18 GLOB_ALTDIRFUNC
19 GLOB_BRACE
20 GLOB_ERR
21 GLOB_ERROR
22 GLOB_MARK
23 GLOB_NOCHECK
24 GLOB_NOMAGIC
25 GLOB_NOSORT
26 GLOB_NOSPACE
27 GLOB_QUOTE
28 GLOB_TILDE
29);
30
31@EXPORT_FAIL = ( 'globally' );
32
33%EXPORT_TAGS = (
34 'glob' => [ qw(
35 GLOB_ABEND
36 GLOB_ALTDIRFUNC
37 GLOB_BRACE
38 GLOB_ERR
39 GLOB_ERROR
40 GLOB_MARK
41 GLOB_NOCHECK
42 GLOB_NOMAGIC
43 GLOB_NOSORT
44 GLOB_NOSPACE
45 GLOB_QUOTE
46 GLOB_TILDE
47 glob
48 ) ],
49);
50
51$VERSION = '0.99';
52
53sub export_fail {
54 shift;
55
56 if ($_[0] eq 'globally') {
57 local $^W;
58 *CORE::GLOBAL::glob = \&File::Glob::csh_glob;
59 shift;
60 }
61
62 @_;
63}
64
65sub AUTOLOAD {
66 # This AUTOLOAD is used to 'autoload' constants from the constant()
67 # XS function. If a constant is not found then control is passed
68 # to the AUTOLOAD in AutoLoader.
69
70 my $constname;
71 ($constname = $AUTOLOAD) =~ s/.*:://;
72 my $val = constant($constname, @_ ? $_[0] : 0);
73 if ($! != 0) {
74 if ($! =~ /Invalid/) {
75 $AutoLoader::AUTOLOAD = $AUTOLOAD;
76 goto &AutoLoader::AUTOLOAD;
77 }
78 else {
79 croak "Your vendor has not defined File::Glob macro $constname";
80 }
81 }
82 eval "sub $AUTOLOAD { $val }";
83 goto &$AUTOLOAD;
84}
85
86bootstrap File::Glob $VERSION;
87
88# Preloaded methods go here.
89
90sub GLOB_ERROR {
91 return constant('GLOB_ERROR', 0);
92}
93
94sub GLOB_CSH () { GLOB_BRACE() | GLOB_NOMAGIC() | GLOB_QUOTE() | GLOB_TILDE() }
95
96# Autoload methods go after =cut, and are processed by the autosplit program.
97
98sub glob {
99 return doglob(@_);
100}
101
102## borrowed heavily from gsar's File::DosGlob
103my %iter;
104my %entries;
105
106sub csh_glob {
107 my $pat = shift;
108 my $cxix = shift;
109 my @pat;
110
111 # glob without args defaults to $_
112 $pat = $_ unless defined $pat;
113
114 # extract patterns
115 if ($pat =~ /\s/) {
116 # XXX this is needed for compatibility with the csh
117 # implementation in Perl. Need to support a flag
118 # to disable this behavior.
119 require Text::ParseWords;
120 @pat = Text::ParseWords::parse_line('\s+',0,$pat);
121 }
122
123 # assume global context if not provided one
124 $cxix = '_G_' unless defined $cxix;
125 $iter{$cxix} = 0 unless exists $iter{$cxix};
126
127 # if we're just beginning, do it all first
128 if ($iter{$cxix} == 0) {
129 if (@pat) {
130 $entries{$cxix} = [ map { doglob($_, GLOB_CSH) } @pat ];
131 }
132 else {
133 $entries{$cxix} = [ doglob($pat, GLOB_CSH) ];
134 }
135 }
136
137 # chuck it all out, quick or slow
138 if (wantarray) {
139 delete $iter{$cxix};
140 return @{delete $entries{$cxix}};
141 }
142 else {
143 if ($iter{$cxix} = scalar @{$entries{$cxix}}) {
144 return shift @{$entries{$cxix}};
145 }
146 else {
147 # return undef for EOL
148 delete $iter{$cxix};
149 delete $entries{$cxix};
150 return undef;
151 }
152 }
153}
154
1551;
156__END__
157
158=head1 NAME
159
160File::Glob - Perl extension for BSD glob routine
161
162=head1 SYNOPSIS
163
164 use File::Glob ':glob';
165 @list = glob('*.[ch]');
166 $homedir = glob('~gnat', GLOB_TILDE | GLOB_ERR);
167 if (GLOB_ERROR) {
168 # an error occurred reading $homedir
169 }
170
171 ## override the core glob (even with -T)
172 use File::Glob 'globally';
173 my @sources = <*.{c,h,y}>
174
175=head1 DESCRIPTION
176
177File::Glob implements the FreeBSD glob(3) routine, which is a superset
178of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). The
179glob() routine takes a mandatory C<pattern> argument, and an optional
180C<flags> argument, and returns a list of filenames matching the
181pattern, with interpretation of the pattern modified by the C<flags>
182variable. The POSIX defined flags are:
183
184=over 4
185
186=item C<GLOB_ERR>
187
188Force glob() to return an error when it encounters a directory it
189cannot open or read. Ordinarily glob() continues to find matches.
190
191=item C<GLOB_MARK>
192
193Each pathname that is a directory that matches the pattern has a slash
194appended.
195
196=item C<GLOB_NOCHECK>
197
198If the pattern does not match any pathname, then glob() returns a list
199consisting of only the pattern. If C<GLOB_QUOTE> is set, its effect
200is present in the pattern returned.
201
202=item C<GLOB_NOSORT>
203
204By default, the pathnames are sorted in ascending ASCII order; this
205flag prevents that sorting (speeding up glob()).
206
207=back
208
209The FreeBSD extensions to the POSIX standard are the following flags:
210
211=over 4
212
213=item C<GLOB_BRACE>
214
215Pre-process the string to expand C<{pat,pat,...} strings like csh(1).
216The pattern '{}' is left unexpanded for historical reasons (and csh(1)
217does the same thing to ease typing of find(1) patterns).
218
219=item C<GLOB_NOMAGIC>
220
221Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not
222contain any of the special characters "*", "?" or "[". C<NOMAGIC> is
223provided to simplify implementing the historic csh(1) globbing
224behaviour and should probably not be used anywhere else.
225
226=item C<GLOB_QUOTE>
227
228Use the backslash ('\') character for quoting: every occurrence of a
229backslash followed by a character in the pattern is replaced by that
230character, avoiding any special interpretation of the character.
231
232=item C<GLOB_TILDE>
233
234Expand patterns that start with '~' to user name home directories.
235
236=item C<GLOB_CSH>
237
238For convenience, C<GLOB_CSH> is a synonym for
239C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE>.
240
241=back
242
243The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD
244extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been
245implemented in the Perl version because they involve more complex
246interaction with the underlying C structures.
247
248=head1 DIAGNOSTICS
249
250glob() returns a list of matching paths, possibly zero length. If an
251error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be
252set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
253or one of the following values otherwise:
254
255=over 4
256
257=item C<GLOB_NOSPACE>
258
259An attempt to allocate memory failed.
260
261=item C<GLOB_ABEND>
262
263The glob was stopped because an error was encountered.
264
265=back
266
267In the case where glob() has found some matching paths, but is
268interrupted by an error, glob() will return a list of filenames B<and>
269set &File::Glob::ERROR.
270
271Note that glob() deviates from POSIX and FreeBSD glob(3) behaviour by
272not considering C<ENOENT> and C<ENOTDIR> as errors - glob() will
273continue processing despite those errors, unless the C<GLOB_ERR> flag is
274set.
275
276Be aware that all filenames returned from File::Glob are tainted.
277
278=head1 NOTES
279
280=over 4
281
282=item *
283
284If you want to use multiple patterns, e.g. C<glob "a* b*">, you should
285probably throw them in a set as in C<glob "{a*,b*}>. This is because
286the argument to glob isn't subjected to parsing by the C shell. Remember
287that you can use a backslash to escape things.
288
289=item *
290
291Win32 users should use the real slash. If you really want to use
292backslashes, consider using Sarathy's File::DosGlob, which comes with
293the standard Perl distribution.
294
295=head1 AUTHOR
296
297The Perl interface was written by Nathan Torkington (gnat@frii.com),
298and is released under the artistic license. Further modifications were
299made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt> and Gurusamy Sarathy
300E<lt>gsar@activestate.comE<gt>. The C glob code has the
301following copyright:
302
303 Copyright (c) 1989, 1993 The Regents of the University of California.
304 All rights reserved. This code is derived from software contributed
305 to Berkeley by Guido van Rossum.
306
307For redistribution of the C glob code, read the copyright notice in
308the file bsd_glob.c, which is part of the File::Glob source distribution.
309
310=cut