NAME
Module::MetaInfo - Report meta information from perl module distribution files
USAGE
use Module::MetaInfo.pm;
$mod=new Module::MetaInfo(perl-module-file.tar.gz);
$desc=$mod->description();DESCRIPTION
This module is designed to provide the primary interface to Perl meta information for perl module distribution files (this, however, is a prototype and hasn't yet been accepted by the "perl community", so don't count on it yet). The module is designed to allow perl modules to be easily and accurately packaged by other package systems such as RPM and DPKG.
The Module::MetaInfo module isn't actually designed to get any meta information from the perl module. Instead it serves as an entry point to other modules which have their own way of doing that. Since there isn't yet any agreed way to store meta-information in perl modules this may not be very reliable.
Currently there are two ways of getting meta information: a) guessing from the contents of the module and b) using a directory structure which has not yet been accepted by the perl community. The default way this module works is to first try b) then try a) then to give up.
IMPLEMENTATION AND INHERITANCE..
This module doesn't inherit anything. Instead it simply uses three different classes Module::MetaInfo::BestGuess Module::MetaInfo::AutoGuess and Module::MetaInfo::ModList, first trying functions from AutoGuess then from BestGuess and finally from ModList.
FUNCTIONS
Module::MetaInfo::new(<dist_filename> [<modlist_filename>)
new creates the object and initialises it. The argument is the path of the perl module distribution file.
If you provide the perl modules list then meta information from the modules list will be available.
$thing->::verbose() $thing->::scratch_dir()
These functions affect class settings (or if called for an object, only the settings of the object: afterwards that object will ignore changes to the class settings).
Currently implemented are verbose which prints debugging info and scratch_dir which sets the directory to be used for unpacking perl modules.
description / docs / etc...
These functions provide meta information. They are provided by the base classes. In all cases the functions will return undef if they are unable to get meta information of that kind. If there is no function then MetaInfo will die (croak). If you want to work with different versions of MetaInfo that may implement different sets of functions then use eval to catch the die.
For more information about the different functions available, see the subsidiary packages such as Module::MetaInfo::AutoGuess and Module::MetaInfo::DirTree.
N.B. we will throw an exception if you call a function which isn't provided by any of the modules. This is important since some functions are only present if a modules list has been provided to new. Either don't call those functions unless you have provided the modules list or catch the exception.
RETURN CONVENTIONS
Meta information function either return a scalar (name / description) or an array value. If an array is returned, it will actually be returned as a reference to an array if the function is used in a scalar context.
In Module::MetaInfo.pm the scalar return is always used so any modules used by it must provide this mode.
FUTURE FUNCTIONS
There are a number of other things which should be implemented. These can be guessed from looking at the possible meta-information which can be stored in the RPM or DPG formats, for example. Examples include:
copyright - GPL / as perl / redistributable / etc.
application area - Database / Internet / WWW / HTTP etc.
suggests - related applications
In many cases this data is generated currently by package building tools simply by using a fixed string. The function should do better than that in almost all cases or else it is't worth having...
COPYRIGHT
You may distribute under the terms of either the GNU General Public License, version 2 or (at your option) later or the Artistic License, as specified in the Perl README.
BUGS
Please see bugs in sub modules. Especially warnings in Module::MetaInfo::_Exctractor.
AUTHOR
Michael De La Rue.