NAME

       File::Fu::File - a filename object

SYNOPSIS

         use File::Fu;

         my $file = File::Fu->file("path/to/file");
         $file %= '.extension';
         $file->e and warn "$file exists";

         $file->l and warn "$file is a link to ", $file->readlink;

Constructor

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

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

   new_direct
         my $file = File::Fu::File->new_direct(
           dir => $dir_obj,
           file => $name
         );

Class Constants

   dir_class
       Return the corresponding dir class for this file object.  Default: File::Fu::Dir.

         my $dc = $class->dir_class;

   is_dir
       Always false for a file.

   is_file
       Always true for a file.

Parts

   basename
       Returns a new object representing only the file part of the name.

         my $obj = $file->basename;

Methods

   stringify
         my $string = $file->stringify;

   append
       Append a string only to the filename part.

         $file->append('.gz');

         $file %= '.gz';

       (Yeah... I tried to use .=, but overloading hates me.)

   map
         $file->map(sub {...});

         $file &= sub {...};

   absolute
       Get an absolute name (without checking the filesystem.)

         my $abs = $file->absolute;

   absolutely
       Get an absolute name (resolved on the filesytem.)

         my $abs = $file->absolutely;

Doing stuff

   open
       Open the file with $mode ('<', 'r', '>', 'w', etc) -- see IO::File.

         my $fh = $file->open($mode, $permissions);

       Throws an error if anything goes wrong or if the resulting filehandle happens to be a
       directory.

   sysopen
       Interface to the sysopen() builtin.  The value of $mode is a text string joined by '|'
       characters which must be valid O_* constants from Fcntl.

         my $fh = $file->sysopen($mode, $perms);

   piped_open
       Opens a read pipe.  The file is appended to @command.

         my $fh = $file->piped_open(@command);

       Example: useless use of cat.

         my $fh = $file->piped_open('cat');

       This interface is deprecated (maybe) because it is limited to commands which take the
       $file as the last argument.  See run() for the way of the future.

   run
       Treat $file as a program and execute a pipe open.

         my $fh = $file->run(@args);

       If called in void context, runs "system()" with autodie semantics and multi-arg form
       (suppresses shell interpolation.)

         $file->run(@args);

       No special treatment is made for whether $file is relative or not (the underlying
       "system()"/"exec()" will search your path.)  Use File::Fu->which() to get an absolute path
       beforehand.

         File::Fu->which('ls')->run('-l');

   touch
       Update the timestamp of a file (or create it.)

         $file->touch;

   mkfifo
         my $file = $file->mkfifo($mode);

   link
         my $link = $file->link($name);

   symlink
         my $link = $file->symlink($linkname);

       Note that symlinks are relative to where they live.

         my $dir = File::Fu->dir("foo");
         my $file = $dir+'file';
         # $file->symlink($dir+'link'); is a broken link
         my $link = $file->basename->symlink($dir+'link');

   relative_symlink
       See "relative_symlink" in File::Fu::Base.

   unlink
         $file->unlink;

   remove
       A forced unlink (chmod the file if it is not writable.)

         $file->remove;

   readlink
         my $to = $file->readlink;

   read
       Read the entire file into memory (or swap!)

         my @lines = $file->read;

         my $file = $file->read;

       If File::Slurp is available, options to read_file will be passed along.  See "read_file"
       in File::Slurp.

   write
       Write the file's contents.  Returns the $file object for chaining.

         $file = $file->write($content);

       If File::Slurp is available, $content may be either a scalar, scalar ref, or array ref.

         $file->write($content, %args);

   copy
       Copies $file to $dest (which can be a file or directory) and returns the name of the new
       file as an object.

         my $new = $file->copy($dest);

       Note that if $dest is already a File object, that existing object will be returned.

   move
         my $new = $file->move($dest);

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.