File::Path::Tiny(3pm)

1File::Path::Tiny(3)   User Contributed Perl Documentation  File::Path::Tiny(3)
2
3
4

NAME

6       File::Path::Tiny - recursive versions of mkdir() and rmdir() without as
7       much overhead as File::Path
8

VERSION

10       This document describes File::Path::Tiny version 1.0
11

SYNOPSIS

13           use File::Path::Tiny;
14
15           if(!File::Path::Tiny::mk($path)) {
16               die "Could not make path '$path': $!";
17           }
18
19           if(!File::Path::Tiny::rm($path)) {
20               die "Could not remove path '$path': $!";
21           }
22

DESCRIPTION

24       The goal here is simply to provide recursive versions of mkdir() and
25       rmdir() with as little code and overhead as possible.
26
27       This module is in no way meant to derogate File::Path and is in no way
28       an endorsement to go out and replace all use of File::Path with
29       File::Path::Tiny.
30
31       File::Path is very good at what it does but there's simply a lot
32       happening that we can do without much of the time.
33
34       Here are some things File::Path has/does that this module attempts to
35       do without:
36
37       •   multiple interfaces
38
39           Backwards compatibility brings in a lot of code and logic that we
40           don't need from here on out.
41
42       •   chdir()s
43
44           It forces a ton of chdir()s which could leave you somewhere you're
45           not planning on being and requires much more overhead to do.
46
47           This module provides a way to disable that if you know it is safe
48           to do so in your circumstance.
49
50       •   can croak not allowing you to detect and handle failure
51
52           Just let me handle errors how I want. Don't make my entire app die
53           or have to wrap it in an eval
54
55           The exception here is the security checks can croak, which is what
56           you want. See DIAGNOSTICS for more info.
57
58       •   A well intentioned output system
59
60           Just let me do the output how I want. (Nothing, As HTML, print to a
61           filehandle, etc...)
62
63       •   A well intentioned and experimental (IE subject to change) error
64           handling system.
65
66           Just keep it simple and detect failure via a boolean check and do
67           what I want with the error. See "How can I make/remove multiple
68           paths?"
69
70       •   According to its POD, removing a tree is apparently not safe unless
71           you tell it to be with the ‘safe’ or 'keep_root' attributes.
72
73           Seems like that should just happen, I don't want to worry about
74           accidentally removing / when I pass it /tmp
75

INTERFACE

77       Nothing in exported or exportable, that helps keep it '::Tiny'.
78
79   File::Path::Tiny::mk()
80       Takes a single path (like mkdir()) to recursively create and,
81       optionally, a mask (like mkdir()) for all subsequent mkdir() calls.
82
83       Mask defaults to 0700 (also like mkdir())
84
85       Returns false if it could not be made, true otherwise (returns ‘2’ if
86       it is -d already)
87
88       It is recursive in the sense that given “foo/bar/baz” as the path to
89       create all 3 will be created if necessary.
90
91   File::Path::Tiny::rm()
92       Takes a single path (like rmdir()) to recursively empty and remove.
93
94       Returns false if it could not be emptied or removed, true otherwise
95       (returns ‘2’ if it is !-d already). Also see DIAGNOSTICS.
96
97       It is recursive in the sense that given “/foo/bar/baz” as the path to
98       remove it will recursively empty ‘baz’ and then remove it from
99       /foo/bar.
100
101       Its parents, /, /foo, and /foo/bar are *not* touched.
102
103       By default it does chdir() for security reasons. If you are sure it is
104       safe to do without that for the sake of a bit of speed you can pass a
105       second true argument to skip that.
106
107   File::Path::Tiny::empty_dir()
108       Takes a single path to recursively empty but not remove.
109
110       Returns false when there is a problem. Also see DIAGNOSTICS.
111
112       By default it does chdir() for security reasons. If you are sure it is
113       safe to do without that for the sake of a bit of speed you can pass a
114       second true argument to skip that.
115
116   File::Path::Tiny::mk_parent()
117       Like mk() but recursively creates the parent. e.g. given
118       “foo/bar/baz.txt” creates foo/bar.
119
120   From Cwd
121       It uses these internally so, for convenience, these are exposed in case
122       you want to use them also.
123
124       File::Path::Tiny::cwd()
125
126       Comes directly from Cwd’s cwd().
127
128       File::Path::Tiny::chdir()
129
130       Comes directly from Cwd’s chdir().
131

DIAGNOSTICS

133       If the functions ever return false, $! will have been set either
134       explicitly or by the mkdir(), rmdir(), unlink(), or opendir() that
135       ultimately returned false.
136
137       "directory %s changed: expected dev=%d ino=$d, actual dev=%d ino=%d,
138       aborting"
139           empty_dir() and rm() throw this if any of the directories being
140           operated on change during the operation.
141

MISC

143   How can I make/remove multiple paths?
144       For simplicity sake && ::Tiny status this module must be very very very
145       simple.
146
147       That said it is also very simple to do multiple paths:
148
149           for my $path (@paths) {
150               File::Path::Tiny::::mk($path) or _my_handle_failed_mk($path, $!);
151           }
152
153           for my $path (@paths) {
154               File::Path::Tiny::::rm($path) or _my_handle_failed_rm($path, $!);
155           }
156
157       That also lets you keep going or short circuit it or handle errors
158       however you like:
159
160            PATH:
161            for my $path qw(foo/bar bar/rat) {
162                if (!File::Path::Tiny::mk($path)) {
163                    print "problem unlinking '$path': $!\n";
164                    last PATH;
165                }
166                else {
167                    print "No error encountered with '$path'\n"
168                }
169            }
170
171   About the '::Tiny' status
172       See Acme::Tiny for information on the ::Tiny suffix.
173
174         #3 is almost there (< 1/5th +/-), a bit more trimming and I think we'll have it!
175         #8 is N/A since part of the "sub set" is to do single paths like their non-recursive core counterparts and there are so many ways to invoke it with different consequences
176
177          [ -- RSS Memory -- ]
178           Baseline perl 1168
179           File::Path 1808 (+640)
180           File::Path::Tiny 1288 (+120)
181
182       Even though "time" isn't really a ::Tiny factor, it does improve
183       loading a bit:
184
185          [ -- time -- ]
186           Baseline perl
187             real      0m0.007s
188             user      0m0.002s
189             sys       0m0.004s
190
191           File::Path
192             real      0m0.017s
193             user      0m0.011s
194             sys       0m0.005s
195
196           File::Path::Tiny
197             real      0m0.007s
198             user      0m0.003s
199             sys       0m0.004s
200
201       As time allows and more tests are added I'll try to include more
202       comprehensive benchmark results.
203
204   How do I make sure the path is safe to create or remove?
205       Of course the answer depends on what you mean by "safe".
206
207       This module makes no assumptions on interpreting the "safeness" of a
208       path, just like mkdir() and rmdir().
209
210       Also like  mkdir() and rmdir() typically you'll find that filesystem
211       permissions are a pretty reliable tool (of course if the code will be
212       run as root you would want to setuid first...)
213
214       You might use Cwd::abs_path() to sanitize a path before sending it to
215       be made or removed.
216
217       Even after that it might not be "safe" so you'll need to discern what
218       your particular definition of "safe" is and take appropriate action.
219

DEPENDENCIES

221       File::Spec of course but its only loaded if needed
222

INCOMPATIBILITIES

230       None reported.
231

BUGS AND FEATURES

233       Please report any bugs or feature requests (and a pull request for
234       bonus points)
235        through the issue tracker at
236       <https://github.com/drmuey/p5-File-Path-Tiny/issues>.
237

AUTHOR

239       Daniel Muey  "<http://drmuey.com/cpan_contact.pl>"
240

LICENCE AND COPYRIGHT

242       Copyright (c) 2008, Daniel Muey "<http://drmuey.com/cpan_contact.pl>".
243       All rights reserved.
244
245       This module is free software; you can redistribute it and/or modify it
246       under the same terms as Perl itself. See perlartistic.
247

DISCLAIMER OF WARRANTY

249       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
250       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
251       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
252       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
253       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
254       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
255       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
256       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
257       NECESSARY SERVICING, REPAIR, OR CORRECTION.
258
259       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
260       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
261       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
262       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
263       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
264       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
265       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
266       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
267       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
268       DAMAGES.
269
270
271
272perl v5.36.0                      2023-01-20               File::Path::Tiny(3)