NAME

       File::Fu - file and directory objects

SYNOPSIS

       The directory constructor:

         use File::Fu;

         my $dir = File::Fu->dir("bar");
         print "$dir\n"; # 'bar/'

         my $file = $dir + 'bar.txt';
         print "$file\n"; # 'bar/bar.txt'

         my $d2 = $dir % 'baz'; # 'barbaz/'
         my $d3 = $dir / 'bat'; # 'bar/bat/'

         my $file2 = $dir / 'bat' + 'foo.txt'; # 'bar/bat/foo.txt'

       The file constructor:

         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;

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.

       The interface and style are quite different than the perl builtins or File::Spec.  The
       syntax is concise.  Errors are thrown with croak(), so you never need to check a return
       code.

Constructors

       The actual objects are in the 'Dir' and 'File' sub-namespaces.

   dir
         my $dir = File::Fu->dir($path);

       See "new" in File::Fu::Dir

   file
         my $file = File::Fu->file($path);

       See "new" in File::Fu::File

Class Constants

   tmp
       Your system's '/tmp/' directory (or equivalent of that.)

         my $dir = File::Fu->tmp;

   home
       User's $HOME directory.

         my $dir = File::Fu->home;

   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'.

         my $prog = File::Fu->program_name;

       If File::Fu was loaded after a chdir and the $0 was relative, calling program_name()
       throws an error.  (Unless you set $0 correctly before requiring File::Fu.)

   program_dir
       Returns what typically corresponds to program_name()->dirname, but just the compile-time
       cwd() when $0 is -e/-E.

         my $dir = File::Fu->program_dir;

Class Methods

   THIS_FILE
       A nicer way to say __FILE__.

         my $file = File::Fu->THIS_FILE;

   cwd
       The current working directory.

         my $dir = File::Fu->cwd;

   which
       Returns File::Fu::File objects of ordered candidates for $name found in the path.

         my @prog = File::Fu->which($name) or die "cannot find $name";

       If called in scalar context, returns a single File::Fu::File object or throws an error if
       no candidates were found.

         my $prog = File::Fu->which($name);

Temporary Directories and Files

       These class methods call the corresponding File::Fu::Dir methods on the value of tmp().
       That is, you get a temporary file/dir in the '/tmp/' directory.

   temp_dir
         my $dir = File::Fu->temp_dir;

   temp_file
         my $handle = File::Fu->temp_file;

Operators

       If you choose not to use the overloaded operators, you can just say "$obj->stringify()" or
       "$obj" whenever you want to drop the object-y nature and treat the path as a string.

       The operators can be convenient for building-up path names, but you probably don't want to
       think of them as "math on filenames", because they are nothing like that.

       The '+' and '/' operators only apply to directory objects.

         op   method                     mnemonic
         --   ----------------           --------------------
         +    $d->file($b) ............. plus (not "add")
         /    $d->subdir($b) ........... slash (not "divide")

       The other operators apply to both files and directories.

         op   method                     mnemonic
         --   ----------------           --------------------
         %=   $p->append($b) ........... mod(ify)
         %    $p->clone->append($b)
         &=   $p->map(sub{...}) ........ invoke subref
         &    $p->clone->map(sub {...})

       Aside:  It would be more natural to use ".=" as append(), but the way perl compiles "$obj
       foo" into "$obj . " foo"" makes it impossible to do the right thing because the lines
       between object and string are too ambiguous.

Subclassing

       You may wish to subclass File:Fu and override the dir_class() and/or file_class() class
       methods to point to your own Dir/File subclasses.

         my $class = 'My::FileFu';
         my $dir = $class->dir("foo");

       See File::Fu::File and File::Fu::Dir for more info.

   dir_class
         File::Fu->dir_class # File::Fu::Dir

   file_class
         File::Fu->file_class # File::Fu::File

See Also

       File::Fu::why if I need to explain my motivations.

       Path::Class, from which many an idea was taken.

       File::stat, IO::File, File::Spec, File::Find, File::Temp, File::Path, File::Basename,
       perlfunc, perlopentut.

AUTHOR

       Eric Wilhelm @ <ewilhelm at cpan dot org>

       http://scratchcomputing.com/

BUGS

       If you found this module on CPAN, 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.

       If you pulled this development version from my /svn/, please contact me directly.

COPYRIGHT

       Copyright (C) 2008 Eric L. Wilhelm, All Rights Reserved.

NO WARRANTY

       Absolutely, positively NO WARRANTY, 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.

LICENSE

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.