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
    

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

IO::Handle Data::Dumper

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

version

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) $.