1File::Copy::Recursive::URseedrucCeodn(t3r)ibuted Perl DoFciulmee:n:tCaotpiyo:n:Recursive::Reduced(3)
2
3
4
6 File::Copy::Recursive::Reduced - Recursive copying of files and
7 directories within Perl 5 toolchain
8
10 use File::Copy::Recursive::Reduced qw(fcopy dircopy);
11
12 fcopy($orig,$new) or die $!;
13
14 dircopy($orig,$new) or die $!;
15
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
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
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
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
242 James E Keenan
243 CPAN ID: JKEENAN
244 jkeenan@cpan.org
245 http://thenceforward.net/perl
246
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
257 perl(1). File::Copy::Recursive(3).
258
259
260
261perl v5.32.1 2021-01-27 File::Copy::Recursive::Reduced(3)