.\" Automatically generated by Pod::Man 2.28 (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::Fu 3pm"
.TH File::Fu 3pm "2015-12-08" "perl v5.20.2" "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::Fu \- file and directory objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
The directory constructor:
.PP
.Vb 1
\&  use File::Fu;
\&
\&  my $dir = File::Fu\->dir("bar");
\&  print "$dir\en"; # \*(Aqbar/\*(Aq
\&
\&  my $file = $dir + \*(Aqbar.txt\*(Aq;
\&  print "$file\en"; # \*(Aqbar/bar.txt\*(Aq
\&
\&  my $d2 = $dir % \*(Aqbaz\*(Aq; # \*(Aqbarbaz/\*(Aq
\&  my $d3 = $dir / \*(Aqbat\*(Aq; # \*(Aqbar/bat/\*(Aq
\&
\&  my $file2 = $dir / \*(Aqbat\*(Aq + \*(Aqfoo.txt\*(Aq; # \*(Aqbar/bat/foo.txt\*(Aq
.Ve
.PP
The file constructor:
.PP
.Vb 4
\&  my $file = File::Fu\->file("foo");
\&  $file\->e and warn "$file exists";
\&  $file\->l and warn "$file is a link";
\&  warn "file is in ", $file\->dir;
.Ve
.SH "ABOUT"
.IX Header "ABOUT"
This class provides the toplevel interface to File::Fu directory and
file objects, with operator overloading which allows precise path
composition and support for most builtin methods, as well as creation of
temporary files/directories, finding files, and more.
.PP
The interface and style are quite different than the perl builtins or
File::Spec.  The syntax is concise.  Errors are thrown with \fIcroak()\fR, so
you never need to check a return code.
.SH "Constructors"
.IX Header "Constructors"
The actual objects are in the 'Dir' and 'File' sub-namespaces.
.SS "dir"
.IX Subsection "dir"
.Vb 1
\&  my $dir = File::Fu\->dir($path);
.Ve
.PP
See \*(L"new\*(R" in File::Fu::Dir
.SS "file"
.IX Subsection "file"
.Vb 1
\&  my $file = File::Fu\->file($path);
.Ve
.PP
See \*(L"new\*(R" in File::Fu::File
.SH "Class Constants"
.IX Header "Class Constants"
.SS "tmp"
.IX Subsection "tmp"
Your system's '/tmp/' directory (or equivalent of that.)
.PP
.Vb 1
\&  my $dir = File::Fu\->tmp;
.Ve
.SS "home"
.IX Subsection "home"
User's \f(CW$HOME\fR directory.
.PP
.Vb 1
\&  my $dir = File::Fu\->home;
.Ve
.SS "program_name"
.IX Subsection "program_name"
The absolute name of your program.  This will be relative from the time
File::Fu was loaded.  It dies if the name is '\-e'.
.PP
.Vb 1
\&  my $prog = File::Fu\->program_name;
.Ve
.PP
If File::Fu was loaded after a chdir and the \f(CW$0\fR was relative, calling
\&\fIprogram_name()\fR throws an error.  (Unless you set \f(CW$0\fR correctly before
requiring File::Fu.)
.SS "program_dir"
.IX Subsection "program_dir"
Returns what typically corresponds to \fIprogram_name()\fR\->dirname, but
just the compile-time \fIcwd()\fR when \f(CW$0\fR is \-e/\-E.
.PP
.Vb 1
\&  my $dir = File::Fu\->program_dir;
.Ve
.SH "Class Methods"
.IX Header "Class Methods"
.SS "\s-1THIS_FILE\s0"
.IX Subsection "THIS_FILE"
A nicer way to say _\|_FILE_\|_.
.PP
.Vb 1
\&  my $file = File::Fu\->THIS_FILE;
.Ve
.SS "cwd"
.IX Subsection "cwd"
The current working directory.
.PP
.Vb 1
\&  my $dir = File::Fu\->cwd;
.Ve
.SS "which"
.IX Subsection "which"
Returns File::Fu::File objects of ordered candidates for \f(CW$name\fR found in
the path.
.PP
.Vb 1
\&  my @prog = File::Fu\->which($name) or die "cannot find $name";
.Ve
.PP
If called in scalar context, returns a single File::Fu::File object or throws an error if no candidates were found.
.PP
.Vb 1
\&  my $prog = File::Fu\->which($name);
.Ve
.SH "Temporary Directories and Files"
.IX Header "Temporary Directories and Files"
These class methods call the corresponding File::Fu::Dir methods on the
value of \fItmp()\fR.  That is, you get a temporary file/dir in the '/tmp/'
directory.
.SS "temp_dir"
.IX Subsection "temp_dir"
.Vb 1
\&  my $dir = File::Fu\->temp_dir;
.Ve
.SS "temp_file"
.IX Subsection "temp_file"
.Vb 1
\&  my $handle = File::Fu\->temp_file;
.Ve
.SH "Operators"
.IX Header "Operators"
If you choose not to use the overloaded operators, you can just say
\&\f(CW\*(C`$obj\->stringify()\*(C'\fR or \*(L"$obj\*(R" whenever you want to drop the
object-y nature and treat the path as a string.
.PP
The operators can be convenient for building-up path names, but you
probably don't want to think of them as \*(L"math on filenames\*(R", because
they are nothing like that.
.PP
The '+' and '/' operators only apply to directory objects.
.PP
.Vb 4
\&  op   method                     mnemonic
\&  \-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-           \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  +    $d\->file($b) ............. plus (not "add")
\&  /    $d\->subdir($b) ........... slash (not "divide")
.Ve
.PP
The other operators apply to both files and directories.
.PP
.Vb 6
\&  op   method                     mnemonic
\&  \-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-           \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  %=   $p\->append($b) ........... mod(ify)
\&  %    $p\->clone\->append($b)      
\&  &=   $p\->map(sub{...}) ........ invoke subref
\&  &    $p\->clone\->map(sub {...})
.Ve
.PP
Aside:  It would be more natural to use \f(CW\*(C`.=\*(C'\fR as \fIappend()\fR, but the way
perl compiles \f(CW"$obj foo"\fR into \f(CW\*(C`$obj . " foo"\*(C'\fR makes it impossible to
do the right thing because the lines between object and string are too
ambiguous.
.SH "Subclassing"
.IX Header "Subclassing"
You may wish to subclass File:Fu and override the \fIdir_class()\fR and/or
\&\fIfile_class()\fR class methods to point to your own Dir/File subclasses.
.PP
.Vb 2
\&  my $class = \*(AqMy::FileFu\*(Aq;
\&  my $dir = $class\->dir("foo");
.Ve
.PP
See File::Fu::File and File::Fu::Dir for more info.
.SS "dir_class"
.IX Subsection "dir_class"
.Vb 1
\&  File::Fu\->dir_class # File::Fu::Dir
.Ve
.SS "file_class"
.IX Subsection "file_class"
.Vb 1
\&  File::Fu\->file_class # File::Fu::File
.Ve
.SH "See Also"
.IX Header "See Also"
File::Fu::why if I need to explain my motivations.
.PP
Path::Class, from which many an idea was taken.
.PP
File::stat, IO::File, File::Spec, File::Find, File::Temp,
File::Path, File::Basename, perlfunc, perlopentut.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eric Wilhelm @ <ewilhelm at cpan dot org>
.PP
http://scratchcomputing.com/
.SH "BUGS"
.IX Header "BUGS"
If you found this module on \s-1CPAN,\s0 please report any bugs or feature
requests through the web interface at <http://rt.cpan.org>.  I will be
notified, and then you'll automatically be notified of progress on your
bug as I make changes.
.PP
If you pulled this development version from my /svn/, please contact me
directly.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2008 Eric L. Wilhelm, All Rights Reserved.
.SH "NO WARRANTY"
.IX Header "NO WARRANTY"
Absolutely, positively \s-1NO WARRANTY,\s0 neither express or implied, is
offered with this software.  You use this software at your own risk.  In
case of loss, no person or entity owes you anything whatsoever.  You
have been warned.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.