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

1 files changed, 39 insertions, 20 deletions

diff --git a/ext/File/Glob/Glob.pm b/ext/File/Glob/Glob.pm
index 4b7e54b9e3..1353d4ffc6 100644
--- 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.