1package File::Glob; 2 3use strict; 4our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, $DEFAULT_FLAGS); 5 6require XSLoader; 7use feature 'switch'; 8 9@ISA = qw(Exporter); 10 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 14%EXPORT_TAGS = ( 15 'glob' => [ qw( 16 GLOB_ABEND 17 GLOB_ALPHASORT 18 GLOB_ALTDIRFUNC 19 GLOB_BRACE 20 GLOB_CSH 21 GLOB_ERR 22 GLOB_ERROR 23 GLOB_LIMIT 24 GLOB_MARK 25 GLOB_NOCASE 26 GLOB_NOCHECK 27 GLOB_NOMAGIC 28 GLOB_NOSORT 29 GLOB_NOSPACE 30 GLOB_QUOTE 31 GLOB_TILDE 32 bsd_glob 33 glob 34 ) ], 35); 36$EXPORT_TAGS{bsd_glob} = [@{$EXPORT_TAGS{glob}}]; 37pop @{$EXPORT_TAGS{bsd_glob}}; # no "glob" 38 39@EXPORT_OK = (@{$EXPORT_TAGS{'glob'}}, 'csh_glob'); 40 41$VERSION = '1.17'; 42 43sub import { 44 require Exporter; 45 local $Exporter::ExportLevel = $Exporter::ExportLevel + 1; 46 Exporter::import(grep { 47 my $passthrough; 48 given ($_) { 49 $DEFAULT_FLAGS &= ~GLOB_NOCASE() when ':case'; 50 $DEFAULT_FLAGS |= GLOB_NOCASE() when ':nocase'; 51 when (':globally') { 52 no warnings 'redefine'; 53 *CORE::GLOBAL::glob = \&File::Glob::csh_glob; 54 } 55 if ($_ eq ':bsd_glob') { 56 no strict; *{caller."::glob"} = \&bsd_glob_override; 57 } 58 $passthrough = 1; 59 } 60 $passthrough; 61 } @_); 62} 63 64XSLoader::load(); 65 66$DEFAULT_FLAGS = GLOB_CSH(); 67if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos)$/) { 68 $DEFAULT_FLAGS |= GLOB_NOCASE(); 69} 70 71# File::Glob::glob() is deprecated because its prototype is different from 72# CORE::glob() (use bsd_glob() instead) 73sub glob { 74 splice @_, 1; # don't pass PL_glob_index as flags! 75 goto &bsd_glob; 76} 77 781; 79__END__ 80 81=head1 NAME 82 83File::Glob - Perl extension for BSD glob routine 84 85=head1 SYNOPSIS 86 87 use File::Glob ':bsd_glob'; 88 89 @list = bsd_glob('*.[ch]'); 90 $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR); 91 92 if (GLOB_ERROR) { 93 # an error occurred reading $homedir 94 } 95 96 ## override the core glob (CORE::glob() does this automatically 97 ## by default anyway, since v5.6.0) 98 use File::Glob ':globally'; 99 my @sources = <*.{c,h,y}>; 100 101 ## override the core glob, forcing case sensitivity 102 use File::Glob qw(:globally :case); 103 my @sources = <*.{c,h,y}>; 104 105 ## override the core glob forcing case insensitivity 106 use File::Glob qw(:globally :nocase); 107 my @sources = <*.{c,h,y}>; 108 109 ## glob on all files in home directory 110 use File::Glob ':globally'; 111 my @sources = <~gnat/*>; 112 113=head1 DESCRIPTION 114 115The glob angle-bracket operator C<< <> >> is a pathname generator that 116implements the rules for file name pattern matching used by Unix-like shells 117such as the Bourne shell or C shell. 118 119File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is 120a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). 121bsd_glob() takes a mandatory C<pattern> argument, and an optional 122C<flags> argument, and returns a list of filenames matching the 123pattern, with interpretation of the pattern modified by the C<flags> 124variable. 125 126Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). 127Note that they don't share the same prototype--CORE::glob() only accepts 128a single argument. Due to historical reasons, CORE::glob() will also 129split its argument on whitespace, treating it as multiple patterns, 130whereas bsd_glob() considers them as one pattern. But see C<:bsd_glob> 131under L</EXPORTS>, below. 132 133=head2 META CHARACTERS 134 135 \ Quote the next metacharacter 136 [] Character class 137 {} Multiple pattern 138 * Match any string of characters 139 ? Match any single character 140 ~ User name home directory 141 142The metanotation C<a{b,c,d}e> is a shorthand for C<abe ace ade>. Left to 143right order is preserved, with results of matches being sorted separately 144at a low level to preserve this order. As a special case C<{>, C<}>, and 145C<{}> are passed undisturbed. 146 147=head2 EXPORTS 148 149See also the L</POSIX FLAGS> below, which can be exported individually. 150 151=head3 C<:bsd_glob> 152 153The C<:bsd_glob> export tag exports bsd_glob() and the constants listed 154below. It also overrides glob() in the calling package with one that 155behaves like bsd_glob() with regard to spaces (the space is treated as part 156of a file name), but supports iteration in scalar context; i.e., it 157preserves the core function's feature of returning the next item each time 158it is called. 159 160=head3 C<:glob> 161 162The C<:glob> tag, now discouraged, is the old version of C<:bsd_glob>. It 163exports the same constants and functions, but its glob() override does not 164support iteration; it returns the last file name in scalar context. That 165means this will loop forever: 166 167 use File::Glob ':glob'; 168 while (my $file = <* copy.txt>) { 169 ... 170 } 171 172=head3 C<bsd_glob> 173 174This function, which is included in the two export tags listed above, 175takes one or two arguments. The first is the glob pattern. The second is 176a set of flags ORed together. The available flags are listed below under 177L</POSIX FLAGS>. If the second argument is omitted, C<GLOB_CSH> (or 178C<GLOB_CSH|GLOB_NOCASE> on VMS and DOSish systems) is used by default. 179 180=head3 C<:nocase> and C<:case> 181 182These two export tags globally modify the default flags that bsd_glob() 183and, except on VMS, Perl's built-in C<glob> operator use. C<GLOB_NOCASE> 184is turned on or off, respectively. 185 186=head3 C<csh_glob> 187 188The csh_glob() function can also be exported, but you should not use it 189directly unless you really know what you are doing. It splits the pattern 190into words and feeds each one to bsd_glob(). Perl's own glob() function 191uses this internally. 192 193=head2 POSIX FLAGS 194 195The POSIX defined flags for bsd_glob() 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 362 Copyright (c) 1989, 1993 The Regents of the University of California. 363 All rights reserved. 364 365 This code is derived from software contributed to Berkeley by 366 Guido van Rossum. 367 368 Redistribution and use in source and binary forms, with or without 369 modification, are permitted provided that the following conditions 370 are met: 371 372 1. Redistributions of source code must retain the above copyright 373 notice, this list of conditions and the following disclaimer. 374 2. Redistributions in binary form must reproduce the above copyright 375 notice, this list of conditions and the following disclaimer in the 376 documentation and/or other materials provided with the distribution. 377 3. Neither the name of the University nor the names of its contributors 378 may be used to endorse or promote products derived from this software 379 without specific prior written permission. 380 381 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND 382 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 383 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 384 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 385 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 386 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 387 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 388 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 389 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 390 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 391 SUCH DAMAGE. 392 393=cut 394