NAME

Contentment::FileType - Contract all filetype plugins must adhere to

DESCRIPTION

The filetype plugins are used to determine a few important bits of information about VFS files in Contentment:

1. What kind of file is this?

2. What kind of file do I get when it is generated?

3. Are there any additional properties stored within this file's meetadata? What are they?

4. How do I generate this file?

FILE KIND

$preference = Contentment::FileType::TYPE->filetype_match($file)

The filetype plugin MUST provide a method named filetype_match. This method accepts a single argument, the VFS file to be checked. This method returns a numeric value. A return of zero indicates that this filetype plugin is unable to identify the filetype and should not be used. A return of one or greater indicates that this plugin is able to identify the filetype. Filetypes that return greater return values are preferred to those with lesser return values.

$kind = Contentment::FileType::TYPE->real_kind($file)

The filetype plugin MUST provide a method named real_kind. This method accepts a single argument, the VFS file to be checked. This method returns a string containing the name of the kind this file has in the VFS. This is the kind of file we would see if we simply read it's content from the disk. There is no required format for the name, but MIME types provide a common and simple starting point.

GENERATED KIND

$kind = Contentment::FileType::TYPE->generated_kind($file, @args)

The filetype plugin MUST provide a method named generated_kind. This method accepts at least a single argument, the VFS file to be checked. This method returns a string containing the name of the kind of file that will be generated if the generate method were called with this file and the exact same arguments @args. There is no required format for the name, but MIME types provide a common and simple starting point.

It is possible for this method to return undef, if no actual output is generated---i.e., as is the case if and only if a file is generated for the result from the generate method only and gives no output. If a method gives output, its kind should be given as a defined value, e.g., "unknown".

PROPERTIES

@property_keys = Contentment::FileType::TYPE->properties($file)

The filetype plugin MUST provide a method named properties. This method accepts a single argument, the VFS file to be checked. This method returns a list of strings containing the names of all metadata properties that can be found within the file.

$value = Contentment::FileType::TYPE->get_property($file, $key)

The filetype plugin MUST provide a method named get_property. This method accepts a two arguments, the VFS file to be checked and the name of a key to retrive. If there is a metadata value for the given file and key, then its value should be returned. Otherwise, the method should return undef.

GENERATION

$result = Contentment::FileType::TYPE->generate($file, @args)

The filetype plugin MUST provide a method named generate. This method accepts at least one argument, the VFS file to be checked. Any additional arguments may be used by the generator to alter the generation process or be passed on to the file while running if the file is a script or something similar.

Generation itself will involve the STDOUT file handle. The actual data generated will be sent to STDOUT. It may be that a generator expects some file input as well. In this case, the generator may read from STDIN to capture any input found there. Obviously, it is necessary when generating a file to redirect the input and output streams prior to generation. Contentment provides facilities to do this.

Finally, the generate function may return a value. The format for the return value is not defined and can be anything.

SEE ALSO

Contentment::FileType::Other is a good base class for filetype plugins.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.hanenkamp.com>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

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