GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BADGER::FILESYSTEM::DIRECTORY (3)

.ds Aq ’

NAME

Badger::Filesystem::Directory - directory object

CONTENTS

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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 BADGER::FILESYSTEM::DIRECTORY (3) 2010-02-20

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.