This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to File::Path 2.06_07. (an e-mail from David)
authorNicholas Clark <nick@ccl4.org>
Wed, 29 Oct 2008 16:50:40 +0000 (16:50 +0000)
committerNicholas Clark <nick@ccl4.org>
Wed, 29 Oct 2008 16:50:40 +0000 (16:50 +0000)
p4raw-id: //depot/perl@34637

lib/File/Path.pm

index a622ac7..e759cb0 100644 (file)
@@ -17,7 +17,7 @@ BEGIN {
 
 use Exporter ();
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
 
 use Exporter ();
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
-$VERSION   = '2.06_06';
+$VERSION   = '2.06_07';
 @ISA     = qw(Exporter);
 @EXPORT  = qw(mkpath rmtree);
 @EXPORT_OK = qw(make_path remove_tree);
 @ISA     = qw(Exporter);
 @EXPORT  = qw(mkpath rmtree);
 @EXPORT_OK = qw(make_path remove_tree);
@@ -55,12 +55,12 @@ sub _error {
 }
 
 sub make_path {
 }
 
 sub make_path {
-    push @_, {} if !@_ or (@_ and !UNIVERSAL::isa($_[-1],'HASH'));
+    push @_, {} unless @_ and UNIVERSAL::isa($_[-1],'HASH');
     goto &mkpath;
 }
 
 sub mkpath {
     goto &mkpath;
 }
 
 sub mkpath {
-    my $old_style = !(@_ > 0 and UNIVERSAL::isa($_[-1],'HASH'));
+    my $old_style = !(@_ and UNIVERSAL::isa($_[-1],'HASH'));
 
     my $arg;
     my $paths;
 
     my $arg;
     my $paths;
@@ -69,12 +69,11 @@ sub mkpath {
         my ($verbose, $mode);
         ($paths, $verbose, $mode) = @_;
         $paths = [$paths] unless UNIVERSAL::isa($paths,'ARRAY');
         my ($verbose, $mode);
         ($paths, $verbose, $mode) = @_;
         $paths = [$paths] unless UNIVERSAL::isa($paths,'ARRAY');
-        $arg->{verbose} = defined $verbose ? $verbose : 0;
+        $arg->{verbose} = $verbose;
         $arg->{mode}    = defined $mode    ? $mode    : 0777;
     }
     else {
             $arg = pop @_;
         $arg->{mode}    = defined $mode    ? $mode    : 0777;
     }
     else {
             $arg = pop @_;
-        $arg->{verbose} ||= 0;
         $arg->{mode}      = delete $arg->{mask} if exists $arg->{mask};
             $arg->{mode} = 0777 unless exists $arg->{mode};
             ${$arg->{error}} = [] if exists $arg->{error};
         $arg->{mode}      = delete $arg->{mask} if exists $arg->{mask};
             $arg->{mode} = 0777 unless exists $arg->{mode};
             ${$arg->{error}} = [] if exists $arg->{error};
@@ -125,12 +124,12 @@ sub _mkpath {
 }
 
 sub remove_tree {
 }
 
 sub remove_tree {
-    push @_, {} if !@_ or (@_ and !UNIVERSAL::isa($_[-1],'HASH'));
+    push @_, {} unless @_ and UNIVERSAL::isa($_[-1],'HASH');
     goto &rmtree;
 }
 
 sub rmtree {
     goto &rmtree;
 }
 
 sub rmtree {
-    my $old_style = !(@_ > 0 and UNIVERSAL::isa($_[-1],'HASH'));
+    my $old_style = !(@_ and UNIVERSAL::isa($_[-1],'HASH'));
 
     my $arg;
     my $paths;
 
     my $arg;
     my $paths;
@@ -138,7 +137,7 @@ sub rmtree {
     if ($old_style) {
         my ($verbose, $safe);
         ($paths, $verbose, $safe) = @_;
     if ($old_style) {
         my ($verbose, $safe);
         ($paths, $verbose, $safe) = @_;
-        $arg->{verbose} = defined $verbose ? $verbose : 0;
+        $arg->{verbose} = $verbose;
         $arg->{safe}    = defined $safe    ? $safe    : 0;
 
         if (defined($paths) and length($paths)) {
         $arg->{safe}    = defined $safe    ? $safe    : 0;
 
         if (defined($paths) and length($paths)) {
@@ -150,14 +149,9 @@ sub rmtree {
         }
     }
     else {
         }
     }
     else {
-        if (@_ > 0 and UNIVERSAL::isa($_[-1],'HASH')) {
             $arg = pop @_;
             ${$arg->{error}}  = [] if exists $arg->{error};
             ${$arg->{result}} = [] if exists $arg->{result};
             $arg = pop @_;
             ${$arg->{error}}  = [] if exists $arg->{error};
             ${$arg->{result}} = [] if exists $arg->{result};
-        }
-        else {
-            @{$arg}{qw(verbose safe)} = (0, 0);
-        }
         $paths = [@_];
     }
 
         $paths = [@_];
     }
 
@@ -398,79 +392,65 @@ File::Path - Create or remove directory trees
 
 =head1 VERSION
 
 
 =head1 VERSION
 
-This document describes version 2.06_06 of File::Path, released
-2008-10-05.
+This document describes version 2.06_07 of File::Path, released
+2008-10-29.
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 
-    use File::Path;
+  use File::Path qw(make_path remove_tree);
 
 
-    # modern
-  make_path( 'foo/bar/baz', '/zug/zwang' );
-  # or
-    mkpath( 'foo/bar/baz', '/zug/zwang', {verbose => 1} );
+  make_path('foo/bar/baz', '/zug/zwang');
+  make_path('foo/bar/baz', '/zug/zwang', {
+      verbose => 1,
+      mode => 0711,
+  });
 
 
-    rmtree(
-        'foo/bar/baz', '/zug/zwang',
-        { verbose => 1, error  => \my $err_list }
-    );
-  # or
-  remove_tree( 'foo/bar/baz', '/zug/zwang' );
+  remove_tree('foo/bar/baz', '/zug/zwang');
+  remove_tree('foo/bar/baz', '/zug/zwang', {
+      verbose => 1,
+      error  => \my $err_list,
+  });
 
 
-    # traditional
+  # legacy (interface promoted before v2.0)
+  mkpath('/foo/bar/baz');
+  mkpath('/foo/bar/baz', 1, 0711);
     mkpath(['/foo/bar/baz', 'blurfl/quux'], 1, 0711);
     mkpath(['/foo/bar/baz', 'blurfl/quux'], 1, 0711);
+  rmtree('foo/bar/baz', 1, 1);
     rmtree(['foo/bar/baz', 'blurfl/quux'], 1, 1);
 
     rmtree(['foo/bar/baz', 'blurfl/quux'], 1, 1);
 
-=head1 DESCRIPTION
-
-The C<mkpath> function provides a convenient way to create directories
-of arbitrary depth. Similarly, the C<rmtree> function provides a
-convenient way to delete an entire directory subtree from the
-filesystem, much like the Unix command C<rm -r> or C<del /s> on
-Windows.
-
-There are two further functions, C<make_path> and C<remove_tree>
-that perform the same task and offer a more intuitive interface.
-
-=head2 FUNCTIONS
+  # legacy (interface promoted before v2.6)
+  mkpath('foo/bar/baz', '/zug/zwang', { verbose => 1, mode => 0711 });
+  rmtree('foo/bar/baz', '/zug/zwang', { verbose => 1, mode => 0711 });
 
 
-The modern way of calling C<mkpath> and C<rmtree> is with a list
-of directories to create, or remove, respectively, followed by a
-hash reference containing keys to control the function's behaviour.
+=head1 DESCRIPTION
 
 
-=head3 C<make_path>
+This module provide a convenient way to create directories of
+arbitrary depth and to delete an entire directory subtree from the
+filesystem.
 
 
-The C<make_path> routine accepts a list of directories to be
-created. Its behaviour may be tuned by an optional hashref
-appearing as the last parameter on the call.
+The following functions are provided:
 
 
-  my @created = make_path(qw(/tmp /flub /home/nobody));
-  print "created $_\n" for @created;
+=over
 
 
-The function returns the list of files actually created during the
-call.
+=item make_path( $dir1, $dir2, .... )
 
 
-=head3 C<mkpath>
+=item make_path( $dir1, $dir2, ...., \%opts )
 
 
-The C<mkpath> routine will recognise a final hashref in the
-same manner as C<make_path>. If no hashref is present, the
-parameters are interpreted according to the traditional interface
-(see below).
+The C<make_path> function creates the given directories if they don't
+exists before, much like the Unix command C<mkdir -p>.
 
 
-  my @created = mkpath(
-    qw(/tmp /flub /home/nobody),
-    {verbose => 1, mode => 0750},
-  );
-  print "created $_\n" for @created;
+The function accepts a list of directories to be created. Its
+behaviour may be tuned by an optional hashref appearing as the last
+parameter on the call.
 
 The function returns the list of directories actually created during
 
 The function returns the list of directories actually created during
-the call.
+the call; in scalar context the number of directories created.
 
 
-The following keys are recognised:
+The following keys are recognised in the option hash:
 
 
-=over 4
+=over
 
 
-=item mode
+=item mode => $num
 
 The numeric permissions mode to apply to each created directory
 (defaults to 0777), to be modified by the current C<umask>. If the
 
 The numeric permissions mode to apply to each created directory
 (defaults to 0777), to be modified by the current C<umask>. If the
@@ -479,14 +459,15 @@ the permissions will not be modified.
 
 C<mask> is recognised as an alias for this parameter.
 
 
 C<mask> is recognised as an alias for this parameter.
 
-=item verbose
+=item verbose => $bool
 
 If present, will cause C<mkpath> to print the name of each directory
 as it is created. By default nothing is printed.
 
 
 If present, will cause C<mkpath> to print the name of each directory
 as it is created. By default nothing is printed.
 
-=item error
+=item error => \$err
 
 
-If present, will be interpreted as a reference to a list, and will
+If present, it should be a reference to a scalar.
+This scalar will be made to reference an array, which will
 be used to store any errors that are encountered.  See the ERROR
 HANDLING section for more information.
 
 be used to store any errors that are encountered.  See the ERROR
 HANDLING section for more information.
 
@@ -496,32 +477,40 @@ in an C<eval> block.
 
 =back
 
 
 =back
 
-=head3 C<remove_tree>
+=item mkpath( $dir, $verbose, $mode )
 
 
-The C<remove_tree> routine accepts a list of directories to be
-removed. Its behaviour may be tuned by an optional hashref
-appearing as the last parameter on the call.
+=item mkpath( [$dir1, $dir2,...], $verbose, $mode )
 
 
-  remove_tree( 'this/dir', 'that/dir' );
+=item mkpath( $dir1, $dir2,..., \%opt )
 
 
-=head3 C<rmtree>
+The mkpath() function provide the legacy interface with a different
+interpretation of the arguments passed.  This function also returns
+the list of directories actually created during the call.
 
 
-The C<rmtree> routine will recognise a final hashref in the
-same manner as C<remove_tree>. If no hashref is present, the
-parameters are interpreted according to the traditional interface.
+=item remove_tree( $dir1, $dir2, .... )
 
 
-  rmtree( 'mydir', 1 );                 # traditional
-  rmtree( ['mydir'], 1 );               # traditional
-  rmtree( 'mydir', 1, {verbose => 0} ); # modern
+=item remove_tree( $dir1, $dir2, ...., \%opts )
 
 
-=over 4
+The C<remove_tree> function deletes the given directories and any
+files and subdirectories they might contain, much like the Unix
+command C<rm -r> or C<del /s> on Windows.
+
+The function accepts a list of directories to be
+removed. Its behaviour may be tuned by an optional hashref
+appearing as the last parameter on the call.
+
+The functions returns the number of files successfully deleted.
+
+The following keys are recognised in the option hash:
 
 
-=item verbose
+=over
+
+=item verbose => $bool
 
 If present, will cause C<rmtree> to print the name of each file as
 it is unlinked. By default nothing is printed.
 
 
 If present, will cause C<rmtree> to print the name of each file as
 it is unlinked. By default nothing is printed.
 
-=item safe
+=item safe => $bool
 
 When set to a true value, will cause C<rmtree> to skip the files
 for which the process lacks the required privileges needed to delete
 
 When set to a true value, will cause C<rmtree> to skip the files
 for which the process lacks the required privileges needed to delete
@@ -530,7 +519,7 @@ will make no attempt to alter file permissions. Thus, if the process
 is interrupted, no filesystem object will be left in a more
 permissive mode.
 
 is interrupted, no filesystem object will be left in a more
 permissive mode.
 
-=item keep_root
+=item keep_root => $bool
 
 When set to a true value, will cause all files and subdirectories
 to be removed, except the initially specified directories. This comes
 
 When set to a true value, will cause all files and subdirectories
 to be removed, except the initially specified directories. This comes
@@ -538,23 +527,24 @@ in handy when cleaning out an application's scratch directory.
 
   remove_tree( '/tmp', {keep_root => 1} );
 
 
   remove_tree( '/tmp', {keep_root => 1} );
 
-=item result
+=item result => \$res
 
 
-If present, will be interpreted as a reference to a list, and will
-be used to store the list of all files and directories unlinked
-during the call. If nothing is unlinked, a reference to an empty
-list is returned (rather than C<undef>).
+If present, it should be a reference to a scalar.
+This scalar will be made to reference an array, which will
+be used to store all files and directories unlinked
+during the call. If nothing is unlinked, a the array will be empty.
 
   remove_tree( '/tmp', {result => \my $list} );
   print "unlinked $_\n" for @$list;
 
 This is a useful alternative to the C<verbose> key.
 
 
   remove_tree( '/tmp', {result => \my $list} );
   print "unlinked $_\n" for @$list;
 
 This is a useful alternative to the C<verbose> key.
 
-=item error
+=item error => \$err
 
 
-If present, will be interpreted as a reference to a list,
-and will be used to store any errors that are encountered.
-See the ERROR HANDLING section for more information.
+If present, it should be a reference to a scalar.
+This scalar will be made to reference an array, which will
+be used to store any errors that are encountered.  See the ERROR
+HANDLING section for more information.
 
 Removing things is a much more dangerous proposition than
 creating things. As such, there are certain conditions that
 
 Removing things is a much more dangerous proposition than
 creating things. As such, there are certain conditions that
@@ -567,106 +557,19 @@ of hand. This is the safest course of action.
 
 =back
 
 
 =back
 
-=head2 TRADITIONAL INTERFACE
+=item rmtree( $dir )
 
 
-The old interfaces of C<mkpath> and C<rmtree> take a reference to
-a list of directories (to create or remove), followed by a series
-of positional, numeric, modal parameters that control their behaviour.
-If only one directory is being created or removed, a simple scalar
-may be used instead of the reference.
+=item rmtree( $dir, $verbose, $safe )
 
 
-  rmtree( ['dir1', 'dir2'], 0, 1 );
-  rmtree( 'dir3', 1, 1 );
+=item rmtree( [$dir1, $dir2,...], $verbose, $safe )
 
 
-This design made it difficult to add additional functionality, as
-well as posed the problem of what to do when the calling code only
-needs to set the last parameter. Even though the code doesn't care
-how the initial positional parameters are set, the programmer is
-forced to learn what the defaults are, and specify them.
-
-Worse, if it turns out in the future that it would make more sense
-to change the default behaviour of the first parameter (for example,
-to avoid a security vulnerability), all existing code will remain
-hard-wired to the wrong defaults.
-
-Finally, a series of numeric parameters are much less self-documenting
-in terms of communicating to the reader what the code is doing. Named
-parameters do not have this problem.
-
-In the traditional API, C<mkpath> takes three arguments:
-
-=over 4
-
-=item *
+=item rmtree( $dir1, $dir2,..., \%opt )
 
 
-The name of the path to create, or a reference to a list of paths
-to create,
-
-=item *
-
-a boolean value, which if TRUE will cause C<mkpath> to print the
-name of each directory as it is created (defaults to FALSE), and
-
-=item *
-
-the numeric mode to use when creating the directories (defaults to
-0777), to be modified by the current umask.
+The rmtree() function provide the legacy interface with a different
+interpretation of the arguments passed.
 
 =back
 
 
 =back
 
-It returns a list of all directories (including intermediates,
-determined using the Unix '/' separator) created. In scalar context
-it returns the number of directories created.
-
-If a system error prevents a directory from being created, then the
-C<mkpath> function throws a fatal error with C<Carp::croak>. This
-error can be trapped with an C<eval> block:
-
-  eval { mkpath($dir) };
-  if ($@) {
-    print "Couldn't create $dir: $@";
-  }
-
-In the traditional API, C<rmtree> takes three arguments:
-
-=over 4
-
-=item *
-
-the root of the subtree to delete, or a reference to a list of
-roots. All of the files and directories below each root, as well
-as the roots themselves, will be deleted. If you want to keep
-the roots themselves, you must use the modern API.
-
-=item *
-
-a boolean value, which if TRUE will cause C<rmtree> to print a
-message each time it examines a file, giving the name of the file,
-and indicating whether it's using C<rmdir> or C<unlink> to remove
-it, or that it's skipping it.  (defaults to FALSE)
-
-=item *
-
-a boolean value, which if TRUE will cause C<rmtree> to skip any
-files to which you do not have delete access (if running under VMS)
-or write access (if running under another OS). This will change
-in the future when a criterion for 'delete permission' under OSs
-other than VMS is settled.  (defaults to FALSE)
-
-=back
-
-C<rmtree> returns the number of files, directories and symlinks
-successfully deleted. Symlinks are simply deleted and not followed.
-
-Note also that the occurrence of errors in C<rmtree> using the
-traditional interface can be determined I<only> by trapping diagnostic
-messages using C<$SIG{__WARN__}>; it is not apparent from the return
-value. (The modern interface may use the C<error> parameter to
-record any problems encountered).
-
-It is not possible to invoke the C<keep_root> functionality through
-the traditional interface.
-
 =head2 ERROR HANDLING
 
 If C<mkpath> or C<rmtree> encounter an error, a diagnostic message
 =head2 ERROR HANDLING
 
 If C<mkpath> or C<rmtree> encounter an error, a diagnostic message