NAME
Module::Versions - Handle versions of loaded modules with flexible result interface
VERSION
This documentation refers to Module::Versions Version 0.01 $Revision: 522 $
Precautions: Alpha Release.
SYNOPSIS
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
DESCRIPTION
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.
METHODS
- Calling
-
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;
- Shortcuts
-
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
Overview
- Constuctor
-
new
- Standard Methods
-
get
,list
,data
- Preformed Methods
-
ARRAY
,HASH
,SCALAR
,CSV
,XML
,XSD
,DTD
Constructor
new
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.
- <MODULES>
-
String or ARRAY of strings; default is content of %INC.
- <SELECTION>
-
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.
Methods
get
get(<CRITERIA>)
Retrieve
<MODULES>
as defined before and use the<SELECTION>
as defined in object by the constructor.The result can be accessed by
list
,data
or the shortcutsARRAY
,HASH
,SCALAR
,CSV
andXML
.- <CRITERIA>
-
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
, notnotme
, notall
and notversion
.- oldver
-
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.
- notme
-
Suppress 'my own' package version (Module::Versions).
- all
-
Show 'unknown modules' also.
- version
-
Show 'version' module also. Influences
oldver
criterium.
list
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.A mask
<MASK>
redefines the standard format. ALternatively a preformed fileformat (<PREFORM>
) can be selected to print in standard formats.For indivudual requirements a
<CALLBACK>
interface can be used.- <FD>
-
Filedescriptor, default *STDOUT.
- <MASK>
-
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
- <PREFORM>
-
String, no default.
The following strings are valid:
- 'ARRAY'
-
Print a serialized ARRAY. Ref:
ARRAY
.$versions
= [[
'AutoLoader'
,
'VERSION'
,
'5.600'
],...];
- 'HASH'
-
Print a serialized HASH. Ref:
HASH
.$versions
= {
'AutoLoader'
=> {
'VERSION'
=>
'5.600'
},...};
- 'SCALAR'
-
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
- 'CSV'
-
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
#
- 'XML'
-
Print a XML file sructure.
Default format, if no
'XSD'
or'DTD'
call was executed before.<?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>
- 'XSD'
-
Print a
'XML'
file related XSD schema file. - 'DTD'
-
Print a
'XML'
file related DTD file.
- <CALLBACK>
-
CODE reference, no default. Interface
sub
cb {
my
(
$versions
,
$names
) =
@_
;
# Do anything and build result...
return
$result
;
}
data
data(<CALLBACK>)
Result from callback (
<CALLBACK>
) routine, default callback isARRAY
;ARRAY
Result is an ARRAY:
[
[
'AutoLoader'
,
# Module
'VERSION'
,
# Variable
'5.600'
# Value
],
:
:
:
[
'warnings::register'
,
'VERSION'
,
'1.000'
]
];
HASH
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
},
}
SCALAR
Result is a simple text SCALAR. Ref:
'SCALAR'
.CSV
Result is a simple CSV text scalar. Ref:
'CSV'
.XML
Result is a XML text scalar. Ref:
'XML'
.XSD
Result is a XSD text scalar. Ref:
'XSD'
.DTD
Result is a DTD text scalar. Ref:
'DTD'
.
DIAGNOSTICS
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'
);
CONFIGURATION AND ENVIRONMENT
*** tbd ***
EXAMPLES
See examples of this distributions.
DEPENDENCIES
BUGS
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.
SEE ALSO
Module::Find, Module::InstalledVersion, Module::Info, Module::List, Module::Locate, Module::Which, Module::Which::List
AUTHOR
Thomas Walloschke <thw@cpan.org>.
COPYRIGHT AND LICENSE
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.
DATE
Last changed $Date: 2006-09-19 13:26:13 +0200 (Di, 19 Sep 2006) $.