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

BUGS AND SUPPORT

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

ACKNOWLEDGEMENTS

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

AUTHOR

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

COPYRIGHT

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