File::Copy::Recursive::Reduced(3pm)

1File::Copy::Recursive::URseedrucCeodn(t3r)ibuted Perl DoFciulmee:n:tCaotpiyo:n:Recursive::Reduced(3)
2
3
4

NAME

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

SYNOPSIS

10           use File::Copy::Recursive::Reduced qw(fcopy dircopy);
11
12           fcopy($orig,$new) or die $!;
13
14           dircopy($orig,$new) or die $!;
15

DESCRIPTION

17       This library is intended as a not-quite-drop-in replacement for certain
18       functionality provided by CPAN distribution File-Copy-Recursive
19       <http://search.cpan.org/dist/File-Copy-Recursive/>.  The library
20       provides methods similar enough to that distribution's fcopy(),
21       dircopy() and rcopy() functions to be usable in those CPAN
22       distributions often described as being part of the Perl toolchain.
23
24   Rationale
25       File::Copy::Recursive (hereinafter referred to as FCR) is heavily used
26       in other CPAN libraries.  Out of over 30,000 other CPAN distributions
27       studied in early 2018, it ranks by one calculation as the 129th highest
28       distribution in terms of its total direct and indirect reverse
29       dependencies.  In current parlance, it sits "high upstream on the CPAN
30       river."  Hence, it ought to work correctly and be installable on all
31       operating systems where Perl is well supported.
32
33       However, as of early April 2018, FCR version 0.40 wass failing to pass
34       its tests against either Perl 5.26 or Perl 5 blead on important
35       operating systems including Windows, FreeBSD and NetBSD
36       (<http://fast-matrix.cpantesters.org/?dist=File-Copy-Recursive%200.40>).
37       As a consequence, CPAN installers such as cpan and cpanm were failing
38       to install it (unless one resorted to the "--force" option).  This
39       prevented distributions dependent (directly or indirectly) on FCR from
40       being installed as well.
41
42       Some patches had been provided to the FCR bug tracker
43       <https://rt.cpan.org/Dist/Display.html?Name=File-Copy-Recursive> for
44       this problem.  However, as late as April 18 2018 those patches had not
45       yet been applied.  This posed a critical problem for the ability to
46       assess the impact of the soon-to-be-released perl-5.28.0 on CPAN
47       distributions (the so-called "Blead Breaks CPAN" ("BBC") problem) on
48       platforms other than Linux.
49
50       File::Copy::Recursive::Reduced (hereinafter referred to as FCR2) is
51       intended to provide a minimal subset of FCR's functionality -- just
52       enough to get the Perl toolchain working on the platforms where FCR is
53       currently failing.  Functions will be added to FCR2 only insofar as
54       investigation shows that they can replace usage of FCR functions in
55       toolchain and other heavily used modules.  No attempt will be made to
56       reproduce all the functionality currently provided or claimed to be
57       provided by FCR.
58
59       On April 19 2018, FCR's author, Daniel Muey, released version 0.41 to
60       CPAN.  This version included a patch submitted by Tom Hukins which
61       corrected the problem addressed by FCR2.  FCR once again built and
62       tested correctly on FreeBSD.  That meant that its 6000-plus reverse
63       dependencies can once again be reached by cpan and other installers.
64       That in turn means that we can conduct exhaustive BBC investigations on
65       FreeBSD and other platforms.
66
67       With that correction in FCR, the original rationale for FCR2 has been
68       superseded.  I will continue to maintain the code and respond to bug
69       reports, but am suspending active development.  I now deem FCR2
70       feature-complete.
71

SUBROUTINES

73       The current version of FCR2 provides three exportable and publicly
74       supported subroutines partially equivalent to the similarly named
75       subroutines exported by FCR.
76
77   fcopy()
78       •   Purpose
79
80           A stripped-down replacement for File::Copy::Recursive::fcopy().
81
82           Copies a file to a new location, recursively creating directories
83           as needed.  Does not copy directories.  Unlike File::Copy::copy(),
84           fcopy() attempts to preserve the mode of the original file.
85
86       •   Arguments
87
88               fcopy($orig, $new) or die $!;
89
90           List of two required arguments:
91
92           •   Absolute path to the file being copied; and
93
94           •   Absolute path to the location to which the file is being
95               copied.
96
97           Four cases should be noted:
98
99           1 Create copy within same directory but new basename
100                   fcopy('/path/to/filename', '/path/to/newfile');
101
102               The second argument must be the absolute path to the new file.
103               (Otherwise the file will be created in the current working
104               directory, which is almost certainly what you do not want.)
105
106           2 Create copy within different, already existing directory, same
107           basename
108                   fcopy('/path/to/filename', '/path/to/existing/directory');
109
110               The second argument can be merely the path to the existing
111               directory; will create /path/to/existing/directory/filename.
112
113           3 Create copy within different, not yet existing directory, same
114           basename
115                   fcopy('/path/to/filename', '/path/not/yet/existing/directory/filename');
116
117               The second argument will be interpreted as the complete path to
118               the newly created file.  The basename must be included even if
119               it is the same as in the first argument.  Will create
120               /path/not/yet/existing/directory/filename.
121
122           4 Create copy within different, not yet existing directory,
123           different basename
124                   fcopy('/path/to/filename', '/path/not/yet/existing/directory/newfile');
125
126               The second argument will be interpreted as the complete path to
127               the newly created file.  Will create
128               /path/not/yet/existing/directory/newfile.
129
130       •   Return Value
131
132           Returns 1 upon success; 0 upon failure.  Returns an undefined value
133           if, for example, function cannot validate arguments.
134
135       •   Comment
136
137           Since fcopy() internally uses File::Copy::copy() to perform the
138           copying, the arguments are subject to the same qualifications as
139           that function's arguments.  Call perldoc File::Copy for discussion
140           of those arguments.
141
142   dircopy()
143       •   Purpose
144
145           A stripped-down replacement for File::Copy::Recursive::dircopy().
146
147           Given the path to the directory specified by the first argument,
148           the function copies all of the files and directories beneath it to
149           the directory specified by the second argument.
150
151       •   Arguments
152
153               my $count = dircopy($orig, $new);
154               warn "dircopy() returned undefined value" unless defined $count;
155
156       •   Return Value
157
158           Upon completion, returns the count of directories and files created
159           -- which might be 0.
160
161           Should the function not complete (but not "die"), an undefined
162           value will be returned.  That generally indicates problems with
163           argument validation.  This approach is taken for consistency with
164           File::Copy::Recursive::dircopy().
165
166           In list context the return value is a one-item list holding the
167           same value as returned in scalar context.  The three-item list
168           return value of File::Copy::Recursive::dircopy() is not supported.
169
170       •   Restrictions
171
172           None of "File::Copy::Recursive::dircopy"'s bells and whistles.  No
173           guaranteed preservation of file or directory modes.  No restriction
174           on maximum depth.  No nothing; this is fine-tuned to the needs of
175           Perl toolchain modules and their test suites.
176
177   rcopy()
178       •   Purpose
179
180           A stripped-down replacement for File::Copy::Recursive::rcopy().  As
181           is the case with that FCR function, rcopy() is more or less a
182           wrapper around fcopy() or dircopy(), depending on the nature of the
183           first argument.
184
185       •   Arguments
186
187               rcopy($orig, $new) or die $!;
188
189           List of two required arguments:
190
191           •   Absolute path to the entity (file or directory) being copied;
192               and
193
194           •   Absolute path to the location to which the entity is being
195               copied.
196
197       •   Return Value
198
199           Returns 1 upon success; 0 upon failure.  Returns an undefined value
200           if, for example, function cannot validate arguments.
201
202       •   Comment
203
204           Please read the documentation for fcopy() or dircopy(), depending
205           on the nature of the first argument.
206
207   File::Copy::Recursive Subroutines Not Supported in
208       File::Copy::Recursive::Reduced
209       As of the current version, FCR2 has no publicly documented, exportable
210       subroutines equivalent to the following FCR exportable subroutines:
211
212           rcopy_glob
213           fmove
214           rmove
215           rmove_glob
216           dirmove
217           pathempty
218           pathrm
219           pathrmdir
220
221       Consideration is being given to supporting rcopy().
222

BUGS AND SUPPORT

224       Please report any bugs by mail to
225       "bug-File-Copy-Recursive-Reduced@rt.cpan.org" or through the web
226       interface at <http://rt.cpan.org>.
227

ACKNOWLEDGEMENTS

229       Notwithstanding the fact that this distribution is being released to
230       address certain problems in File-Copy-Recursive, credit must be given
231       to FCR author Daniel Muey <http://www.cpan.org/authors/id/D/DM/DMUEY/>
232       for ingenious conception and execution.  The implementation of the
233       subroutines provided by FCR2 follows that found in FCR to a significant
234       extent.
235
236       Thanks also to Tom Hukins for supplying the patch which corrects FCR's
237       problems and which has been incorporated into FCR2 as well.
238

AUTHOR

240           James E Keenan
241           CPAN ID: JKEENAN
242           jkeenan@cpan.org
243           http://thenceforward.net/perl
244

COPYRIGHT

246       This program is free software; you can redistribute it and/or modify it
247       under the same terms as Perl itself.
248
249       The full text of the license can be found in the LICENSE file included
250       with this module.
251
252       Copyright James E Keenan 2018.  All rights reserved.
253