Customised initialisation method specific to directories.

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).

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

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.

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/

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.

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)

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

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

This method deletes the directory permanently. Use it wisely.

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

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

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

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

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

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.

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

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

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

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.

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.

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.