NAME

Path::Extended::Dir

SYNOPSIS

  use Path::Extended::Dir;

  my $dir = Path::Extended::Dir->new('path/to/dir');
  my $parent_dir = Path::Extended::Dir->new_from_file('path/to/some.file');

  # you can get information of the directory
  print $dir->basename;  # dir
  print $dir->absolute;  # /absolute/path/to/dir

  # you can get an object for the parent directory or children
  my $parent_dir = $dir->parent;
  my $sub_dir    = $dir->subdir('path/to/subdir');
  my $sub_file   = $dir->file('path/to/file');

  # Path::Extended::Dir object works like a directory handle
  $dir->open;
  while( my $entry = $dir->read ) {
    print $entry->basename, "\n";
  }
  $dir->close;

  # it also can do some extra file related tasks
  $dir->copy_to('/other/path/to/dir');
  $dir->unlink if $dir->exists;
  $dir->mkdir;

  $dir->recurse(prune => 1, callback => sub {
    my $entry = shift;  # Path::Extended::File/Dir object
    return if $entry->is_dir;
    print $entry->slurp;
  });

  foreach my $file ( $dir->find('*.txt') ) {
    print $file->relative, "\n";
  }

  # it has a logger, too
  $dir->log( fatal => "Couldn't open $dir: $!" );

DESCRIPTION

This class implements several directory-specific methods. See also Path::Class::Entity for common methods like copy and move.

METHODS

new, new_from_file

takes a path or parts of a path of a directory (or a file in the case of "new_from_file"), and creates a Path::Extended::Dir object. If the path specified is a relative one, it will be converted to the absolute one internally.

basename

returns the last part of the directory.

open, close, read, seek, tell, rewind

are simple wrappers of the corresponding built-in functions (with the trailing 'dir').

mkdir, mkpath

makes the directory via "File::Path::mkpath".

rmdir, rmtree, remove

removes the directory via "File::Path::rmtree".

find, find_dir

takes a File::Find::Rule's rule and a hash option, and returns "Path::Extended::*" objects of the matched files ("find") or directories ("find_dir") under the directory the $self object points to. Options are:

callback: You can pass a code reference to filter the objects.

  while (my $file = $dir->next) {
    next unless -f $file;
    $file->openr or die "Can't read $file: $!";
    ...
  }

returns a Path::Extended::Dir or Path::Extended::File object while iterating through the directory (or "undef" when there's no more items there). The directory will be open with the first "next", and close with the last "next".

children

returns a list of Path::Extended::Class::File and/or Path::Extended::Class::Dir objects listed in the directory. See Path::Class::Dir for details.

As of 0.13, this may take a "prune" option to exclude some of the children. See below for details.

file, subdir

returns a child Path::Extended::Class::File/Path::Extended::Class::Dir object in the directory.

file_or_dir

takes a file/subdirectory path and returns a Path::Extended::File object if it doesn't point to an existing directory (if it does point to a directory, it returns a Path::Extended::Dir object). This is handy if you don't know a path is a file or a directory. You can tell which is the case by calling ->is_dir method (if it's a file, ->is_dir returns false, otherwise true).

dir_or_file

does the same above but Path::Extended::Dir has precedence.

recurse

  dir('path/to/somewhere')->recurse( callback => sub {
    my $file_or_dir = shift;
    ...
  });

takes a hash and iterates through the directory and all its subdirectories recursively, and call the callback function for each entry. Options are:

callback

a code reference to call for each entry.

depthfirst, preorder

flags to change the order of processing.

prune

As of 0.13, you can use this option to prune some of the directory tree. You can provide a regular expression, a code reference, or a boolean value:

  # all the dot files/directories will be pruned (current default)
  $dir->recurse( prune => 1, callback => sub { ... });

  # nothing will be pruned (previous default)
  $dir->recurse( prune => 0, callback => sub { ... });

  # files/directories whose "basename" has a ".bak" suffix
  # will be pruned
  $dir->recurse( prune => qr/\.bak$/, callback => sub { ... });

  # ditto
  $dir->recurse( prune => \&prune, callback => sub { ... });

  sub prune {
    my $entry = shift;
    return $entry->basename =~ /\.bak$/ ? 1 : 0;
  }

subsumes, contains

returns if the path belongs to the object, or vice versa. See Path::Class::Dir for details.

volume

returns a volume of the path (if any).

AUTHOR

Kenichi Ishigaki, <ishigaki@cpan.org>

COPYRIGHT AND LICENSE

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