1package File::Glob; 2 3use strict; 4our($DEFAULT_FLAGS); 5 6require XSLoader; 7 8# NOTE: The glob() export is only here for compatibility with 5.6.0. 9# csh_glob() should not be used directly, unless you know what you're doing. 10 11our %EXPORT_TAGS = ( 12 'glob' => [ qw( 13 GLOB_ABEND 14 GLOB_ALPHASORT 15 GLOB_ALTDIRFUNC 16 GLOB_BRACE 17 GLOB_CSH 18 GLOB_ERR 19 GLOB_ERROR 20 GLOB_LIMIT 21 GLOB_MARK 22 GLOB_NOCASE 23 GLOB_NOCHECK 24 GLOB_NOMAGIC 25 GLOB_NOSORT 26 GLOB_NOSPACE 27 GLOB_QUOTE 28 GLOB_TILDE 29 bsd_glob 30 ) ], 31); 32$EXPORT_TAGS{bsd_glob} = [@{$EXPORT_TAGS{glob}}]; 33 34our @EXPORT_OK = (@{$EXPORT_TAGS{'glob'}}, 'csh_glob'); 35 36our $VERSION = '1.37'; 37 38sub import { 39 require Exporter; 40 local $Exporter::ExportLevel = $Exporter::ExportLevel + 1; 41 Exporter::import(grep { 42 my $passthrough; 43 if ($_ eq ':case') { 44 $DEFAULT_FLAGS &= ~GLOB_NOCASE() 45 } 46 elsif ($_ eq ':nocase') { 47 $DEFAULT_FLAGS |= GLOB_NOCASE(); 48 } 49 elsif ($_ eq ':globally') { 50 no warnings 'redefine'; 51 *CORE::GLOBAL::glob = \&File::Glob::csh_glob; 52 } 53 elsif ($_ eq ':bsd_glob') { 54 no strict; *{caller."::glob"} = \&bsd_glob_override; 55 $passthrough = 1; 56 } 57 else { 58 $passthrough = 1; 59 } 60 $passthrough; 61 } @_); 62} 63 64XSLoader::load(); 65 66$DEFAULT_FLAGS = GLOB_CSH(); 67if ($^O =~ /^(?:MSWin32|VMS|os2|riscos)$/) { 68 $DEFAULT_FLAGS |= GLOB_NOCASE(); 69} 70 711; 72__END__ 73 74=head1 NAME 75 76File::Glob - Perl extension for BSD glob routine 77 78=head1 SYNOPSIS 79 80 use File::Glob ':bsd_glob'; 81 82 @list = bsd_glob('*.[ch]'); 83 $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR); 84 85 if (GLOB_ERROR) { 86 # an error occurred reading $homedir 87 } 88 89 ## override the core glob (CORE::glob() does this automatically 90 ## by default anyway, since v5.6.0) 91 use File::Glob ':globally'; 92 my @sources = <*.{c,h,y}>; 93 94 ## override the core glob, forcing case sensitivity 95 use File::Glob qw(:globally :case); 96 my @sources = <*.{c,h,y}>; 97 98 ## override the core glob forcing case insensitivity 99 use File::Glob qw(:globally :nocase); 100 my @sources = <*.{c,h,y}>; 101 102 ## glob on all files in home directory 103 use File::Glob ':globally'; 104 my @sources = <~gnat/*>; 105 106=head1 DESCRIPTION 107 108The glob angle-bracket operator C<< <> >> is a pathname generator that 109implements the rules for file name pattern matching used by Unix-like shells 110such as the Bourne shell or C shell. 111 112File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is 113a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). 114bsd_glob() takes a mandatory C<pattern> argument, and an optional 115C<flags> argument, and returns a list of filenames matching the 116pattern, with interpretation of the pattern modified by the C<flags> 117variable. 118 119Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). 120Note that they don't share the same prototype--CORE::glob() only accepts 121a single argument. Due to historical reasons, CORE::glob() will also 122split its argument on whitespace, treating it as multiple patterns, 123whereas bsd_glob() considers them as one pattern. But see C<:bsd_glob> 124under L</EXPORTS>, below. 125 126=head2 META CHARACTERS 127 128 \ Quote the next metacharacter 129 [] Character class 130 {} Multiple pattern 131 * Match any string of characters 132 ? Match any single character 133 ~ User name home directory 134 135The metanotation C<a{b,c,d}e> is a shorthand for C<abe ace ade>. Left to 136right order is preserved, with results of matches being sorted separately 137at a low level to preserve this order. As a special case C<{>, C<}>, and 138C<{}> are passed undisturbed. 139 140=head2 EXPORTS 141 142See also the L</POSIX FLAGS> below, which can be exported individually. 143 144=head3 C<:bsd_glob> 145 146The C<:bsd_glob> export tag exports bsd_glob() and the constants listed 147below. It also overrides glob() in the calling package with one that 148behaves like bsd_glob() with regard to spaces (the space is treated as part 149of a file name), but supports iteration in scalar context; i.e., it 150preserves the core function's feature of returning the next item each time 151it is called. 152 153=head3 C<:glob> 154 155The C<:glob> tag, now discouraged, is the old version of C<:bsd_glob>. It 156exports the same constants and functions, but its glob() override does not 157support iteration; it returns the last file name in scalar context. That 158means this will loop forever: 159 160 use File::Glob ':glob'; 161 while (my $file = <* copy.txt>) { 162 ... 163 } 164 165=head3 C<bsd_glob> 166 167This function, which is included in the two export tags listed above, 168takes one or two arguments. The first is the glob pattern. The 169second, if given, is a set of flags ORed together. The available 170flags and the default set of flags are listed below under L</POSIX FLAGS>. 171 172Remember that to use the named constants for flags you must import 173them, for example with C<:bsd_glob> described above. If not imported, 174and C<use strict> is not in effect, then the constants will be 175treated as bareword strings, which won't do what you what. 176 177 178=head3 C<:nocase> and C<:case> 179 180These two export tags globally modify the default flags that bsd_glob() 181and, except on VMS, Perl's built-in C<glob> operator use. C<GLOB_NOCASE> 182is turned on or off, respectively. 183 184=head3 C<csh_glob> 185 186The csh_glob() function can also be exported, but you should not use it 187directly unless you really know what you are doing. It splits the pattern 188into words and feeds each one to bsd_glob(). Perl's own glob() function 189uses this internally. 190 191=head2 POSIX FLAGS 192 193If no flags argument is give then C<GLOB_CSH> is set, and on VMS and 194Windows systems, C<GLOB_NOCASE> too. Otherwise the flags to use are 195determined solely by the flags argument. The POSIX defined flags are: 196 197=over 4 198 199=item C<GLOB_ERR> 200 201Force bsd_glob() to return an error when it encounters a directory it 202cannot open or read. Ordinarily bsd_glob() continues to find matches. 203 204=item C<GLOB_LIMIT> 205 206Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern expands 207to a size bigger than the system constant C<ARG_MAX> (usually found in 208limits.h). If your system does not define this constant, bsd_glob() uses 209C<sysconf(_SC_ARG_MAX)> or C<_POSIX_ARG_MAX> where available (in that 210order). You can inspect these values using the standard C<POSIX> 211extension. 212 213=item C<GLOB_MARK> 214 215Each pathname that is a directory that matches the pattern has a slash 216appended. 217 218=item C<GLOB_NOCASE> 219 220By default, file names are assumed to be case sensitive; this flag 221makes bsd_glob() treat case differences as not significant. 222 223=item C<GLOB_NOCHECK> 224 225If the pattern does not match any pathname, then bsd_glob() returns a list 226consisting of only the pattern. If C<GLOB_QUOTE> is set, its effect 227is present in the pattern returned. 228 229=item C<GLOB_NOSORT> 230 231By default, the pathnames are sorted in ascending ASCII order; this 232flag prevents that sorting (speeding up bsd_glob()). 233 234=back 235 236The FreeBSD extensions to the POSIX standard are the following flags: 237 238=over 4 239 240=item C<GLOB_BRACE> 241 242Pre-process the string to expand C<{pat,pat,...}> strings like csh(1). 243The pattern '{}' is left unexpanded for historical reasons (and csh(1) 244does the same thing to ease typing of find(1) patterns). 245 246=item C<GLOB_NOMAGIC> 247 248Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not 249contain any of the special characters "*", "?" or "[". C<NOMAGIC> is 250provided to simplify implementing the historic csh(1) globbing 251behaviour and should probably not be used anywhere else. 252 253=item C<GLOB_QUOTE> 254 255Use the backslash ('\') character for quoting: every occurrence of a 256backslash followed by a character in the pattern is replaced by that 257character, avoiding any special interpretation of the character. 258(But see below for exceptions on DOSISH systems). 259 260=item C<GLOB_TILDE> 261 262Expand patterns that start with '~' to user name home directories. 263 264=item C<GLOB_CSH> 265 266For convenience, C<GLOB_CSH> is a synonym for 267C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT>. 268 269=back 270 271The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD 272extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been 273implemented in the Perl version because they involve more complex 274interaction with the underlying C structures. 275 276The following flag has been added in the Perl implementation for 277csh compatibility: 278 279=over 4 280 281=item C<GLOB_ALPHASORT> 282 283If C<GLOB_NOSORT> is not in effect, sort filenames is alphabetical 284order (case does not matter) rather than in ASCII order. 285 286=back 287 288=head1 DIAGNOSTICS 289 290bsd_glob() returns a list of matching paths, possibly zero length. If an 291error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be 292set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred, 293or one of the following values otherwise: 294 295=over 4 296 297=item C<GLOB_NOSPACE> 298 299An attempt to allocate memory failed. 300 301=item C<GLOB_ABEND> 302 303The glob was stopped because an error was encountered. 304 305=back 306 307In the case where bsd_glob() has found some matching paths, but is 308interrupted by an error, it will return a list of filenames B<and> 309set &File::Glob::ERROR. 310 311Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour 312by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will 313continue processing despite those errors, unless the C<GLOB_ERR> flag is 314set. 315 316Be aware that all filenames returned from File::Glob are tainted. 317 318=head1 NOTES 319 320=over 4 321 322=item * 323 324If you want to use multiple patterns, e.g. C<bsd_glob("a* b*")>, you should 325probably throw them in a set as in C<bsd_glob("{a*,b*}")>. This is because 326the argument to bsd_glob() isn't subjected to parsing by the C shell. 327Remember that you can use a backslash to escape things. 328 329=item * 330 331On DOSISH systems, backslash is a valid directory separator character. 332In this case, use of backslash as a quoting character (via GLOB_QUOTE) 333interferes with the use of backslash as a directory separator. The 334best (simplest, most portable) solution is to use forward slashes for 335directory separators, and backslashes for quoting. However, this does 336not match "normal practice" on these systems. As a concession to user 337expectation, therefore, backslashes (under GLOB_QUOTE) only quote the 338glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself. 339All other backslashes are passed through unchanged. 340 341=item * 342 343Win32 users should use the real slash. If you really want to use 344backslashes, consider using Sarathy's File::DosGlob, which comes with 345the standard Perl distribution. 346 347=back 348 349=head1 SEE ALSO 350 351L<perlfunc/glob>, glob(3) 352 353=head1 AUTHOR 354 355The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>, 356and is released under the artistic license. Further modifications were 357made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy 358E<lt>gsar@activestate.comE<gt>, and Thomas Wegner 359E<lt>wegner_thomas@yahoo.comE<gt>. The C glob code has the 360following copyright: 361 362Copyright (c) 1989, 1993 The Regents of the University of California. 363All rights reserved. 364 365This code is derived from software contributed to Berkeley by 366Guido van Rossum. 367 368Redistribution and use in source and binary forms, with or without 369modification, are permitted provided that the following conditions 370are met: 371 372=over 4 373 374=item 1. 375 376Redistributions of source code must retain the above copyright 377notice, this list of conditions and the following disclaimer. 378 379=item 2. 380 381Redistributions in binary form must reproduce the above copyright 382notice, this list of conditions and the following disclaimer in the 383documentation and/or other materials provided with the distribution. 384 385=item 3. 386 387Neither the name of the University nor the names of its contributors 388may be used to endorse or promote products derived from this software 389without specific prior written permission. 390 391=back 392 393THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND 394ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 395IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 396ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 397FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 398DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 399OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 400HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 401LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 402OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 403SUCH DAMAGE. 404 405=cut 406