oracular (3) File::Copy::Recursive::Reduced.3pm.gz
NAME
File::Copy::Recursive::Reduced - Recursive copying of files and directories within Perl 5 toolchain
SYNOPSIS
use File::Copy::Recursive::Reduced qw(fcopy dircopy);
fcopy($orig,$new) or die $!;
dircopy($orig,$new) or die $!;
DESCRIPTION
This library is intended as a not-quite-drop-in replacement for certain functionality provided by CPAN
distribution File-Copy-Recursive <http://search.cpan.org/dist/File-Copy-Recursive/>. The library
provides methods similar enough to that distribution's fcopy(), dircopy() and rcopy() functions to be
usable in those CPAN distributions often described as being part of the Perl toolchain.
Rationale
File::Copy::Recursive (hereinafter referred to as FCR) is heavily used in other CPAN libraries. Out of
over 30,000 other CPAN distributions studied in early 2018, it ranks by one calculation as the 129th
highest distribution in terms of its total direct and indirect reverse dependencies. In current
parlance, it sits "high upstream on the CPAN river." Hence, it ought to work correctly and be
installable on all operating systems where Perl is well supported.
However, as of early April 2018, FCR version 0.40 wass failing to pass its tests against either Perl 5.26
or Perl 5 blead on important operating systems including Windows, FreeBSD and NetBSD
(<http://fast-matrix.cpantesters.org/?dist=File-Copy-Recursive%200.40>). As a consequence, CPAN
installers such as cpan and cpanm were failing to install it (unless one resorted to the "--force"
option). This prevented distributions dependent (directly or indirectly) on FCR from being installed as
well.
Some patches had been provided to the FCR bug tracker <https://rt.cpan.org/Dist/Display.html?Name=File-
Copy-Recursive> for this problem. However, as late as April 18 2018 those patches had not yet been
applied. This posed a critical problem for the ability to assess the impact of the soon-to-be-released
perl-5.28.0 on CPAN distributions (the so-called "Blead Breaks CPAN" ("BBC") problem) on platforms other
than Linux.
File::Copy::Recursive::Reduced (hereinafter referred to as FCR2) is intended to provide a minimal subset
of FCR's functionality -- just enough to get the Perl toolchain working on the platforms where FCR is
currently failing. Functions will be added to FCR2 only insofar as investigation shows that they can
replace usage of FCR functions in toolchain and other heavily used modules. No attempt will be made to
reproduce all the functionality currently provided or claimed to be provided by FCR.
On April 19 2018, FCR's author, Daniel Muey, released version 0.41 to CPAN. This version included a
patch submitted by Tom Hukins which corrected the problem addressed by FCR2. FCR once again built and
tested correctly on FreeBSD. That meant that its 6000-plus reverse dependencies can once again be
reached by cpan and other installers. That in turn means that we can conduct exhaustive BBC
investigations on FreeBSD and other platforms.
With that correction in FCR, the original rationale for FCR2 has been superseded. I will continue to
maintain the code and respond to bug reports, but am suspending active development. I now deem FCR2
feature-complete.
SUBROUTINES
The current version of FCR2 provides three exportable and publicly supported subroutines partially
equivalent to the similarly named subroutines exported by FCR.
fcopy()
• Purpose
A stripped-down replacement for File::Copy::Recursive::fcopy().
Copies a file to a new location, recursively creating directories as needed. Does not copy
directories. Unlike File::Copy::copy(), fcopy() attempts to preserve the mode of the original file.
• Arguments
fcopy($orig, $new) or die $!;
List of two required arguments:
• Absolute path to the file being copied; and
• Absolute path to the location to which the file is being copied.
Four cases should be noted:
1 Create copy within same directory but new basename
fcopy('/path/to/filename', '/path/to/newfile');
The second argument must be the absolute path to the new file. (Otherwise the file will be
created in the current working directory, which is almost certainly what you do not want.)
2 Create copy within different, already existing directory, same basename
fcopy('/path/to/filename', '/path/to/existing/directory');
The second argument can be merely the path to the existing directory; will create
/path/to/existing/directory/filename.
3 Create copy within different, not yet existing directory, same basename
fcopy('/path/to/filename', '/path/not/yet/existing/directory/filename');
The second argument will be interpreted as the complete path to the newly created file. The
basename must be included even if it is the same as in the first argument. Will create
/path/not/yet/existing/directory/filename.
4 Create copy within different, not yet existing directory, different basename
fcopy('/path/to/filename', '/path/not/yet/existing/directory/newfile');
The second argument will be interpreted as the complete path to the newly created file. Will
create /path/not/yet/existing/directory/newfile.
• Return Value
Returns 1 upon success; 0 upon failure. Returns an undefined value if, for example, function cannot
validate arguments.
• Comment
Since fcopy() internally uses File::Copy::copy() to perform the copying, the arguments are subject to
the same qualifications as that function's arguments. Call perldoc File::Copy for discussion of
those arguments.
dircopy()
• Purpose
A stripped-down replacement for File::Copy::Recursive::dircopy().
Given the path to the directory specified by the first argument, the function copies all of the files
and directories beneath it to the directory specified by the second argument.
• Arguments
my $count = dircopy($orig, $new);
warn "dircopy() returned undefined value" unless defined $count;
• Return Value
Upon completion, returns the count of directories and files created -- which might be 0.
Should the function not complete (but not "die"), an undefined value will be returned. That
generally indicates problems with argument validation. This approach is taken for consistency with
File::Copy::Recursive::dircopy().
In list context the return value is a one-item list holding the same value as returned in scalar
context. The three-item list return value of File::Copy::Recursive::dircopy() is not supported.
• Restrictions
None of "File::Copy::Recursive::dircopy"'s bells and whistles. No guaranteed preservation of file or
directory modes. No restriction on maximum depth. No nothing; this is fine-tuned to the needs of
Perl toolchain modules and their test suites.
rcopy()
• Purpose
A stripped-down replacement for File::Copy::Recursive::rcopy(). As is the case with that FCR
function, rcopy() is more or less a wrapper around fcopy() or dircopy(), depending on the nature of
the first argument.
• Arguments
rcopy($orig, $new) or die $!;
List of two required arguments:
• Absolute path to the entity (file or directory) being copied; and
• Absolute path to the location to which the entity is being copied.
• Return Value
Returns 1 upon success; 0 upon failure. Returns an undefined value if, for example, function cannot
validate arguments.
• Comment
Please read the documentation for fcopy() or dircopy(), depending on the nature of the first
argument.
File::Copy::Recursive Subroutines Not Supported in File::Copy::Recursive::Reduced
As of the current version, FCR2 has no publicly documented, exportable subroutines equivalent to the
following FCR exportable subroutines:
rcopy_glob
fmove
rmove
rmove_glob
dirmove
pathempty
pathrm
pathrmdir
Consideration is being given to supporting rcopy().
BUGS AND SUPPORT
Please report any bugs by mail to "bug-File-Copy-Recursive-Reduced@rt.cpan.org" or through the web interface at <http://rt.cpan.org>.
ACKNOWLEDGEMENTS
Notwithstanding the fact that this distribution is being released to address certain problems in File-
Copy-Recursive, credit must be given to FCR author Daniel Muey
<http://www.cpan.org/authors/id/D/DM/DMUEY/> for ingenious conception and execution. The implementation
of the subroutines provided by FCR2 follows that found in FCR to a significant extent.
Thanks also to Tom Hukins for supplying the patch which corrects FCR's problems and which has been
incorporated into FCR2 as well.
Thanks to Håkon Hægland for paying attention to how this library performs on Windows and other platforms
to which the author does not have access.
AUTHOR
James E Keenan
CPAN ID: JKEENAN
jkeenan@cpan.org
http://thenceforward.net/perl
COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.
The full text of the license can be found in the LICENSE file included with this module.
Copyright James E Keenan 2018-2023. All rights reserved.
SEE ALSO
perl(1). File::Copy::Recursive(3).