Provided by: libbadger-perl_0.16-2_all 
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