Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Module::Versions(3)   User Contributed Perl Documentation  Module::Versions(3)

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
       o new

       o 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
       o get

       o 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 shortcuts
	 "ARRAY", "HASH", "SCALAR", "CSV" and "XML".

	 <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", not "notme",	not "all" and
		   not "version".

		   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.

       o list

       o list(<FD>, <MASK>)

       o list(<FD>, <PREFORM>)

       o 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.

		   o	     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

		   o	     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;
		       }

       o data

       o data(<CALLBACK>)

	 Result	from callback ("<CALLBACK>") routine, default callback is
	 "ARRAY";

       o ARRAY

	 Result	is an ARRAY:

		 [
		   [
		     'AutoLoader',		     # Module
		     'VERSION',			     # Variable
		     '5.600'			     # Value
		   ],
			 :
			 :
			 :
		   [
		     'warnings::register',
		     'VERSION',
		     '1.000'
		   ]
		 ];

       o 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
					    },
		 }

       o SCALAR

	 Result	is a simple text SCALAR. Ref: 'SCALAR'.

       o CSV

	 Result	is a simple CSV	text scalar. Ref: 'CSV'.

       o XML

	 Result	is a XML text scalar. Ref: 'XML'.

       o XSD

	 Result	is a XSD text scalar. Ref: 'XSD'.

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

perl v5.24.1			  2006-09-20		   Module::Versions(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | EXAMPLES | DEPENDENCIES | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE | DATE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Module::Versions&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help