.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "File::Copy::Recursive::Reduced 3pm"
.TH File::Copy::Recursive::Reduced 3pm "2018-07-15" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::Copy::Recursive::Reduced \- Recursive copying of files and directories within Perl 5 toolchain
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use File::Copy::Recursive::Reduced qw(fcopy dircopy);
\&
\&    fcopy($orig,$new) or die $!;
\&
\&    dircopy($orig,$new) or die $!;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This library is intended as a not-quite-drop-in replacement for certain
functionality provided by \s-1CPAN\s0 distribution
File-Copy-Recursive <http://search.cpan.org/dist/File-Copy-Recursive/>.  The
library provides methods similar enough to that distribution's \f(CW\*(C`fcopy()\*(C'\fR,
\&\f(CW\*(C`dircopy()\*(C'\fR and \f(CW\*(C`rcopy()\*(C'\fR functions to be usable in those \s-1CPAN\s0 distributions
often described as being part of the Perl toolchain.
.SS "Rationale"
.IX Subsection "Rationale"
\&\fIFile::Copy::Recursive\fR (hereinafter referred to as \fB\s-1FCR\s0\fR) is heavily used
in other \s-1CPAN\s0 libraries.  Out of over 30,000 other \s-1CPAN\s0 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 \f(CW\*(C`high upstream on the CPAN river.\*(C'\fR  Hence, it ought to work
correctly and be installable on all operating systems where Perl is well
supported.
.PP
However, as of early April 2018, \s-1FCR\s0 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, \s-1CPAN\s0 installers such as \fIcpan\fR and \fIcpanm\fR were failing to
install it (unless one resorted to the \f(CW\*(C`\-\-force\*(C'\fR option).  This prevented
distributions dependent (directly or indirectly) on \s-1FCR\s0 from being installed
as well.
.PP
Some patches had been provided to the \s-1FCR\s0 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 \s-1CPAN\s0 distributions (the
so-called \*(L"Blead Breaks \s-1CPAN\*(R"\s0 (\*(L"\s-1BBC\*(R"\s0) problem) on platforms other than Linux.
.PP
\&\fIFile::Copy::Recursive::Reduced\fR (hereinafter referred to as \fB\s-1FCR2\s0\fR) is
intended to provide a minimal subset of \s-1FCR\s0's functionality \*(-- just enough to
get the Perl toolchain working on the platforms where \s-1FCR\s0 is currently
failing.  Functions will be added to \s-1FCR2\s0 only insofar as investigation shows
that they can replace usage of \s-1FCR\s0 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 \s-1FCR.\s0
.PP
On April 19 2018, \s-1FCR\s0's author, Daniel Muey, released version 0.41 to \s-1CPAN.\s0
This version included a patch submitted by Tom Hukins which corrected the
problem addressed by \s-1FCR2.\s0  \s-1FCR\s0 once again built and tested correctly on
FreeBSD.  That meant that its 6000\-plus reverse dependencies can once again be
reached by \fIcpan\fR and other installers.  That in turn means that we can
conduct exhaustive \s-1BBC\s0 investigations on FreeBSD and other platforms.
.PP
With that correction in \s-1FCR,\s0 the original rationale for \s-1FCR2\s0 has been
superseded.  I will continue to maintain the code and respond to bug reports,
but am suspending active development.  I now deem \s-1FCR2\s0 feature-complete.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
The current version of \s-1FCR2\s0 provides three exportable and publicly supported
subroutines partially equivalent to the similarly named subroutines exported
by \s-1FCR.\s0
.ie n .SS """fcopy()"""
.el .SS "\f(CWfcopy()\fP"
.IX Subsection "fcopy()"
.IP "\(bu" 4
Purpose
.Sp
A stripped-down replacement for \f(CW\*(C`File::Copy::Recursive::fcopy()\*(C'\fR.
.Sp
Copies a file to a new location, recursively creating directories as needed.
Does not copy directories.  Unlike \f(CW\*(C`File::Copy::copy()\*(C'\fR, \f(CW\*(C`fcopy()\*(C'\fR attempts
to preserve the mode of the original file.
.IP "\(bu" 4
Arguments
.Sp
.Vb 1
\&    fcopy($orig, $new) or die $!;
.Ve
.Sp
List of two required arguments:
.RS 4
.IP "\(bu" 4
Absolute path to the file being copied; and
.IP "\(bu" 4
Absolute path to the location to which the file is being copied.
.RE
.RS 4
.Sp
Four cases should be noted:
.IP "1 Create copy within same directory but new basename" 4
.IX Item "1 Create copy within same directory but new basename"
.Vb 1
\&    fcopy(\*(Aq/path/to/filename\*(Aq, \*(Aq/path/to/newfile\*(Aq);
.Ve
.Sp
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.)
.IP "2 Create copy within different, already \fBexisting\fR directory, same basename" 4
.IX Item "2 Create copy within different, already existing directory, same basename"
.Vb 1
\&    fcopy(\*(Aq/path/to/filename\*(Aq, \*(Aq/path/to/existing/directory\*(Aq);
.Ve
.Sp
The second argument can be merely the path to the existing directory; will
create \fI/path/to/existing/directory/filename\fR.
.IP "3 Create copy within different, not yet existing directory, same basename" 4
.IX Item "3 Create copy within different, not yet existing directory, same basename"
.Vb 1
\&    fcopy(\*(Aq/path/to/filename\*(Aq, \*(Aq/path/not/yet/existing/directory/filename\*(Aq);
.Ve
.Sp
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 \fI/path/not/yet/existing/directory/filename\fR.
.IP "4 Create copy within different, not yet existing directory, different basename" 4
.IX Item "4 Create copy within different, not yet existing directory, different basename"
.Vb 1
\&    fcopy(\*(Aq/path/to/filename\*(Aq, \*(Aq/path/not/yet/existing/directory/newfile\*(Aq);
.Ve
.Sp
The second argument will be interpreted as the complete path to the newly
created file.  Will create \fI/path/not/yet/existing/directory/newfile\fR.
.RE
.RS 4
.RE
.IP "\(bu" 4
Return Value
.Sp
Returns \f(CW1\fR upon success; \f(CW0\fR upon failure.  Returns an undefined value if,
for example, function cannot validate arguments.
.IP "\(bu" 4
Comment
.Sp
Since \f(CW\*(C`fcopy()\*(C'\fR internally uses \f(CW\*(C`File::Copy::copy()\*(C'\fR to perform the copying,
the arguments are subject to the same qualifications as that function's
arguments.  Call \fIperldoc File::Copy\fR for discussion of those arguments.
.ie n .SS """dircopy()"""
.el .SS "\f(CWdircopy()\fP"
.IX Subsection "dircopy()"
.IP "\(bu" 4
Purpose
.Sp
A stripped-down replacement for \f(CW\*(C`File::Copy::Recursive::dircopy()\*(C'\fR.
.Sp
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.
.IP "\(bu" 4
Arguments
.Sp
.Vb 2
\&    my $count = dircopy($orig, $new);
\&    warn "dircopy() returned undefined value" unless defined $count;
.Ve
.IP "\(bu" 4
Return Value
.Sp
Upon completion, returns the count of directories and files created \*(-- which
might be \f(CW0\fR.
.Sp
Should the function not complete (but not \f(CW\*(C`die\*(C'\fR), an undefined value will be
returned.  That generally indicates problems with argument validation.  This
approach is taken for consistency with \f(CW\*(C`File::Copy::Recursive::dircopy()\*(C'\fR.
.Sp
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
\&\f(CW\*(C`File::Copy::Recursive::dircopy()\*(C'\fR is not supported.
.IP "\(bu" 4
Restrictions
.Sp
None of \f(CW\*(C`File::Copy::Recursive::dircopy\*(C'\fR'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.
.ie n .SS """rcopy()"""
.el .SS "\f(CWrcopy()\fP"
.IX Subsection "rcopy()"
.IP "\(bu" 4
Purpose
.Sp
A stripped-down replacement for \f(CW\*(C`File::Copy::Recursive::rcopy()\*(C'\fR.  As is the
case with that \s-1FCR\s0 function, \f(CW\*(C`rcopy()\*(C'\fR is more or less a wrapper around
\&\f(CW\*(C`fcopy()\*(C'\fR or \f(CW\*(C`dircopy()\*(C'\fR, depending on the nature of the first argument.
.IP "\(bu" 4
Arguments
.Sp
.Vb 1
\&    rcopy($orig, $new) or die $!;
.Ve
.Sp
List of two required arguments:
.RS 4
.IP "\(bu" 4
Absolute path to the entity (file or directory) being copied; and
.IP "\(bu" 4
Absolute path to the location to which the entity is being copied.
.RE
.RS 4
.RE
.IP "\(bu" 4
Return Value
.Sp
Returns \f(CW1\fR upon success; \f(CW0\fR upon failure.  Returns an undefined value if,
for example, function cannot validate arguments.
.IP "\(bu" 4
Comment
.Sp
Please read the documentation for \f(CW\*(C`fcopy()\*(C'\fR or \f(CW\*(C`dircopy()\*(C'\fR, depending on the
nature of the first argument.
.SS "File::Copy::Recursive Subroutines Not Supported in File::Copy::Recursive::Reduced"
.IX Subsection "File::Copy::Recursive Subroutines Not Supported in File::Copy::Recursive::Reduced"
As of the current version, \s-1FCR2\s0 has no publicly documented, exportable subroutines equivalent
to the following \s-1FCR\s0 exportable subroutines:
.PP
.Vb 8
\&    rcopy_glob
\&    fmove
\&    rmove
\&    rmove_glob
\&    dirmove
\&    pathempty
\&    pathrm
\&    pathrmdir
.Ve
.PP
Consideration is being given to supporting \f(CW\*(C`rcopy()\*(C'\fR.
.SH "BUGS AND SUPPORT"
.IX Header "BUGS AND SUPPORT"
Please report any bugs by mail to \f(CW\*(C`bug\-File\-Copy\-Recursive\-Reduced@rt.cpan.org\*(C'\fR
or through the web interface at <http://rt.cpan.org>.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Notwithstanding the fact that this distribution is being released to address
certain problems in File-Copy-Recursive, credit must be given to \s-1FCR\s0 author
Daniel Muey <http://www.cpan.org/authors/id/D/DM/DMUEY/> for ingenious
conception and execution.  The implementation of the subroutines provided by
\&\s-1FCR2\s0 follows that found in \s-1FCR\s0 to a significant extent.
.PP
Thanks also to Tom Hukins for supplying the patch which corrects \s-1FCR\s0's
problems and which has been incorporated into \s-1FCR2\s0 as well.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 4
\&    James E Keenan
\&    CPAN ID: JKEENAN
\&    jkeenan@cpan.org
\&    http://thenceforward.net/perl
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.
.PP
Copyright James E Keenan 2018.  All rights reserved.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1). \fIFile::Copy::Recursive\fR\|(3).