Dependencies

Annotate this POD

# CPAN RT

 New 3 Open 2
View/Report Bugs

# SYNOPSIS

    # using either of Badger::Filesytem constructor subroutines

# use native OS-specific paths:
$dir = Dir('/path/to/dir'); # or generic OS-independent paths$dir = Dir('path', 'to', 'dir');

# Dir is short for Directory if you prefer longness
$dir = Directory('/path/to/dir');$dir = Directory('path', 'to', 'dir');

# manual object construction

# positional arguments
$dir = Badger::Filesystem::Directory->new('/path/to/file');$dir = Badger::Filesystem::Directory->new(['path', 'to', 'file']);

# named parameters
$dir = Badger::Filesystem::Directory->new( path => '/path/to/dir' # native );$dir = Badger::Filesystem::Directory->new(
path => ['path', 'to', 'dir']       # portable
);

# path inspection methods
$dir->path; # full path$dir->directory;                # same as path()
$dir->dir; # alias to directory()$dir->base;                     # same as path()
$dir->volume; # path volume (e.g. C:)$dir->is_absolute;              # path is absolute
$dir->is_relative; # path is relative$dir->exists;                   # returns true/false
$dir->must_exist; # throws error if not @stats =$dir->stat;            # returns list
$stats =$dir->stat;            # returns list ref

# path translation methods
$dir->relative; # relative to cwd$dir->relative($base); # relative to$base
$dir->absolute; # relative to filesystem root$dir->definitive;               # physical file location
$dir->collapse; # resolve '.' and '..' in$file path

# path comparison methods
$dir->above($another_path);     # $dir is ancestor of$another_path
$dir->below($another_path);     # $dir is descendant of$another_path

# directory manipulation methods
$dir->create; # create directory$dir->delete;                   # delete directory
$fh =$dir->open;               # open directory to read

@data  = $dir->read; # return directory index @kids =$dir->children;         # objects for each file/subdir
@files = $dir->files; # objects for each file in dir @dirs =$dir->dirs;             # objects for each sub-dir in dir
@dirs  = $dir->directories; # same as dirs() # DESCRIPTION The Badger::Filesystem::Directory module is a subclass of Badger::Filesystem::Path for representing directories in a file system. You can create a file object using the Dir constructor function in Badger::Filesystem. This is also available as Directory if you prefer longer names.  use Badger::Filesystem 'Dir'; Directory paths can be specified as a single string using your native filesystem format or as a list or reference to a list of items in the path for platform-independent paths.  my$dir = Dir('/path/to/dir');

If you're concerned about portability to other operating systems and/or file systems, then you can specify the directory path as a list or reference to a list of component names.

    my $dir = Dir('path', 'to', 'dir'); my$dir = Dir(['path', 'to', 'dir']);

# METHODS

In addition to the methods inherited from Badger::Filesystem::Path, the following methods are defined or re-defined.

## init(\%config)

Customised initialisation method specific to directories.

## exists

Returns true if the directory exists in the filesystem. Returns false if the directory does not exists or if it is not a directory (e.g. a file).

## is_directory() / is_dir()

This method returns true for all Badger::Filesystem::Directory instances.

## volume() / vol()

Returns any volume defined as part of the path. This is most commonly used on Win32 platforms to indicate drive letters, e.g. C:.

    # on MS Windows
print Dir('C:\\foo\\bar')->volume;   # C

This always returns $self for directories. ## canonical() This returns the canonoical representation of the directory path. This is the absolute path with a trailing slash added (or whatever the relevant directory separator is for your filesystem).  print Dir('/foo/bar')->canonical; # /foo/bar/ ## directory() / dir() Returns the complete directory path when called without arguments. This is effectively the same thing as path() or base() returns, given that this object is a directory. This can also be used with an argument to locate another directory relative to this one.  my$dir = Dir('/path/to/dir');
print $dir->dir; # /path/to/dir (auto-stringified) print$dir->dir('subdir');          # /path/to/dir/subdir (ditto)

Directories are returned as new Badger::Filesystem::Directory objects. The above examples are relying on the auto-stringification to display the path when printed.

## file($name) This method can be used to locate a file relative to the directory. The file is returned as a Badger::Filesystem::File object.  my$dir  = Dir('/path/to/dir');
my $file =$dir->file('example.txt');
print $file->path; # /path/to/dir/example.txt print$file;                        # same (auto-stringified)

## create()

This method can be used to create the directory if it doesn't already exist.

    Dir('/path/to/dir')->create;

## delete()

This method deletes the directory permanently. Use it wisely.

    Dir('/tmp/junk')->delete;

## mkdir($subdir) This method can be used to create a sub-directory.  my$dir = Dir('/tmp');
$dir->mkdir('junk'); # /tmp/junk When called without an argument it has the same effect as create() in creating itself.  my$dir = Dir('/tmp/junk');
$dir->mkdir; # same as$dir->create

## rmdir($subdir); This does the opposite of mkdir() but works in the same way. It can be used to delete a sub-directory:  my$dir = Dir('/tmp');
$dir->rmdir('junk'); # /tmp/junk Or the directory itself when called without an argument:  my$dir = Dir('/tmp/junk');
$dir->rmdir; # same as$dir->delete

## open()

This method opens the directory and returns an IO::Dir handle to it.

    $fh =$dir->open;
while (defined($item =$fh->read)) {
print $item, "\n"; } ## read($all)

This method read the contents of the directory. It returns a list (in list context) or a reference to a list (in scalar context) containing the names of the entries in the directory.

    my @entries = $dir->read; # list in list context my$entries = $dir->read; # list ref in scalar context By default, the . and .. directories (or the equivalents for your file system) are ignored. Pass a true value for the $all flag if you want them included.

## children($all) Returns the entries of a directory as Badger::Filesystem::File or Badger::Filesystem::Directory objects. Returns a list (in list context) or a reference to a list (in scalar context).  my @kids =$dir->children;          # list in list context
my $kids =$dir->children;          # list ref in scalar context

## files()

Returns a list (in list context) or a reference to a list (in scalar context) of all the files in a directory as Badger::Filesystem::File objects.

    my @files = $dir->files; # list in list context my$files = $dir->files; # list ref in scalar context ## directories() / dirs() Returns a list (in list context) or a reference to a list (in scalar context) of all the sub-directories in a directory as Badger::Filesystem::Directory objects.  my @dirs =$dir->dirs;              # list in list context
my $dirs =$dir->dirs;              # list ref in scalar context

## visit($visitor) Entry point for a filesystem visitor for visit a directory. A reference to a Badger::Filesystem::Visitor object (or subclass) should be passed as the first argument.  use Badger::Filesystem::Visitor; my$visitor = Badger::Filesystem::Visitor->new( in_dirs => 1 );
$dir->visit($visitor);

Alternately, a list or reference to a hash array of named parameters may be provided. These will be used to instantiate a new Badger::Filesystem::Visitor object (via the Badger::Filesystem visitor() method) which will then be applied to the directory. If no arguments are passed then a visitor is created with a default configuration.

    # either list of named params
$dir->visit( in_dirs => 1 ); # or reference to hash array$dir->visit({ in_dirs => 1});

This method is called to dispatch a visitor to the correct method for a filesystem object. In the Badger::Filesystem::Directory class, it calls the visitor visit_directory() method, passing the $self object reference as an argument. ## enter($visitor)

This is a custom variant of the accept() method which is called by a visitor when it first enters a filesystem. Instead of calling the visitor visit_directory() method, it calls visit_directory_children() passing \$self as an argument to begin visiting the files and sub-directories contained in this directory.

# AUTHOR

Andy Wardley http://wardley.org/

The Badger::Filesystem modules are built around a number of existing Perl modules, including File::Spec, File::Path, Cwd, IO::File, IO::Dir and draw heavily on ideas in Path::Class.