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 a "virtual file system" that allows the user to store components in a customized manner.

This class is used to wrap File::System::Objects and provides additional functionality.

VFS API

The VFS class 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. Whenever possible, the VFS delegates work directly to File::System::Object, so see that documentation for the basic details. Any additional functionality is described in this document.

Contentment::VFS

$vfs = Contentment::VFS->new

Returns a reference to the VFS singleton object.

$source_obj = $obj->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 no path is given and $obj->has_content returns true, then $source_obj = $obj. If no path is given and $obj->has_content returns false, but $obj->is_container returns true, then a check is performed to see if a file named index.* can be found inside of the container. If so, that object is returned.

If the $path matches a file (not a directory) exactly, then the object 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 is arbitrary.

@properties = $obj->properties

When $obj->has_content returns true, this method will attempt to lookup the filetype and return the list of additional properties reported by the filetype in addition to those native to the filesystem.

$value = $obj->get_property($key)

When $obj->has_content returns true, this method will lookup both properties native to the file system and those for the file type plugin.

$headers = $obj->generate_headers(@_)

This method is only valid when has_content returns true. This calls the generate_headers method of the file type returned by the filetype method or returns an empty hash reference.

$result = $obj->generate(@_)

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

This method is only valid when has_content returns true. Generation differs from just calling the content method in that this uses the filetype to interpret and write the file. Generate may take arguments, which are passed directly on to the generate method of the associated file type plugin.

$kind = $file_thing->real_kind

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

This method is only valid when has_content is true.

$kind = $file_thing->generated_kind(@_)

Determines the filetype of the file represented and returns the generated kind of the file. Note that it is important to pass the same set of arguments to this method as to the generate method, as a file type plugin may generate different types based upon the arguments given.

This is only valid when has_content is true.

$filetype = $file_thing->filetype

Returns the filetype plugin which matches the file thing.

This is only valid when has_content is true.

@files = $obj->ancestors

This is a handy method that returns the parent, grandparent, and so forth for the current object $obj. The files are returned in order such that the ultimate parent is first and the nearest parent is last. (Handy for crumbtrail generation, etc.)

Returns an empty list if the current object is the root.

SEE ALSO

File::System, File::System::Other, File::System::Passthrough, 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.