File::Path::Tiny(3pm)

💖 File::Path::Tiny 💖

okay bestie, so this is File::Path::Tiny — the user-contributed Perl doc page for it — and it's literally recursive versions of mkdir() and rmdir() without all the overhead that File::Path drags around. it's giving minimalist queen. 👑

---

✨ VERSION ✨

this doc is describing File::Path::Tiny version 1.0. periodt.

---

🌸 SYNOPSIS 🌸

use File::Path::Tiny;

if(!File::Path::Tiny::mk($path)) {
    die "Could not make path '$path': $!";
}

if(!File::Path::Tiny::rm($path)) {
    die "Could not remove path '$path': $!";
}

---

🦋 DESCRIPTION 🦋

so the whole goal here is just to give you recursive versions of mkdir() and rmdir() with as little code and overhead as humanly possible. no cap.

and like, this module is in no way meant to be disrespectful to File::Path, and it is in no way an endorsement to go replace all your File::Path usage with File::Path::Tiny. we're not doing that. we're mutuals. 🫶

File::Path is genuinely so good at what it does — but there's just a lot happening, and honestly a lot of the time we can do without it.

here's the stuff File::Path has/does that this module is trying to do without:

• multiple interfaces

backwards compatibility brings in a ton of code and logic that we just don't need from here on out.

• chdir()s

it forces a ton of chdir()s which could leave you somewhere you're not planning on being, and requires sooo much more overhead to do.

this module provides a way to disable that, if you know it's safe to do so in your circumstance.

• can croak not allowing you to detect and handle failure

just let me handle errors how I want. don't make my entire app die, don't make me wrap it in an eval. 🙄

the exception here is the security checks can croak, which is exactly what you want. see DIAGNOSTICS for more info.

• A well intentioned output system

just let me do the output how I want. (nothing, as HTML, print to a filehandle, whatever...)

• A well intentioned and experimental (IE subject to change) error handling system.

just keep it simple and detect failure via a boolean check, then do what I want with the error. see "How can I make/remove multiple paths?"

• according to its POD, removing a tree is apparently not safe unless you tell it to be with the ‘safe’ or 'keep_root' attributes.

girl... seems like that should just happen?? I don't want to worry about accidentally removing / when I pass it /tmp. 💀

---

👑 INTERFACE 👑

nothing is exported or exportable, and that's what keeps it '::Tiny'. slay.

💅 File::Path::Tiny::mk()

takes a single path (like mkdir()) to recursively create, and optionally a mask (like mkdir()) for all subsequent mkdir() calls.

mask defaults to 0700 (also like mkdir()).

returns false if it couldn't be made, true otherwise (returns 2 if it's -d already).

it's recursive in the sense that, given foo/bar/baz as the path to create, all 3 will be created if necessary.

💅 File::Path::Tiny::rm()

takes a single path (like rmdir()) to recursively empty and remove.

returns false if it couldn't be emptied or removed, true otherwise (returns 2 if it's !-d already). also see DIAGNOSTICS.

it's recursive in the sense that, given /foo/bar/baz as the path to remove, it will recursively empty baz and then remove it from /foo/bar.

its parents, /, /foo, and /foo/bar are not touched. 🔥

by default it does chdir() for security reasons. if you are sure it's safe to do without that, for the sake of a bit of speed, you can pass a second true argument to skip that.

💅 File::Path::Tiny::empty_dir()

takes a single path to recursively empty but not remove.

returns false when there's a problem. also see DIAGNOSTICS.

by default it does chdir() for security reasons. if you are sure it's safe to do without that, for the sake of a bit of speed, you can pass a second true argument to skip that.

💅 File::Path::Tiny::mk_parent()

like mk() but recursively creates the parent. e.g. given foo/bar/baz.txt it creates foo/bar.

💅 From Cwd

it uses these internally, so for convenience they're exposed in case you want to use them too.

File::Path::Tiny::cwd()

comes directly from Cwd's cwd().

File::Path::Tiny::chdir()

comes directly from Cwd's chdir().

---

🎀 DIAGNOSTICS 🎀

if the functions ever return false, $! will have been set either explicitly or by the mkdir(), rmdir(), unlink(), or opendir() that ultimately returned false.

"directory %s changed: expected dev=%d ino=$d, actual dev=%d ino=%d, aborting"

empty_dir() and rm() throw this if any of the directories being operated on change during the operation. 👀

---

🌈 MISC 🌈

🍓 How can I make/remove multiple paths?

for simplicity's sake && ::Tiny status, this module must be very very very simple.

that said, it's also very simple to do multiple paths:

for my $path (@paths) {
    File::Path::Tiny::::mk($path) or _my_handle_failed_mk($path, $!);
}

for my $path (@paths) {
    File::Path::Tiny::::rm($path) or _my_handle_failed_rm($path, $!);
}

that also lets you keep going, or short circuit it, or handle errors however you like:

 PATH:
 for my $path qw(foo/bar bar/rat) {
     if (!File::Path::Tiny::mk($path)) {
         print "problem unlinking '$path': $!\n";
         last PATH;
     }
     else {
         print "No error encountered with '$path'\n"
     }
 }

🍓 About the '::Tiny' status

see Acme::Tiny for information on the ::Tiny suffix.

#3 is almost there (< 1/5th +/-), a bit more trimming and I think we'll have it!
#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

 [ -- RSS Memory -- ]
  Baseline perl 1168
  File::Path 1808 (+640)
  File::Path::Tiny 1288 (+120)

even though "time" isn't really a ::Tiny factor, it does improve loading a bit:

 [ -- time -- ]
  Baseline perl
    real      0m0.007s
    user      0m0.002s
    sys       0m0.004s

  File::Path
    real      0m0.017s
    user      0m0.011s
    sys       0m0.005s

  File::Path::Tiny
    real      0m0.007s
    user      0m0.003s
    sys       0m0.004s

as time allows and more tests are added, more comprehensive benchmark results will try to be included.

🍓 How do I make sure the path is safe to create or remove?

of course the answer depends on what you mean by "safe". 🙈

this module makes no assumptions on interpreting the "safeness" of a path — just like mkdir() and rmdir().

also, like mkdir() and rmdir(), typically you'll find that filesystem permissions are a pretty reliable tool (of course, if the code will be run as root you would want to setuid first...)

you might use Cwd::abs_path() to sanitize a path before sending it off to be made or removed.

even after that it might not be "safe", so you'll need to discern what your particular definition of "safe" is and take appropriate action.

---

🧚 DEPENDENCIES 🧚

File::Spec, of course — but it's only loaded if needed. lowkey efficient.

---

⭐ SEE ALSO ⭐

we already talked about File::Path in the "DESCRIPTION". Path::Tiny also offers a mkpath interface, but it too has/does things that this module attempts to do without, per the "DESCRIPTION". plus its ::Tiny name is a misnomer, see Acme::Tiny for details. 💅

---

💜 INCOMPATIBILITIES 💜

none reported.

---

💀 BUGS AND FEATURES 💀

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

---

🌸 AUTHOR 🌸

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

---

🎀 LICENCE AND COPYRIGHT 🎀

Copyright (c) 2008, Daniel Muey "<http://drmuey.com/cpan_contact.pl>". All rights reserved.

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. see perlartistic.

---

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

---

that's the whole page bestie, go forth and make your directories 💖

okay and for the cute sign-off: this page is for perl v5.32.1, dated 2021-02-27, and it is literally the File::Path::Tiny(3pm) page. that's the vibe. take care of her, she's tiny but mighty. 🦋✨💅