NAME

File::Copy::Recursive::Reduced - Recursive copying of files and directories within Perl 5 toolchain

SYNOPSIS

    use File::Copy::Recursive::Reduced;

    my $self = File::Copy::Recursive::Reduced->new({});
    $self->fcopy($orig,$new[,$buf]) or die $!;
    $self->dircopy($orig,$new[,$buf]) 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, it ranks, by one estimate, as the 129th highest distribution in terms of number of direct and indirect reverse dependencies. Hence, it has 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 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). CPAN installers such as cpan and cpanm will not install it without resort to --force options and will prevent distributions dependent on FCR from being installed as well. Some patches have been provided to the FCR bug tracker for certain problems but FCR's author has not yet applied them. Even if, however, those patches are applied, FCR may not install on certain platforms.

File::Copy::Recursive::Reduced (hereinafter referred to as FCR2) is intended to provide little more than a minimal subset of FCR's functionality, that is, just enough to get the Perl toolchain working on the platforms where FCR is currently failing. Methods will be added to FCR2 only insofar as investigation shows that they can replace usage of FCR functions in Toolchain modules. No attempt will be made to reproduce all the functionality currently provided or claimed to be provided by FCR.

METHODS

The current version of FCR2 provides a constructor and two public methods partially equivalent to the similarly named functions exported by FCR.

new()

• Purpose

  File::Copy::Recursive::Reduced constructor.

• Arguments

      $self = File::Copy::Recursive::Reduced->new({});

  If an argument is provided, it must be a hash reference. Valid keys for that hashref are:

  • PFSCheck

    On by default; provide a Perl-false value to turn off.

  • KeepMode

    On by default; provide a Perl-false value to turn off.

  • MaxDepth

    Off by default; provide a positive integer to set the maximum depth to which a directory structure is recursed during dircopy().

  • debug

    Off by default; provide a Perl-true value to turn off.

• Return Value

  File::Copy::Recursive::Reduced object.

• Comment

fcopy()

• Purpose

  Copy 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

      $self->fcopy($orig,$new[,$buf]) or die $!;

  Takes three arguments, the first two required, the third optional.

  1 The file to be copied.

  2 Path where copy is to be created.

  3 Buffer size: the number of bytes from the first file which will be held in memory at any given time before being written to the second file.

  Since fcopy() internally uses File::Copy::copy() to perform the copying, the arguments are subject to the same qualifications as that function. Call perldoc File::Copy for discussion of those arguments.

• Return Value

  Scalar context: returns 1 upon success; 0 upon failure.

  List context: returns a 3-element list: (1,0,0) upon success; 0,0,0) upon failure.

• Comments

  • Unlike FCR's fcopy(), this method provides no functionality to remove an already existing target file before copying.

  • TODO

    • Decide status of $File::Copy::Recursive::BdTrgWrn.

      At present, I'm not implementing it -- at least not for fcopy().

dircopy()

• Purpose

  Recursively traverse a directory and recursively copy it to a new directory.

• Arguments

  Scalar context:

      my $num_of_files_and_dirs = $self->dircopy($orig,$new[,$buf]) or die $!;

  List context:

      my ($num_of_files_and_dirs,$num_of_dirs,$depth_traversed) =
          $self->dircopy($orig,$new[,$buf]) or die $!;

• Return Value

  Scalar context: Returns the number of files and directories copied.

  List context: Returns a 3-element list:

  1 Number of files and directories copied;

  2 Number of directories (only) copied;

  3 Depth level traversed.

• Comment

  • The dircopy() method creates intermediate directories as needed. By default it attempts to preserve the modes of all files and directories. In addition, by default it copies all the way down into the directory.

    Error conditions: TK

  • Unlike FCR's dircopy(), this method provides no functionality to remove already existing directories or files before copying ($RMTrgDir).

  • Unlike FCR's dircopy(), this method provides no functionality to continue on regardless of the failure to copy an individual directory or file (for instance, because of inadequate permissions) ($SkipFlob).

File::Copy::Recursive Subroutines Not Supported in File::Copy::Recursive::Reduced

As of the current version, FCR2 has no publicly documented methods equivalent to the following FCR exportable subroutines:

    rcopy
    rcopy_glob
    fmove
    rmove
    rmove_glob
    dirmove
    pathempty
    pathrm
    pathrmdir

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

TK

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