Provided by: libbadger-perl_0.16-3_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