Module::Versions - Handle versions of loaded modules with flexible result interface
This documentation refers to Module::Versions Version 0.01 $Revision: 522 $
Precautions: Alpha Release.
use Module::Versions; # Simple Interface list Module::Versions; # prints formatted results to STDOUT Module::Versions->list; # prints formatted results to STDOUT # Shortcuts $vers = get Module::Versions; # retrieves loaded modules $vers = Module::Versions->get; # retrieves loaded modules $array = Module::Versions->ARRAY; # returns array with version infos $hash = Module::Versions->HASH; # returns hash with version infos $list = Module::Versions->SCALAR; # returns text list with version infos $csv = Module::Versions->CSV; # returns csv list with version infos $xml = Module::Versions->XML; # returns xml struct with version infos $xsd = Module::Versions->XSD; # returns xml schema of version infos $dtd = Module::Versions->DTD; # returns DTD of version infos # Individual Parameters $vers = Module::Versions # retrieves mods and vars as defined ->new($mods,$vars) ->get($criteria); $vers->list($fd,$mask); # prints formatted results to file $vers->list($fd,$preform); # prints preformatted results to file $vers->list($fd,\&cb); # prints serialied results as handled # in callback routine $vers->data(\&cb); # returns transformed results as # defined in callback routine # Individual formatted output list Module::Versions(*LOG, '%5d %1s %-20s %10s %-16s'); # prints individually formatted # results to LOG list Module::Versions(*DBIMPORT, '%s|%s|%s'); # prints individually formatted # results to Database Import file list Module::Versions(*FD, 'SCALAR');# prints text list results to file list Module::Versions(*FD, 'CSV'); # prints csv list results to file list Module::Versions(*FD, 'XML'); # prints xml struct results to file list Module::Versions(*FD, 'XSD'); # prints xml schema to file list Module::Versions(*FD, 'DTD'); # prints DTD to file list Module::Versions(*FD, 'ARRAY'); # prints serialized results to file list Module::Versions(*FD, 'HASH'); # prints serialized results to file Module::Versions->list(*LOG); # prints formatted results to LOG # Pretty Compact Module::Versions->list # prints formatted results on STDOUT ->list(*XML,'XML'); # prints xml struct results to XML file Module::Versions->list # prints formatted results on STDOUT ->list(*XSD,'XSD') # prints xml schema to XSD file ->list(*XML,'XML'); # prints xml struct results to XML file Module::Versions->list # prints formatted results on STDOUT ->list(*DTD,'DTD') # prints DTD to DTD file ->list(*XML,'XML'); # prints xml struct results to XML file
Module::Versions handles versions of loaded modules with a flexible result interface. The main goal is to get as much version informations as possible about a module or module list with a simple call interface and an absolutely flexible result interface. Module::Versions handles *loaded* and *loadable* modules.
The motivation for writing this module was the need for better support facilities to get informations about the used modules and versions in the productivity environment. Module::Versions allows shipping applications basically with something like a '-version' option (See Getopt::Long) but with expanded functions.
Module::Versions tries to read the loaded/loadable module's $VERSION. For extended purposes any private project 'version variables' can be fetched ($_VERSION, $version, $REV, etc.).
Module::Versions has a flexible result interface to satisfy different needs: results can be lists and data structures with different formats - pre-formed ARRAY, HASH, SCALAR, CSV, XML/XSD/DTD and a full flexible user callback interface.
It is for example very simple to print a good formatted version list to the console and save a version.xml file (in conjunction with an xsd-schema) at the same time with an absolutely minimum of coding (SYNOPSIS, Pretty Compact) .
Module::Versions tries to load 'version.pm' to support Perl 5.10.0's $VERSION formatting.
Module::Versions Methods can be called as
Class methods: e.g. Module::Versions->new; Instance methods: e.g. $versions->new; Indirect objects: e.q. new Module::Versions;
The standard chaining can be written with shortcuts:
1.) Module::Versions->new->get; 2.) Module::Versions->new->get->list; 3.) Module::Versions->new->get->data; 4.) Module::Versions->new->get->XML; 5.) $versions = Module::Versions->new->get-list; $versions->list(*XSD, 'XSD'); $versions->list(*XML, 'XML'); can be written as 1.) Module::Versions->get; # result is an object 2.) Module::Versions->list; # result is an object and a printed list 3.) Module::Versions->data; # result is an ARRAY 4.) Module::Versions->XML; # result is a XML scalar 5.) Module::Versions->list # result is an object and a printed list ->list(*XSD,'XSD') # result is a XSD schema in file *XSD ->list(*XML,'XML'); # result is a XML scalar in file *XML
new
get, list, data
get
list
data
ARRAY, HASH, SCALAR, CSV, XML, XSD, DTD
ARRAY
HASH
SCALAR
CSV
XML
XSD
DTD
new(<MODULES>, <SELECTION>)
Creates a new Versions object.
The object contains a list of module names and a list of variables, which will be scanned in addition to $VERSION. The module list contains explicitely defined names or the internal %INC names.
String or ARRAY of strings; default is content of %INC.
String or ARRAY of strings; default is 'VERSION'.
This may be a list of project specific version variables that can be observed in addition to the Perl standard variable '$VERSION', e.g. '$_VERSION', '$version', '$REV'. See '$_VERSION' in this source (='Mumified VERSION').
The selection of the Perl standard variable '$VERSION' is mandantory and cannot be reset.
get(<CRITERIA>)
Retrieve <MODULES> as defined before and use the <SELECTION> as defined in object by the constructor.
<MODULES>
<SELECTION>
The result can be accessed by list, data or the shortcuts ARRAY, HASH, SCALAR, CSV and XML.
String or ARRAY of strings; default formatting of the version info will be done as 'normal' (e.g. v0.10.0), if the module 'version.pm' ("SEE ALSO", version) is installed and can be 'required' - otherwise the original presentation will be left untouched (e.q. 0.01). By default the result will contain information about 'my own' module (Module::Versions) as well but will ignore any information about 'unloadable' modules. A possibly loaded 'version.pm' module will not be shown.
Default is set to not oldver, not notme, not all and not version.
oldver
notme
all
version
Tries to use the historical versions of Perl itself prior to 5.6.0, as well as the Camel rules for the $VERSION (e.q. 0.01). This 'untouched' presention can be ensured only if the module 'version.pm' had not been loaded before by the script or another module. If the 'version.pm' was loaded, a 'version.pm' default will be used (e.q. 0.010). See EXAMPLES.
Suppress 'my own' package version (Module::Versions).
Show 'unknown modules' also.
Show 'version' module also. Influences oldver criterium.
list(<FD>, <MASK>)
list(<FD>, <PREFORM>)
list(<FD>, <CALLBACK>)
Prints a formatted module list to a file.
If no parameters are defiend list prints to STDOUT in an predefined format. An opened filedescriptor <FD> can define another result file.
<FD>
A mask <MASK> redefines the standard format. ALternatively a preformed fileformat (<PREFORM>) can be selected to print in standard formats.
<MASK>
<PREFORM>
For indivudual requirements a <CALLBACK> interface can be used.
<CALLBACK>
Filedescriptor, default *STDOUT.
String, default '%5d %s[ %s %s %s ]' in sprintf format. See perldoc -f sprintf.
Default result:
1 [ AutoLoader VERSION v5.600.0 ] 2 [ Carp VERSION v1.30.0 ] 3 *[ Config VERSION unknown ] 4 [ Cwd VERSION v3.10.0 ]
Mask needs 3 or 5 arguments.
5 Arguments
---- Examples ---- 1. cnt [numeric] 1 2 2. error [string] * 3. module [string] Carp File 4. variable [string] VERSION Module 5. value [string] 1.030 unknown
3 Arguments
---- Examples ---- 1. module [string] Carp File 2. variable [string] VERSION Module 3. value [string] 1.030 unknown
String, no default.
The following strings are valid:
Print a serialized ARRAY. Ref: ARRAY.
$versions = [['AutoLoader','VERSION','5.600'],...];
Print a serialized HASH. Ref: HASH.
$versions = {'AutoLoader' => {'VERSION' => '5.600'},...};
Print a simple text list.
Carp,VERSION,1.030 # Module, Name, Value strict,VERSION,1.030 File,Module,unknown # 'all': Module 'File' not found Data::Dumper,VERSION,2.121_020 Win32::PerlExe::Env,VERSION,0.050 # Standard variable $VERSION Win32::PerlExe::Env,_VERSION,0.050001507 # Project variable $_VERSION
Print a simple CSV list.
Module,Name,Value # Header Carp,VERSION,1.030 # Data strict,VERSION,1.030 # : File,Module,unknown # Data::Dumper,VERSION,2.121_020 # Win32::PerlExe::Env,VERSION,0.050 # Win32::PerlExe::Env,_VERSION,0.050001507 #
Print a XML file sructure.
Default format, if no 'XSD' or 'DTD' call was executed before.
'XSD'
'DTD'
<?xml version="1.0" encoding="UTF-8"?> <versions> <version module="Carp" name="VERSION">1.030</version> <version module="strict" name="VERSION">1.030</version> <version module="File" name="Module">unknown</version> <version module="Data::Dumper" name="VERSION">2.121_020</version> <version module="Win32::PerlExe::Env" name="VERSION">0.050</version> <version module="Win32::PerlExe::Env" name="_VERSION">0.050001507</version> </versions>
If 'XSD' was called before:
<?xml version="1.0" encoding="UTF-8"?> <versions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="xsd/versions.xsd"> <version module="Carp" name="VERSION">1.030</version> <version module="strict" name="VERSION">1.030</version> : </versions>
If 'DTD' was called before:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE versions SYSTEM "dtd/versions.dtd"> <versions> <version module="Carp" name="VERSION">1.030</version> <version module="strict" name="VERSION">1.030</version> : </versions>
Print a 'XML' file related XSD schema file.
'XML'
Print a 'XML' file related DTD file.
CODE reference, no default. Interface
sub cb { my ( $versions, $names ) = @_; # Do anything and build result... return $result; }
data(<CALLBACK>)
Result from callback (<CALLBACK>) routine, default callback is ARRAY;
Result is an ARRAY:
[ [ 'AutoLoader', # Module 'VERSION', # Variable '5.600' # Value ], : : : [ 'warnings::register', 'VERSION', '1.000' ] ];
Result is a HASH:
{ 'Carp' => { # Module 'VERSION' => '1.030' # Variable and Value }, 'Data::Dumper' => { 'VERSION' => '2.121_020' }, 'File' => { # Criterium was 'all'... 'Module' => 'unknown' # Module 'File' not found }, 'Win32::PerlExe::Env' => { 'VERSION' => '0.050', # Standard variable $VERSION '_VERSION' => '0.050001507 # Project variable $_VERSION }, }
Result is a simple text SCALAR. Ref: 'SCALAR'.
'SCALAR'
Result is a simple CSV text scalar. Ref: 'CSV'.
'CSV'
Result is a XML text scalar. Ref: 'XML'.
Result is a XSD text scalar. Ref: 'XSD'.
Result is a DTD text scalar. Ref: 'DTD'.
The XML generation allows an experimental feature to build XML data which can be validated. This will be done magically if one of the following sequences will be used:
1.) $v->list(*XSD,'XSD')->list(*XML,'XML'); 2.) $v->list(*DTD,'DTD')->list(*XML,'XML');
*** tbd ***
See examples of this distributions.
IO::Handle Data::Dumper
This is an Alpha Release.
The XSD/DTD methods are experimental.
Some parts of this documentation may be marked as *** tbd ***.
Send bug reports to my email address or use the CPAN RT system.
Module::Find, Module::InstalledVersion, Module::Info, Module::List, Module::Locate, Module::Which, Module::Which::List
Thomas Walloschke <thw@cpan.org>.
Copyright (c) 2006 Thomas Walloschke (thw@cpan.org). All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available. See perlartistic.
Last changed $Date: 2006-09-19 13:26:13 +0200 (Di, 19 Sep 2006) $.
To install Module::Versions, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Versions
CPAN shell
perl -MCPAN -e shell install Module::Versions
For more information on module installation, please visit the detailed CPAN module installation guide.