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

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.