NAME

Contentment::VFS - Provides a virtual file system for Contentment

DESCRIPTION

The purpose of a content management system is to provide a store for content. Unfortunately, it is difficult to determine how such content should be represented and stored. As such, this class provides (or will provide when I work on it some more) a "virtual file system" that allows the user to store components in a customized manner.

This class will provide the logic for determining which file system plugin to activate for a given path or set of paths. It will provide a system of virtual "moun points" on which different "file systems" can be nested. It will provide a way of natively accessing multiple versions of documents for file systems that provide such access. However, as of this writing, it does none of these things.

This class merely provides a direct window into the real file system.

STATUS

As of this writing, this really isn't much of a "VFS" at all. It is merely a wrapper for the regular file system. This should change in the future.

VFS API

The main class of the VFS is Contentment::VFS. This is a singleton object that can be referenced by doing:

$vfs = Contentment::VFS->new;

Once you have a $vfs object, you can use it to lookup files and directories. See the documentation on Contentment::VFS::Thing, Contentment::VFS::File, and Contentment::VFS::Directory below.

Contentment::VFS

$vfs = Contentment::VFS->new

Returns a reference to the VFS singleton object.

$thing = $vfs->lookup($path)

Given a path relative to the VFS root, this returns a reference to the matching Contentment::VFS::Thing or returns undef

$thing = $vfs->lookup_source($path)

This is like lookup, except that instead of looking for an exact filename match, this will attempt to find the first file that could be used as a source to generate output for the given path.

If the $path matches a file (not a directory) exactly, then the Contentment::VFS::Thing representing that file is returned.

If the $path matches a directory exactly, then this method checks to see if that directory contains an index. The index is any file starting with index with any file extension. If the directory doesn't contain an index file, then undef is returned.

Finally, this method searches for a file matching $path without regard to file extensions. If a match is found, it is returned.

In the case of multiple matches at any point, the choice of match is undefined.

@files = $vfs->glob(@globs)

Each glob in @globs should be a Unix-style file glob pattern relative to the VFS root. Each of these patterns is applied to the VFS to return any matching filename. The @files returned are merely full paths (within the VFS root) and not Contentment::VFS::Thing objects. The @files are returned in sorted order.

@files = $vfs->find($want, @dirs)

This method searches for all files within the given directories @dirs that match the criteria given by the subroutine reference $want. For each file found in each of the directories given, the Contentment::VFS::Thing object for that file is passwd to the $want subroutine. If the subroutine returns true, then the file is included in the resultant list of files @files.

In addition, the $want method can determine whether or not a subdirectory is descended. By default, all subdirectories are searched. However, this can be turned off directory-by-directory by setting the value of prune to true on that directory.

Contentment::VFS::Thing

This is the base class for all "things" stored in the VFS. Generally, all VFS plugins will provide at least a file thing. If a VFS may contain subdirectories, it should also provide a directory thing. Depending on the needs and capabilities, a VFS may also provide other kinds of things.

$path = $thing->root

I'm not sure of the value of this method generally, but it is very useful for the general file system plugin. It lets us know which Mason root contains this file.

$path = $thing->path

This names the VFS path to the thing.

$path = $thing->canonpath

I'm not sure of the value of this method generally, but it is very useful for the general file sysetm plugin. It gives us the full "real" path to the file in the file system.

$parent_thing = $thing->parent

Tries to find the thing that is the parent of this $thing. Either returns the Contentment::VFS::Thing found or undef.

$stat = $thing->stat

This performs a filesystem stat on the thing. This is only useful for the file system plugin.

$test = $thing->is_file

Returns true if this thing is a plain file.

$test = $thing->is_directory

Returns true if this thing is a directory.

$value = $thing->property($key)

Checks the thing to see if it has the named property. It either returns that property's value or undef.

$result = $thing->generate

This causes the output of the thing to be generated and printed to the currently selected file handle. The result of this generation is also returned.

Contentment::VFS::File

This class will most certainly be moved when the VFS implementation is completed. This code is specific to real file system access only.

$fh = $file_thing->open($access)

Opens the file associated with the $file_thing and returns a reference to the opened file handle or undef on failure. The $access value determines what access to the file is requested as per FileHandle.

@lines = $file_thing->lines

Returns all of the lines (newline terminated) of the file in a list.

$test = $file_thing->is_file

Always returns true.

$kind = $file_thing->real_kind

Determines the filetype of the file represented and returns the real kind of the file.

$kind = $file_thing->generated_kind

Determines the filetype of the file represented and returns the generated kind of the file.

$filetype = $file_thing->filetype

Returns the filetype plugin which matches the file thing.

$thing = $file_thing->lookup_source

Always returns $thing = $filething.

Contentment::VFS::Directory

This is specific to the filesystem plugin which will really be made it's own plugin rather than a built-in of the VFS at some future point.

$test = $dir_thing->is_directory

Alwayrs returns true.

$test = $dir_thing->prune($set_prune)

Used during find operations of Contentment::VFS to determine whether to descend into child directories. Setting it to true will result in files under this directory being skipped. Setting it to false will result in files under this directory to be scanned.

$thing = $dir_thing->lookup_source

This uses Contentment::VFS to attempt to find an index in the directory using lookup_source.

$filetype = $dir_thing->filetype

Always returns undef. Directories do not contain any content.

SEE ALSO

Contentment::FileType::Other, Contentment::FileType::Mason, Contentment::FileType::POD

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is distributed and licensed under the same terms as Perl itself.