| Subject: | Documentation error: remove_tree(), rmtree() do accept files as arguments |
| Date: | Sat, 29 Jul 2017 22:21:49 -0400 |
| To: | bug-File-Path [...] rt.cpan.org |
| From: | James E Keenan <jkeenan [...] pobox.com> |
In commit 4b54a837 in mid-2015 a statement was added to the
documentation for File::Path::remove_tree() which erroneously claimed
that remove_tree() accepted only directories:
#####
diff --git a/lib/File/Path.pm b/lib/File/Path.pm
index 3ee17bc..4e8fd8a 100644
--- a/lib/File/Path.pm
+++ b/lib/File/Path.pm
@@ -717,11 +717,14 @@ return value of the function is otherwise
identical to make_path().
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 the Windows commands C<rmdir /s> and C<rd /s>.
+command C<rm -r> or the Windows commands C<rmdir /s> and C<rd /s>. The
+only exception to the function similarity is C<remove_tree> accepts
+only directories whereas C<rm -r> also accepts files.
#####
While remove_tree() and rmtree() suggest by their names that directories
are their intended arguments, the code has never enforced a prohibition
on passing non-directory filesystem entries as arguments. Indeed,
t/Path.t has long contained the following code:
#####
my $file_name = catfile( $tmp_base, 'a', 'delete.me' );
my $file_count = 0;
if (open OUT, "> $file_name") {
print OUT "this file may be deleted\n";
close OUT;
++$file_count;
}
else {
diag( "Failed to create file $file_name: $!" );
}
SKIP: {
skip "cannot remove a file we failed to create", 1
unless $file_count == 1;
my $count = rmtree($file_name);
is($count, 1, "rmtree'ed a file");
}
#####
Other code blocks in t/Path.t demonstrate that symlinks can be passed as
arguments to these functions.
The documentation should change to reflect the actual behavior.
Thank you very much.
Jim Keenan