Provided by: libfile-fu-perl_0.0.8-5_all bug

NAME

       File::Fu::Dir - a directoryname object

SYNOPSIS

         use File::Fu;

         my $dir = File::Fu->dir("path/to/dir");
         $dir->e and warn "$dir exists";

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

         foreach my $entry ($dir->list) {
           warn $entry . ': ' . $entry->stat->size, "\n"
             if($entry->f);
         }

Constructor

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

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

Class Constants/Methods

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

         my $fc = $class->file_class;

   is_dir
       Always true for a directory.

   is_file
       Always false for a directory.

   temp_dir_class
       Class for "temp_dir" objects.  Default: File::Fu::Dir::Temp.

         my $class = File::Fu::Dir->temp_dir_class;

   temp_file_class
         my $class = File::Fu::Dir->temp_file_class;

Methods

   stringify
         my $string = $dir->stringify;

   bare
       Stringify without the trailing slash/assertion.

         my $str = $self->bare;

       The trailing slash causes trouble when trying to address a symlink to a directory via a
       dir object.  Thus, "-l $dir" doesn't work, but "$dir->l" does the same thing as "-l
       $dir->bare".

   file
       Create a filename object with $dir as its parent.

         my $file = $dir->file($filename);

         my $file = $dir + $filename;

   append
       Append a string only to the last directory part.

         $dir->append('.tmp');

         $dir %= "something";

   subdir
         $newdir = $dir->subdir('foo');

         $newdir = $dir / 'foo';

   part
       Returns the $i'th part of the directory list.

         my $part = $dir->part($i);

       $dir->part(-1) is like $dir->basename, but not an object and not quite like
       File::Basename::basename() when it comes to the / directory.

   end
       Shorthand for part(-1);

   parts
       Retrieve the inner list of the directory's parts.

         my @parts = $dir->parts;

         my @parts = $dir->parts(0..2);

       The returned parts will be contiguous, but the request can be a two-element list (and can
       also start or end at negative indices.)

         my @parts = $dir->parts(3, 7);

         my @parts = $dir->parts(3, -1);

         my @parts = $dir->parts(-5, -1);

   slice
       Returns a new dir object as the return of parts().

         my $slice = $dir->slice(0);

         my $slice = $dir->slice(0,3);

   map
       Execute a callback on each part of $dir.  The sub should modify $_ (yes, this is slightly
       unlike the map() builtin.)

       If $parts is defined as an integer or array reference of integers, it will be treated as a
       slice on the directory parts to which the map should be applied.

         $dir->map(sub {...}, [@parts]);

         $dir &= sub {s/foo$/bar/};

       So, to modify only the first directory part:

         $dir->map(sub {s/foo$/bar/}, 0);

Properties

   is_cwd
       True if the $dir represents a relative (e.g. '.') directory.

         my $bool = $dir->is_cwd;

   basename
       Returns the last part of the path as a Dir object.

         my $bit = $dir->basename;

   dirname
       Returns the parent parts of the path as a Dir object.

         my $parent = $dir->dirname;

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

         my $abs = $dir->absolute;

   absolutely
       Get an absolute path (resolved on filesystem, so it must exist.)

         my $abs = $dir->absolutely;

Doing stuff

   open
       Calls opendir(), but throws an error if it fails.

         my $dh = $dir->open;

       Returns a directory handle, for e.g. readdir().

         my @files = map({$dir + $_} grep({$_ !~ m/^\./} readdir($dh)));

   touch
       Update the timestamp of a directory (croak if it doesn't exist.)

         $dir->touch;

   list
         my @paths = $dir->list(all => 1);

   lister
         my $subref = $dir->lister(all => 1);

   contents
       Equivalent to readdir.  With the 'all' option true, returns hidden names too (but not the
       '.' and '..' entries.)

       The return values are strings, not File::Fu objects.

         my @names = $dir->contents(all => 1);

   iterate_contents
       Returns a subref which will iterate over the directory's contents.

         my $subref = $dir->iterate_contents(all => 1);

   find
       Recursively search a directory's contents for items where the supplied coderef (matcher)
       returns true.  The matcher will be invoked with the topic ($_) set to the current path
       (which is either a Dir or File object.) The return values will be File::Fu::File or
       File::Fu::Dir objects.

       If your matcher returns true, the topic will be added to the return values.

         my @paths = $dir->find(sub {m/foo/});

       There is a knob for controlling recursion, which is the first argument to your matcher.

         my @pm_files = $dir->find(sub {
           return shift->prune
             if($_->is_dir and $_->part(-1) =~ m/^\.svn$/);
           $_->is_file and m/\.pm$/;
         });

       Differences from File::Find::find()
           The invocant ($dir aka '.') is not examined (because this is an object method, there
           is always only one starting path.)

           The topic is always absolute in the same sense as the invocant.  That is, if $dir is
           relative to your current directory, then so are the topics and return values.  If $dir
           is absolute, so are the topics and return values.

   finder
       Returns an iterator for finding files.  This iterator does everything that find() does,
       but returns one path at a time.  Returns undef when exhausted and zero when it is just
       taking a break.

         my $subref = $dir->finder(sub {$_->is_file and $_->file =~ m/foo/});

       This allows a non-blocking find.

         while(defined(my $path = $subref->())) {
           $path or next; # 0 means 'not done yet'
           # do something with $path (a file or dir object)
         }

       The find() method is implemented in terms of finder() by simply using a while() loop and
       accumulating the return values.

   The FindKnob object
       The FindKnob object allows you to control the next steps of find().  Methods called on it
       will typically return a value which also makes sense as a return value of your matcher
       sub.  Thus the idiom:

         $dir->find(sub {return shift->prune if(condition); ...})

       prune
           Do not recurse into the topic directory.  Returns false.

   mkdir
       Create the directory or croak with an error.

         $dir->mkdir;

         $dir->mkdir(0700);

   create
       Create the directory, with parents if needed.

         $dir->create;

   rmdir
       Remove the directory or croak with an error.

         $dir->rmdir;

   remove
       Remove the directory and all of its children.

         $dir->remove;

   unlink
         $link->unlink;

   symlink
       Create a symlink which points to $dir.

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

       Note that symlinks are relative to where they live, so if $dir is a relative path, it must
       be relative to $linkname.

   readlink
         my $to = $file->readlink;

Changing Directories

   chdir
       Change to the directory in self, returning a new '.' directory object.

         $dir = $dir->chdir;

   chdir_for
       Change to $dir and run the given subroutine.  The sub will be passed a './' directory
       object.

         $dir->chdir_for(sub {...});

   chdir_local
       Change to $dir, but return to the current cwd when $token goes out of scope.

         my $token = $self->chdir_local;

Temporary Directories and Files

       These methods use the $dir object as a parent location for the temp path.  To use your
       system's global temp space (e.g. '/tmp/'), just replace $dir with 'File::Fu'.

         File::Fu->temp_dir;              # '/tmp/'
         File::Fu->dir->temp_dir;         # './'
         File::Fu->dir("foo")->temp_dir;  # 'foo/'

         File::Fu->temp_file;             # '/tmp/'
         File::Fu->dir->temp_file;        # './'
         File::Fu->dir("foo")->temp_file; # 'foo/'

   temp_dir
       Return a temporary directory in $dir.

         my $dir = $dir->temp_dir;

   temp_file
       Return a filehandle to a temporary file in $dir.

         my $handle = $dir->temp_file;

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.