Eric Wilhelm > File-Fu-v0.0.6 > File::Fu::Dir

Download:
File-Fu-v0.0.6.tar.gz

Annotate this POD

Website

CPAN RT

New  2
Open  1
Stalled  1
View/Report Bugs
Source   Latest Release: File-Fu-v0.0.8

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.

  my $fc = $class->file_class;

is_dir

Always true for a directory.

is_file

Always false for a directory.

temp_dir_class

  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.

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');

  $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 end at -1.)

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

  my @parts = $dir->parts(3, -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

Equivelant 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

Not the same as File::Find::find().

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

finder

Returns an iterator for finding files.

  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 (is a file or dir object)
  }

And there is a knob:

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

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.

syntax highlighting: