Badger::Filesystem::Directory
- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- init(\%config)
- exists
- is_directory() / is_dir()
- volume() / vol()
- base()
- canonical()
- directory() / dir()
- file($name)
- create()
- delete()
- mkdir($subdir)
- rmdir($subdir);
- open()
- read($all)
- children($all)
- files()
- directories() / dirs()
- visit($visitor)
- accept($visitor)
- enter($visitor)
- AUTHOR
- COPYRIGHT
- ACKNOWLEDGEMENTS
- SEE ALSO
# 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()
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']);
In addition to the methods inherited from Badger::Filesystem::Path, the following methods are defined or re-defined.
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 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.
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.
Please see the ACKNOWLEDGEMENTS in Badger::Filesystem for further information.