--- name: "Badger::Filesystem::Directory" section: "3pm" platform: "linux" package: "libbadger-perl" version: "0.16-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Badger::Filesystem::Directory" --- # Badger::Filesystem::Directory(3pm) directory object ## 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 \ ## 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.