Re: [PATCH] 5.6 File::Glob documentation insufficient for use

Message-Id: <200503300141.j2U1f3EP024524@accognoscere.homeunix.org>

p4raw-id: //depot/perl@24097

diff --git a/ext/File/Glob/Glob.pm b/ext/File/Glob/Glob.pm
index f69754c..ac6eaaf 100644 (file)
--- a/ext/File/Glob/Glob.pm
+++ b/ext/File/Glob/Glob.pm
@@ -56,7 +56,7 @@ use XSLoader ();
     ) ],
 );
 
-$VERSION = '1.03';
+$VERSION = '1.04';
 
 sub import {
     require Exporter;
@@ -195,8 +195,10 @@ File::Glob - Perl extension for BSD glob routine
 =head1 SYNOPSIS
 
   use File::Glob ':glob';
+  
   @list = bsd_glob('*.[ch]');
   $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
+  
   if (GLOB_ERROR) {
     # an error occurred reading $homedir
   }
@@ -204,18 +206,26 @@ File::Glob - Perl extension for BSD glob routine
   ## 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}>
+  my @sources = <*.{c,h,y}>;
 
   ## override the core glob, forcing case sensitivity
   use File::Glob qw(:globally :case);
-  my @sources = <*.{c,h,y}>
+  my @sources = <*.{c,h,y}>;
 
   ## override the core glob forcing case insensitivity
   use File::Glob qw(:globally :nocase);
-  my @sources = <*.{c,h,y}>
+  my @sources = <*.{c,h,y}>;
+  
+  ## glob on all files in home directory
+  use File::Glob ':globally';
+  my @sources = <~gnat/*>;
 
 =head1 DESCRIPTION
 
+The glob angle-bracket operator <> is a pathname generator that implements the 
+rules for file name pattern matching used by Unix-like shells such as the 
+Bourne shell or C shell.
+
 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
@@ -229,6 +239,22 @@ 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.
 
+=head2 META CHARACTERS
+
+  \       Quote the next metacharacter
+  []      Character class              
+  {}      Multiple pattern
+  *       Match any string of characters
+  ?       Match any single character
+  ~       User name home directory
+  
+The metanotation ``a{b,c,d}e'' is a shorthand for ``abe ace ade''.  Left
+to right order is preserved, with results of matches being sorted sepa-
+rately at a low level to preserve this order. As a special case `{', `}', 
+and `{}' are passed undisturbed.
+
+=head2 POSIX FLAGS
+
 The POSIX defined flags for bsd_glob() are:
 
 =over 4
@@ -423,6 +449,10 @@ question doesn't contain any colons (e.g. 'lib' becomes ':lib:').
 
 =back
 
+=head1 SEE ALSO
+
+L<perlfunc/glob>, glob(3)
+
 =head1 AUTHOR
 
 The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>,