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.

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.  All rights reserved.

SEE ALSO

       perl(1). File::Copy::Recursive(3).