Provided by: libbadger-perl_0.16-3_all 
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 <http://wardley.org/>
COPYRIGHT
Copyright (C) 2005-2009 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.