rename File::Glob::glob() to File::Glob::bsd_glob() to avoid

prototype mismatch with CORE::glob(); update pod and tests to
suit (File::Glob::glob() is still available for backward
compatibility, but should be considered deprecated)

p4raw-id: //depot/perl@5981

diff --git a/ext/File/Glob/Glob.pm b/ext/File/Glob/Glob.pm
index 4b7e54b..1353d4f 100644 (file)
--- a/ext/File/Glob/Glob.pm
+++ b/ext/File/Glob/Glob.pm
@@ -11,8 +11,12 @@ require AutoLoader;
 
 @ISA = qw(Exporter AutoLoader);
 
+# NOTE: The glob() export is only here for compatibility with 5.6.0.
+# csh_glob() should not be used directly, unless you know what you're doing.
+
 @EXPORT_OK   = qw(
     csh_glob
+    bsd_glob
     glob
     GLOB_ABEND
     GLOB_ALTDIRFUNC
@@ -47,6 +51,7 @@ require AutoLoader;
         GLOB_QUOTE
         GLOB_TILDE
         glob
+        bsd_glob
     ) ],
 );
 
@@ -108,12 +113,18 @@ if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos|MacOS)$/) {
 
 # Autoload methods go after =cut, and are processed by the autosplit program.
 
-sub glob {
+sub bsd_glob {
     my ($pat,$flags) = @_;
     $flags = $DEFAULT_FLAGS if @_ < 2;
     return doglob($pat,$flags);
 }
 
+# File::Glob::glob() is deprecated because its prototype is different from
+# CORE::glob() (use bsd_glob() instead)
+sub glob {
+    goto &bsd_glob;
+}
+
 ## borrowed heavily from gsar's File::DosGlob
 my %iter;
 my %entries;
@@ -177,13 +188,13 @@ File::Glob - Perl extension for BSD glob routine
 =head1 SYNOPSIS
 
   use File::Glob ':glob';
-  @list = glob('*.[ch]');
-  $homedir = glob('~gnat', GLOB_TILDE | GLOB_ERR);
+  @list = bsd_glob('*.[ch]');
+  $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
   if (GLOB_ERROR) {
     # an error occurred reading $homedir
   }
 
-  ## override the core glob (core glob() does this automatically
+  ## override the core glob (CORE::glob() does this automatically
   ## by default anyway, since v5.6.0)
   use File::Glob ':globally';
   my @sources = <*.{c,h,y}>
@@ -198,19 +209,27 @@ File::Glob - Perl extension for BSD glob routine
 
 =head1 DESCRIPTION
 
-File::Glob implements the FreeBSD glob(3) routine, which is a superset
-of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2").  The
-glob() routine takes a mandatory C<pattern> argument, and an optional
+File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is
+a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2").
+bsd_glob() takes a mandatory C<pattern> argument, and an optional
 C<flags> argument, and returns a list of filenames matching the
 pattern, with interpretation of the pattern modified by the C<flags>
-variable.  The POSIX defined flags are:
+variable.
+
+Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob().
+Note that they don't share the same prototype--CORE::glob() only accepts
+a single argument.  Due to historical reasons, CORE::glob() will also
+split its argument on whitespace, treating it as multiple patterns,
+whereas bsd_glob() considers them as one pattern.
+
+The POSIX defined flags for bsd_glob() are:
 
 =over 4
 
 =item C<GLOB_ERR>
 
-Force glob() to return an error when it encounters a directory it
-cannot open or read.  Ordinarily glob() continues to find matches.
+Force bsd_glob() to return an error when it encounters a directory it
+cannot open or read.  Ordinarily bsd_glob() continues to find matches.
 
 =item C<GLOB_MARK>
 
@@ -220,18 +239,18 @@ appended.
 =item C<GLOB_NOCASE>
 
 By default, file names are assumed to be case sensitive; this flag
-makes glob() treat case differences as not significant.
+makes bsd_glob() treat case differences as not significant.
 
 =item C<GLOB_NOCHECK>
 
-If the pattern does not match any pathname, then glob() returns a list
+If the pattern does not match any pathname, then bsd_glob() returns a list
 consisting of only the pattern.  If C<GLOB_QUOTE> is set, its effect
 is present in the pattern returned.
 
 =item C<GLOB_NOSORT>
 
 By default, the pathnames are sorted in ascending ASCII order; this
-flag prevents that sorting (speeding up glob()).
+flag prevents that sorting (speeding up bsd_glob()).
 
 =back
 
@@ -277,7 +296,7 @@ interaction with the underlying C structures.
 
 =head1 DIAGNOSTICS
 
-glob() returns a list of matching paths, possibly zero length.  If an
+bsd_glob() returns a list of matching paths, possibly zero length.  If an
 error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be
 set.  &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
 or one of the following values otherwise:
@@ -294,12 +313,12 @@ The glob was stopped because an error was encountered.
 
 =back
 
-In the case where glob() has found some matching paths, but is
-interrupted by an error, glob() will return a list of filenames B<and>
+In the case where bsd_glob() has found some matching paths, but is
+interrupted by an error, it will return a list of filenames B<and>
 set &File::Glob::ERROR.
 
-Note that glob() deviates from POSIX and FreeBSD glob(3) behaviour by
-not considering C<ENOENT> and C<ENOTDIR> as errors - glob() will
+Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
+by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will
 continue processing despite those errors, unless the C<GLOB_ERR> flag is
 set.
 
@@ -311,8 +330,8 @@ Be aware that all filenames returned from File::Glob are tainted.
 
 =item *
 
-If you want to use multiple patterns, e.g. C<glob "a* b*">, you should
-probably throw them in a set as in C<glob "{a*,b*}>.  This is because
+If you want to use multiple patterns, e.g. C<bsd_glob "a* b*">, you should
+probably throw them in a set as in C<glob "{a*,b*}">.  This is because
 the argument to glob isn't subjected to parsing by the C shell.  Remember
 that you can use a backslash to escape things.
 

diff --git a/t/lib/glob-basic.t b/t/lib/glob-basic.t
index 0719193..cbb1263 100755 (executable)
--- a/t/lib/glob-basic.t
+++ b/t/lib/glob-basic.t
@@ -44,7 +44,7 @@ if ($^O ne 'MSWin32' && $^O ne 'VMS') {
     ($name, $home) = (getpwuid($>))[0,7];
     1;
   } and do {
-    @a = File::Glob::glob("~$name", GLOB_TILDE);
+    @a = bsd_glob("~$name", GLOB_TILDE);
     if (scalar(@a) != 1 || $a[0] ne $home || GLOB_ERROR) {
        print "not ";
     }
@@ -54,7 +54,7 @@ print "ok 3\n";
 
 # check backslashing
 # should return a list with one item, and not set ERROR
-@a = File::Glob::glob('TEST', GLOB_QUOTE);
+@a = bsd_glob('TEST', GLOB_QUOTE);
 if (scalar @a != 1 || $a[0] ne 'TEST' || GLOB_ERROR) {
     local $/ = "][";
     print "# [@a]\n";
@@ -65,7 +65,7 @@ print "ok 4\n";
 # check nonexistent checks
 # should return an empty list
 # XXX since errfunc is NULL on win32, this test is not valid there
-@a = File::Glob::glob("asdfasdf", 0);
+@a = bsd_glob("asdfasdf", 0);
 if ($^O ne 'MSWin32' and scalar @a != 0) {
     print "# |@a|\nnot ";
 }
@@ -81,7 +81,7 @@ if ($^O eq 'mpeix' or $^O eq 'MSWin32' or $^O eq 'os2' or $^O eq 'VMS'
 else {
     $dir = "PtEeRsLt.dir";
     mkdir $dir, 0;
-    @a = File::Glob::glob("$dir/*", GLOB_ERR);
+    @a = bsd_glob("$dir/*", GLOB_ERR);
     #print "\@a = ", array(@a);
     rmdir $dir;
     if (scalar(@a) != 0 || GLOB_ERROR == 0) {
@@ -91,13 +91,13 @@ else {
 }
 
 # check for csh style globbing
-@a = File::Glob::glob('{a,b}', GLOB_BRACE | GLOB_NOMAGIC);
+@a = bsd_glob('{a,b}', GLOB_BRACE | GLOB_NOMAGIC);
 unless (@a == 2 and $a[0] eq 'a' and $a[1] eq 'b') {
     print "not ";
 }
 print "ok 7\n";
 
-@a = File::Glob::glob(
+@a = bsd_glob(
     '{TES*,doesntexist*,a,b}',
     GLOB_BRACE | GLOB_NOMAGIC | ($^O eq 'VMS' ? GLOB_NOCASE : 0)
 );
@@ -112,7 +112,7 @@ print "ok 8\n";
 
 # "~" should expand to $ENV{HOME}
 $ENV{HOME} = "sweet home";
-@a = File::Glob::glob('~', GLOB_TILDE | GLOB_NOMAGIC);
+@a = bsd_glob('~', GLOB_TILDE | GLOB_NOMAGIC);
 unless (@a == 1 and $a[0] eq $ENV{HOME}) {
     print "not ";
 }

diff --git a/t/lib/glob-case.t b/t/lib/glob-case.t
index 32719b2..3d5c816 100755 (executable)
--- a/t/lib/glob-case.t
+++ b/t/lib/glob-case.t
@@ -30,7 +30,7 @@ print "not " unless @a == 0;
 print "ok 3\n";
 
 # Test the explicit use of the GLOB_NOCASE flag
-@a = File::Glob::glob("lib/G*.t", GLOB_NOCASE);
+@a = bsd_glob("lib/G*.t", GLOB_NOCASE);
 print "not " unless @a >= 3;
 print "ok 4\n";
 
@@ -47,7 +47,7 @@ else {
     rmdir "[]";
     print "# returned @a\nnot " unless @a == 1;
     print "ok 6\n";
-    @a = File::Glob::glob("lib\\*", GLOB_QUOTE);
+    @a = bsd_glob("lib\\*", GLOB_QUOTE);
     print "not " if @a == 0;
     print "ok 7\n";
 }

diff --git a/t/lib/glob-taint.t b/t/lib/glob-taint.t
index a8dc213..586357f 100755 (executable)
--- a/t/lib/glob-taint.t
+++ b/t/lib/glob-taint.t
@@ -18,7 +18,7 @@ $loaded = 1;
 print "ok 1\n";
 
 # all filenames should be tainted
-@a = File::Glob::glob("*");
+@a = File::Glob::bsd_glob("*");
 eval { $a = join("",@a), kill 0; 1 };
 unless ($@ =~ /Insecure dependency/) {
     print "not ";