Integrate mainline

[p5sagit/p5-mst-13.2.git] / ext / File / Glob / Glob.pm

diff --git a/ext/File/Glob/Glob.pm b/ext/File/Glob/Glob.pm
index cad8131..1ae894f 100644 (file)
--- a/ext/File/Glob/Glob.pm
+++ b/ext/File/Glob/Glob.pm
@@ -31,6 +31,7 @@ use XSLoader ();
     GLOB_NOSPACE
     GLOB_QUOTE
     GLOB_TILDE
+    GLOB_UTF8
 );
 
 %EXPORT_TAGS = (
@@ -51,6 +52,7 @@ use XSLoader ();
         GLOB_NOSPACE
         GLOB_QUOTE
         GLOB_TILDE
+        GLOB_UTF8
         glob
         bsd_glob
     ) ],
@@ -62,10 +64,11 @@ sub import {
     require Exporter;
     my $i = 1;
     while ($i < @_) {
-       if ($_[$i] =~ /^:(case|nocase|globally)$/) {
+       if ($_[$i] =~ /^:(case|nocase|globally|utf8)$/) {
            splice(@_, $i, 1);
            $DEFAULT_FLAGS &= ~GLOB_NOCASE() if $1 eq 'case';
            $DEFAULT_FLAGS |= GLOB_NOCASE() if $1 eq 'nocase';
+           $DEFAULT_FLAGS |= GLOB_UTF8() if $1 eq 'utf8';
            if ($1 eq 'globally') {
                local $^W;
                *CORE::GLOBAL::glob = \&File::Glob::csh_glob;
@@ -203,15 +206,19 @@ 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}>;
+
+  ## override the core glob forcing UTF-8 names
+  use File::Glob qw(:globally :utf8);
+  my @sources = <*.{c,h,y}>;
 
 =head1 DESCRIPTION
 
@@ -321,6 +328,17 @@ order (case does not matter) rather than in ASCII order.
 
 =back
 
+The following flag has been added in the Perl implementation for
+Unicode compatibility:
+
+=over 4
+
+=item C<GLOB_UTF8>
+
+The filenames returned will be marked as being in UTF-8 encoding of
+Unicode.  Note that it is your responsibility to ascertain that the
+filesystem you are globbing in returns valid UTF-8 filenames.
+
 =head1 DIAGNOSTICS
 
 bsd_glob() returns a list of matching paths, possibly zero length.  If an
@@ -384,7 +402,7 @@ the standard Perl distribution.
 
 Mac OS (Classic) users should note a few differences. Since
 Mac OS is not Unix, when the glob code encounters a tilde glob (e.g.
-~user/foo) and the C<GLOB_TILDE> flag is used, it simply returns that
+~user) and the C<GLOB_TILDE> flag is used, it simply returns that
 pattern without doing any expansion.
 
 Glob on Mac OS is case-insensitive by default (if you don't use any
@@ -397,6 +415,29 @@ always begins with a volume name, a relative pathname should always
 begin with a ':'.  If specifying a volume name only, a trailing ':' is
 required.
 
+The specification of pathnames in glob patterns adheres to the usual Mac
+OS conventions: The path separator is a colon ':', not a slash '/'. A
+full path always begins with a volume name. A relative pathname on Mac
+OS must always begin with a ':', except when specifying a file or
+directory name in the current working directory, where the leading colon
+is optional. If specifying a volume name only, a trailing ':' is
+required. Due to these rules, a glob like E<lt>*:E<gt> will find all
+mounted volumes, while a glob like E<lt>*E<gt> or E<lt>:*E<gt> will find
+all files and directories in the current directory.
+
+Note that updirs in the glob pattern are resolved before the matching begins,
+i.e. a pattern like "*HD:t?p::a*" will be matched as "*HD:a*". Note also,
+that a single trailing ':' in the pattern is ignored (unless it's a volume
+name pattern like "*HD:"), i.e. a glob like E<lt>:*:E<gt> will find both
+directories I<and> files (and not, as one might expect, only directories).
+You can, however, use the C<GLOB_MARK> flag to distinguish (without a file
+test) directory names from file names.
+
+If the C<GLOB_MARK> flag is set, all directory paths will have a ':' appended.
+Since a directory like 'lib:' is I<not> a valid I<relative> path on Mac OS,
+both a leading and a trailing colon will be added, when the directory name in
+question doesn't contain any colons (e.g. 'lib' becomes ':lib:').
+
 =back
 
 =head1 AUTHOR