1File::Path::Tiny(3) User Contributed Perl Documentation File::Path::Tiny(3)
2
6 File::Path::Tiny - recursive versions of mkdir() and rmdir() without as
7 much overhead as File::Path
8
10 This document describes File::Path::Tiny version 0.1
11
13 use File::Path::Tiny;
14 if(!File::Path::Tiny:mk($path)) {
16 die "Could not make path '$path': $!";
17 }
18 if(!File::Path::Tiny:rm($path)) {
20 die "Could not remove path '$path': $!";
21 }
22
24 The goal here is simply to provide recursive versions of mkdir() and
25 rmdir() with as little code and overhead as possible.
26 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 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 Here are some things File::Path has/does that this module attempts to
35 do without:
36 · multiple interfaces
38 Backwards compatibility brings in a lot of code and logic that we
40 don't need from here on out.
41 · chdir's
43 It does a ton of chdir's which could leave you somewhere you're not
45 planning on being and requires much more overhead to do.
46 · can croak not allowing you to detect and handle failure
48 Just let me handle errors how I want. Don't make my entire app die
50 or have to wrap it in an eval
51 · A well intentioned output system
53 Just let me do the output how I want. (Nothing, As HTML, print to a
55 filehandle, etc...)
56 · A well intentioned and experimental (IE subject to change) error
58 handling system.
59 Just keep it simple and detect failure via a boolean check and do
61 what I want with the error. See "How can I make/remove multiple
62 paths?"
63 · According to its POD, removing a tree is apparently not safe unless
65 you tell it to be with the 'safe' or 'keep_root' attributes.
66 Seems like that should just happen, I don't want to worry about
68 accidentally removing / when I pass it /tmp
69
71 Nothing in exported or exportable, that helps keep it '::Tiny'.
72 File::Path::Tiny::mk()
74 Takes a single path (like mkdir()) to recursively create and,
75 optionally, a mask (like mkdir()) for all subsequent mkdir() calls.
76 Mask defaults to 0700 (also like mkdir())
78 Returns false if it could not be made, true otherwise (returns '2' if
80 it is -d already)
81 It is recursive in the sense that given foo/bar/baz as the path to
83 create all 3 will be created if necessary.
84 File::Path::Tiny::rm()
86 Takes a single path (like rmdir()) to recursively empty and remove.
87 Returns false if it could not be emptied or removed, true otherwise.
89 (returns '2' if it is !-d already)
90 It is recursive in the sense that given /foo/bar/baz as the path to
92 remove it will recursively empty 'baz' and then remove it from
93 /foo/bar.
94 Its parents, /, /foo, and /foo/bar are *not* touched.
96
98 Throws no warnings or errors of its own
99 If the functions ever return false, $! will have been set either
101 explicitly or by the mkdir(), rmdir(), unlink(), or opendir() that
102 ultimately returned false.
103
105 How can I make/remove multiple paths?
106 For simplicity sake && ::Tiny status this module must be very very very
107 simple.
108 That said it is also very simple to do muliple paths:
110 for my $path (@paths) {
112 File::Path::Tiny::::mk($path) or _my_handle_failed_mk($path, $!);
113 }
114 for my $path (@paths) {
116 File::Path::Tiny::::rm($path) or _my_handle_failed_rm($path, $!);
117 }
118 That also lets you keep going or short circuit it or handle errors
120 however you like:
121 PATH:
123 for my $path qw(foo/bar bar/rat) {
124 if (!File::Path::Tiny::mk($path)) {
125 print "problem unlinking '$path': $!\n";
126 last PATH;
127 }
128 else {
129 print "No error encountered with '$path'\n"
130 }
131 }
132 About the '::Tiny' status
134 See Acme::Tiny for information on the ::Tiny suffix.
135 #3 is almost there (< 1/5th +/-), a bit more trimming and I think we'll have it!
137 #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
138 [ -- RSS Memory -- ]
140 Baseline perl 1168
141 File::Path 1808 (+640)
142 File::Path::Tiny 1288 (+120)
143 Even though "time" isn't really a ::Tiny factor, it does improve
145 loading a bit:
146 [ -- time -- ]
148 Baseline perl
149 real 0m0.007s
150 user 0m0.002s
151 sys 0m0.004s
152 File::Path
154 real 0m0.017s
155 user 0m0.011s
156 sys 0m0.005s
157 File::Path::Tiny
159 real 0m0.007s
160 user 0m0.003s
161 sys 0m0.004s
162 As time allows and more tests are added I'll try to include more
164 comprehensive benchmark results.
165 How do I make sure the path is safe to create or remove?
167 Of course the answer depends on what you mean by "safe".
168 This module makes no assumptions on interpreting the "safeness" of a
170 path, just like mkdir() and rmdir().
171 Also like mkdir() and rmdir() typically you'll find that filesystem
173 permissions are a pretty reliable tool (of course if the code will be
174 run as root you would want to setuid first...)
175 You might use Cwd::abs_path() to sanitize a path before sending it to
177 be made or removed.
178 Even after that it might not be "safe" so you'll need to discern what
180 your particular definition of "safe" is and take appropriate action.
181
183 File::Spec of course but its only loaded if needed
184
186 None reported.
187
189 No bugs have been reported.
190 Please report any bugs or feature requests to
192 "bug-file-path-tiny@rt.cpan.org", or through the web interface at
193 <http://rt.cpan.org>.
194
196 Daniel Muey "<http://drmuey.com/cpan_contact.pl>"
197
199 Copyright (c) 2008, Daniel Muey "<http://drmuey.com/cpan_contact.pl>".
200 All rights reserved.
201 This module is free software; you can redistribute it and/or modify it
203 under the same terms as Perl itself. See perlartistic.
204
206 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
207 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
208 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
209 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
210 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
211 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
212 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
213 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
214 NECESSARY SERVICING, REPAIR, OR CORRECTION.
215 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
217 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
218 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
219 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
220 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
221 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
222 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
223 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
224 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
225 DAMAGES.
226perl v5.12.2 2008-11-20 File::Path::Tiny(3)