Badger::Filesystem::Virtual - virtual filesystem

Badger documentation Contained in the Badger distribution.

Index

Code Index:

NAME

Top

Badger::Filesystem::Virtual - virtual filesystem

SYNOPSIS

Top

    use Badger::Filesystem::Virtual;

    my $fs = Badger::Filesystem::Virtual->new(
        root => ['/path/to/dir/one', '/path/to/dir/two'],
    );
    my $file = $fs->file('/example/file');
    my $dir  = $fs->dir('/example/directory');

    if ($file->exists) {        # under either root directory
        print $file->text;      # loaded from correct location
    }
    else {                      # writes under first directory
        $file->write("hello world!\n");
    }

INTRODUCTION

Top

This module defines a subclass of Badger::Filesystem for creating virtual filesystems that are "mounted" onto one or more underlying source directories in a real file system (if you're familiar with the Template Toolkit then think of the INCLUDE_PATH). If that doesn't mean much to you then the chances are that you don't need to read this documentation. Either way you should read the documentation for Badger::Filesystem first, closely followed by Badger::Filesystem::Path, Badger::Filesystem::File and Badger::Filesystem::Directory.

Done that now? Good, welcome back. Let us begin.

DESCRIPTION

Top

Badger::Filesystem::Virtual module is a specialised subclass of the Badger::Filesystem module. In contrast to Badger::Filesystem module which gives you access to the files and directories in a real filesystem, Badger::Filesystem::Virtual allows you to create a virtual filesystem mounted under a real directory, or composed from a number of real directories.

    use Badger::Filesystem::Virtual;

    # virtual file system with single root
    my $vfs1 = Badger::Filesystem::Virtual->new(
        root => '/path/to/virtual/root',
    );

    # virtual file system with multiple roots
    my $vfs2 = Badger::Filesystem::Virtual->new(
        root => [
            '/path/to/virtual/root/one',
            '/path/to/virtual/root/two',
        ],
    );

The module defines the exportable VFS symbol as an alias for Badger::Filesystem::Virtual to save on typing:

    use Badger::Filesystem::Virtual 'VFS';

    my $vfs1 = VFS->new( root => '/path/to/virtual/root' );

You can also access this via the Badger::Filesystem module.

    use Badger::Filesystem 'VFS';

TODO: and eventually the Badger module...

Single Root Virtual Filesystem

A filesystem object with a single virtual root directory works in a similar way to the chroot command.

    use Badger::Filesystem::Virtual 'VFS';

    my $vfs1 = VFS->new( root => '/my/web/site' );

Any absolute paths specified for this file system are then assumed to be relative to the virtual root. For example, we can create an object to represent a file in our virtual file system.

    my $home = $vfs1->file('index.html');

This file as a relative path of index.html.

    print $home->relative;                     # index.html

The absolute path is /index.html.

    print $home->absolute;                     # /index.html

However, the real, physical path to the file is relative to the virtual root directory. The definitive() method returns this path.

    print $home->definitive;                   # /my/web/site/index.html

You can open, read, write and generally perform any kind of operation on a file or directory in a virtual file system the same way as you would for a real file system (i.e. one without a virtual root directory defined). Behind the scenes, the filesystem object handles the mapping of paths in the virtual file system to their physical counterparts via the definitive method. 

    my $text = $home->read;                     # read file
    $home->write($text);                        # write file
    $home->append($more_text);                  # append file
    # ...etc...

Multiple Root Virtual File System

Things get a little more interesting when you have a virtual filesystem with multiple root directories.

    use Badger::Filesystem::Virtual 'VFS';

    my $vfs2 = VFS->new( root => [
        '/my/root/dir/one',
        '/my/root/dir/two'
    ] );

The handling of relative and absolute paths is exactly the same as for a single root virtual file system. 

    my $home = $vfs2->file('index.html');
    print $home->relative;                     # index.html
    print $home->absolute;                     # /index.html

You can call any of the regular methods on Badger::Filesystem::File and Badger::Filesystem::Directory objects as you would for a normal file system, and leave it up to the Badger::Filesystem::Virtual module to Do The Right Thing to handle the mapping.

    print $home->text;          # locates file under either root dir
    print $home->size;

If you look at the contents of a directory, you'll see the combined contents of that directory under any and all virtual roots that contain it.

    my $dir = $vfs2->dir('foo');
    print join "\n", $dir->children;

The children() method in this example will returns all the files and sub-directories in both /my/root/dir/one/foo and /my/root/dir/two.

The definitive_read() and definitive_write() methods are used to map virtual paths onto their real counterparts whenever you read, write, or perform any other operation on an underlying file or directory. For read operations, the definitive_read() method will look for the file or directory under each of the virtual root directories until it is located or presumed not found. The definitive_write() method always maps paths to the first root directory (NOTE: we'll be providing some options to customise this at some point in the future - be aware for now that the append() method may not work correctly if you're trying to append to a file that isn't under the first root directory).

Dynamic Root Directories

TODO: we now support code refs and objects as root directories which are evaluated dynamically to generate a list of root directories. An object should have a path(), paths() or roots() method which returns a single path or refererence to a list of path. Any of those can be further dynamic components which will be evaluated recursively until all have been resolved or the max_roots limit has been reached.

METHODS

Top

Badger::Filesystem::Virtual inherits all the methods of Badger::Filesystem. The following methods are added or amended.

init(\%config)

This custom initialisation method allows one or more root (or rootdir) directories to be specified as the base of the virtual filesystem.

roots()

This method returns a list (in list context) or reference to a list (in scalar context) of the root directories for the virtual filesystem. Any dynamic components in the roots will be evaluated and expanded. This include subroutine references and objects implementing a path(), paths() or roots() method. Dynamic components can return a single items or reference to a list of items, any of which can be a static directory or dynamic component.

definitive($path)

This is aliased to the definitive_write() method.

definitive_write($path)

Maps a virtual file path to a definitive one for write operations. The path will be mapped to the first virtual root directory.

definitive_read($path)

Maps a virtual file path to a definitive one for read operations. The path will be mapped to the first virtual root directory in which the item exists. If it does not exists in any of the virtual root directories then an undefined value is returned.

definitive_paths($path)

Returns a list (in list context) or reference to a list (in scalar context) of all the definitive paths that the file path could be mapped to. This is generating by adding the $path argument onto each of the root directories.

read_directory($path)

Custom method to read a directory in a virtual filesystem. This returns a composite index of all entries in a particular directory across all roots of the virtual filesystem.

OPTIONS

Top

root

The root directory or directories of the virtual filesystem.

max_roots

A limit to the maximum number of root directories allowed. This is used to prevent potential runaways when evaluating dynamic root components. See Dynamic Root Directories for further information.

AUTHOR

Top

Andy Wardley http://wardley.org/

COPYRIGHT

Top

Copyright (C) 2005-2009 Andy Wardley. All rights reserved.

SEE ALSO

Top

Badger::Filesystem

Badger documentation Contained in the Badger distribution. 
#========================================================================
#
# Badger::Filesystem::Virtual
#
# DESCRIPTION
#   Subclass of Badger::Filesystem which implements a virtual filesystem
#   composed from several source directories, conceptually layered on
#   top of each other.  
#
# AUTHOR
#   Andy Wardley   <abw@wardley.org>
#
#========================================================================

package Badger::Filesystem::Virtual;

use Badger::Debug ':dump';
use Badger::Class
    version   => 0.01,
    debug     => 0,
    base      => 'Badger::Filesystem',
#   accessors => 'root',                    # interferes
    constants => 'ARRAY CODE',
    constant  => {
        VFS          => __PACKAGE__,
        virtual      => __PACKAGE__,
        PATH_METHOD  => 'path',
        PATHS_METHOD => 'paths',
        ROOTS_METHOD => 'roots',
    },
    exports   => {
        any   => 'VFS',
    },
    messages => {
        bad_root  => 'Invalid root directory: %s', 
        max_roots => 'The number of virtual filesystem roots exceeds the max_roots limit of %s',
    };

*definitive = \&definitive_write;

our $MAX_ROOTS = 32 unless defined $MAX_ROOTS;

sub init {
    my ($self, $config) = @_;

    # let the base class have a go first, so it can set rootdir et al
    $self->SUPER::init($config);

    # root can be a single item or list ref
    my $root = $config->{ root } || $self->{ rootdir };
    $root = [$root] unless ref $root eq ARRAY;
    $self->{ root } = $root;

    # the dynamic flag indicates that the list of roots can change so we must 
    # recompute them each time we use them.  max_roots sets a limit on the 
    # expansion to prevent runaways
    $self->{ dynamic   } = $config->{ dynamic };
    $self->{ max_roots } = 
        defined $config->{ max_roots } 
              ? $config->{ max_roots }
              : $MAX_ROOTS;
    
    # we must set cwd to / so that the relative -> absolute path translation
    # works as expected.  The concept of having a current working directory 
    # in a VFS is just a bit too weird to contemplate anyway.
    $self->{ cwd } = $self->{ rootdir };
    
    $self->debug("Virtual root: ", join(', ', @$root), "\n" ) if $DEBUG;
    
    return $self;
}

sub roots {
    my $self = shift;

    if (my $roots = $self->{ roots }) {
        return wantarray
            ? @$roots
            :  $roots;
    }

    my $max    = $self->{ max_roots };
    my @paths  = @{ $self->{ root } };
    my (@roots, $type, $paths, $dir, $code);

    # If a positive max_roots is defined then we'll limit the number of 
    # roots we resolve.  If it's zero or negative then it will pre-decrement
    # before being tested so will always be true
    while (@paths && --$max) {
        $dir = shift @paths || next;

        $type = ref $dir || do {
            # non-reference paths get added as they are
            $self->debug("discovered root directory: $dir\n") if DEBUG;
            push(@roots, $dir);
            next;
        };

        # anything else can expand out to one or more paths, each of which
        # can expand recursively, so we push all new paths back onto the
        # candidate list and test each in turn.
        
        if ($type eq CODE) {
            # call code ref
            $paths = $dir->();
            $self->debug(
                "discovered root directories from code ref: ",
                $self->dump_data_inline($paths), "\n"
            ) if DEBUG;
            unshift(@paths, ref $paths eq ARRAY ? @$paths : $paths);
            next;
        }
        elsif ($type eq ARRAY) {
            # expand list ref
            $self->debug(
                "discovered root directories from code ref: ",
                join(', ', @$dir), "\n"
            ) if DEBUG;
            unshift(@paths, @$dir);
            next;
        }
        elsif (blessed $dir) {
            # see if object has a path(), paths() or roots() method
            # TODO: this is broken - we don't want to recompute paths 
            # each time just because we're using an object that has a 
            # path
            if ($code = $dir->can(PATH_METHOD)
                     || $dir->can(PATHS_METHOD)
                     || $dir->can(ROOTS_METHOD) ) {
                $paths = $code->($dir);
                $self->debug(
                    "discovered root directories from $type object: $paths / ", 
                    $self->dump_data_inline($paths), "\n"
                ) if DEBUG;
                unshift(@paths, ref $paths eq ARRAY ? @$paths : $paths);
                next;
            }
        }

        $self->error( bad_root => $dir );
    }

    # anything left in @paths means we must have blown the max_roots limit
    return $self->error_msg( max_roots => $self->{ max_roots } )
        if @paths;

    # we can cache roots if all are static and the dynamic flag isn't set
    $self->{ roots } = \@roots
        unless $self->{ dynamic };
    
    $self->debug("resolved roots: [\n  ", join("\n  ", @roots), "\n]\n") if DEBUG;
    
    return wantarray
        ?  @roots
        : \@roots;
}

sub definitive_paths {
    my $self  = shift;
    my $path  = $self->absolute(@_);
    my @paths = map { $self->merge_paths($_, $path) } $self->roots;
    return wantarray
        ?  @paths
        : \@paths;
}

sub definitive_write {
    my $self = shift;
    $self->debug("definitive_write(", join(', ', @_), ")\n") if DEBUG;
    my $path = $self->absolute(@_);
    return $self->join_directory($self->roots->[0], $path);
}

sub definitive_read {
    my $self = shift;
    my $path = $self->absolute(@_);
    my ($base, $full);

    foreach $base ($self->roots) {
        $full = $self->merge_paths($base, $path);
        $self->debug("looking for [$base] + [$path] => $full\n") if DEBUG;
        return $full if -e $full;
        $self->debug("not found\n") if DEBUG;
    }
    return undef;
}

sub read_directory {
    my $self = shift;
    my $path = $self->absolute(shift);
    my $all  = shift;
    my ($base, $full, $dirh, $item, @items, %seen);

    require IO::Dir;

    foreach $base ($self->roots) {
        $full = $self->join_directory($base, $path);
        $self->debug("Opening directory: $full\n") if DEBUG;
        $dirh = IO::Dir->new($full)
            || next;
# Some directory may not exist, so ignore them
#           || $self->error_msg( open_failed => directory => $full => $! );
        while (defined ($item = $dirh->read)) {
            push(@items, $item) unless $seen{ $item }++;
        }
        $dirh->close;
    }
    @items = $self->FILESPEC->no_upwards(@items)
        unless $all || ref $self && $self->{ all_entries };

    return wantarray ? @items : \@items;
}


1;

__END__


# Local Variables:
# mode: Perl
# perl-indent-level: 4
# indent-tabs-mode: nil
# End:
#
# vim: expandtab shiftwidth=4:
# TextMate: rocks my world