/ 
Badger-0.16
River stage one • 4 direct dependents • 7 total dependents
/ Badger::Filesystem::Virtual

NAME

Badger::Filesystem::Virtual - virtual filesystem

SYNOPSIS

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

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

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

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

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

Andy Wardley http://wardley.org/

COPYRIGHT

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

SEE ALSO

Badger::Filesystem