.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::Path::Tiny 3"
.TH File::Path::Tiny 3 "2016-01-27" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::Path::Tiny \- recursive versions of mkdir() and rmdir() without as much overhead as File::Path
.SH "VERSION"
.IX Header "VERSION"
This document describes File::Path::Tiny version 0.8
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use File::Path::Tiny;
\&
\&    if(!File::Path::Tiny::mk($path)) {
\&        die "Could not make path \*(Aq$path\*(Aq: $!";
\&    }
\&    
\&    if(!File::Path::Tiny::rm($path)) {
\&        die "Could not remove path \*(Aq$path\*(Aq: $!";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The goal here is simply to provide recursive versions of mkdir() and rmdir() with as little code and overhead as possible.
.PP
This module is in no way meant to derogate File::Path and is in no way an endorsement to go out and replace all use of File::Path with File::Path::Tiny.
.PP
File::Path is very good at what it does but there's simply a lot happening that we can do without much of the time.
.PP
Here are some things File::Path has/does that this module attempts to do without:
.IP "\(bu" 4
multiple interfaces
.Sp
Backwards compatibility brings in a lot of code and logic that we don't need from here on out.
.IP "\(bu" 4
\&\fIchdir()\fRs
.Sp
It does a ton of \fIchdir()\fRs which could leave you somewhere you're not planning on being and requires much more overhead to do.
.IP "\(bu" 4
can croak not allowing you to detect and handle failure
.Sp
Just let me handle errors how I want. Don't make my entire app die or have to wrap it in an eval
.IP "\(bu" 4
A well intentioned output system
.Sp
Just let me do the output how I want. (Nothing, As \s-1HTML,\s0 print to a filehandle, etc...)
.IP "\(bu" 4
A well intentioned and experimental (\s-1IE\s0 subject to change) error handling system.
.Sp
Just keep it simple and detect failure via a boolean check and do what I want with the error. See \*(L"How can I make/remove multiple paths?\*(R"
.IP "\(bu" 4
According to its \s-1POD,\s0 removing a tree is apparently not safe unless you tell it to be with the XsafeX or 'keep_root' attributes.
.Sp
Seems like that should just happen, I don't want to worry about accidentally removing / when I pass it /tmp
.SH "INTERFACE"
.IX Header "INTERFACE"
Nothing in exported or exportable, that helps keep it '::Tiny'.
.SS "\fIFile::Path::Tiny::mk()\fP"
.IX Subsection "File::Path::Tiny::mk()"
Takes a single path (like mkdir()) to recursively create and, optionally, a mask (like mkdir()) for all subsequent mkdir() calls.
.PP
Mask defaults to 0700 (also like mkdir())
.PP
Returns false if it could not be made, true otherwise (returns X2X if it is \-d already)
.PP
It is recursive in the sense that given Xfoo/bar/bazX as the path to create all 3 will be created if necessary.
.SS "\fIFile::Path::Tiny::rm()\fP"
.IX Subsection "File::Path::Tiny::rm()"
Takes a single path (like rmdir()) to recursively empty and remove.
.PP
Returns false if it could not be emptied or removed, true otherwise. (returns X2X if it is !\-d already)
.PP
It is recursive in the sense that given X/foo/bar/bazX as the path to remove it will recursively empty XbazX and then remove it from /foo/bar.
.PP
Its parents, /, /foo, and /foo/bar are *not* touched.
.SS "\fIFile::Path::Tiny::empty_dir()\fP"
.IX Subsection "File::Path::Tiny::empty_dir()"
Takes a single path to recursively empty  but not remove.
.PP
Returns false when there is a problem.
.SS "\fIFile::Path::Tiny::mk_parent()\fP"
.IX Subsection "File::Path::Tiny::mk_parent()"
Like \fImk()\fR but recursively creates the parent. e.g. given Xfoo/bar/baz.txtX creates foo/bar.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Throws no warnings or errors of its own
.PP
If the functions ever return false, $! will have been set either explicitly or by the mkdir(), rmdir(), unlink(), or opendir() that ultimately returned false.
.SH "MISC"
.IX Header "MISC"
.SS "How can I make/remove multiple paths?"
.IX Subsection "How can I make/remove multiple paths?"
For simplicity sake && ::Tiny status this module must be very very very simple.
.PP
That said it is also very simple to do multiple paths:
.PP
.Vb 3
\&    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, $!);    
\&    }
.Ve
.PP
That also lets you keep going or short circuit it or handle errors however you like:
.PP
.Vb 10
\&     PATH:
\&     for my $path qw(foo/bar bar/rat) {
\&         if (!File::Path::Tiny::mk($path)) {
\&             print "problem unlinking \*(Aq$path\*(Aq: $!\en";
\&             last PATH;
\&         }
\&         else {
\&             print "No error encountered with \*(Aq$path\*(Aq\en" 
\&         }
\&     }
.Ve
.SS "About the '::Tiny' status"
.IX Subsection "About the '::Tiny' status"
See Acme::Tiny for information on the ::Tiny suffix.
.PP
.Vb 2
\&  #3 is almost there (< 1/5th +/\-), a bit more trimming and I think we\*(Aqll 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)
.Ve
.PP
Even though \*(L"time\*(R" isn't really a ::Tiny factor, it does improve loading a bit:
.PP
.Vb 5
\&   [ \-\- 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
.Ve
.PP
As time allows and more tests are added I'll try to include more comprehensive benchmark results.
.SS "How do I make sure the path is safe to create or remove?"
.IX Subsection "How do I make sure the path is safe to create or remove?"
Of course the answer depends on what you mean by \*(L"safe\*(R".
.PP
This module makes no assumptions on interpreting the \*(L"safeness\*(R" of a path, just like mkdir() and rmdir().
.PP
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...)
.PP
You might use \fICwd::abs_path()\fR to sanitize a path before sending it to be made or removed.
.PP
Even after that it might not be \*(L"safe\*(R" so you'll need to discern what your particular definition of \*(L"safe\*(R" is and take appropriate action.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
File::Spec of course but its only loaded if needed
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND FEATURES"
.IX Header "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>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Muey  \f(CW\*(C`<http://drmuey.com/cpan_contact.pl>\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2008, Daniel Muey \f(CW\*(C`<http://drmuey.com/cpan_contact.pl>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE 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 \*(L"AS IS\*(R" 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.\s0
.PP
\&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO 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 \s0(\s-1INCLUDING 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\s0), \s-1EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.\s0