NAME

Badger::Filesystem::Directory - directory object

SYNOPSIS

# using either of Badger::Filesytem constructor subroutines
use Badger::Filesystem 'Dir Directory';

# 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
use Badger::Filesystem::Directory;

# 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

# all-in-one read/write methods
@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

base()

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

The method then calls the visitor visit() passing $self as an argument to begin visiting the directory.

accept($visitor)

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 <abw@wardley.org>

COPYRIGHT

Copyright (C) 2005-2008 Andy Wardley. All rights reserved.

ACKNOWLEDGEMENTS

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.

Please see the ACKNOWLEDGEMENTS in Badger::Filesystem for further information.

SEE ALSO

Badger::Filesystem, Badger::Filesystem::Path, Badger::Filesystem::File, Badger::Filesystem::Visitor.

cpanm Badger

perl -MCPAN -e shell
install Badger