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. The library provides methods similar enough to that distribution's fcopy() and dircopy() 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 in 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 the time of creation of File::Copy::Recursive::Reduced (April 2018), FCR version 0.40 is 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 will not install it without use of the --force option. This will prevent distributions dependent on FCR from being installed as well. Some patches have been provided to the FCR bug tracker for this problem but as of the date on which this distribution is being uploaded to CPAN, FCR's author has not yet applied them. However, even if those patches are applied, FCR may face other installability problems on certain platforms.

File::Copy::Recursive::Reduced (hereinafter referred to as FCR2) is intended to provide an almost 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.

SUBROUTINES

The current version of FCR2 provides two 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.

• Restrictions

  • Does not currently handle copying of symlinks, though it may do so in a future version.

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().

• Restrictions

  None of File::Copy::Recursive::dircopy's bells and whistles. No provision for special handling of symlinks. No 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.

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
    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 for ingenious conception and execution. The implementation of the subroutines provided by FCR2 follows that found in FCR to a significant extent.

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).

cpanm File::Copy::Recursive::Reduced

perl -MCPAN -e shell
install File::Copy::Recursive::Reduced