NAME
Test::GreaterVersion -- Test if you incremented VERSION
SYNOPSIS
has_greater_version('My::Module');
has_greater_version_than_cpan('My::Module');DESCRIPTION
There are two functions which are supposed to be used in your automated release suites to assure that you incremented your version before your install the module or upload it to CPAN.
has_greater_version checks if your module source has a greater VERSION number than the version installed in the system.
has_greater_version_than_cpan checks if your module source has a greater VERSION number than the version found on CPAN.
The version is checked by looking for the VERSION scalar in the module. The names of these two functions are always exported.
The two test functions expect your module files layed out in the standard way, i.e. tests are called in the top directory and module if found in the lib directory:
Module Path
doc
examples
lib
tThe version of My::Module is therefore expected in the file lib/My/Module.pm. There's currently no way to alter that location. (The file name is OS independent via the magic of File::Spec.)
The version information is actually parsed by ExtUtils::MakeMaker.
The version numbers are compared calling CPAN::Version::vgt(). See CPAN::Version or version for version number syntax. (Short: Both 1.00203 and v1.2.30 work.)
Please note that these test functions should not be put in normal test script below t/. They will usually break the tests. These functions are to be put in some install script to check the versions automatically.
FUNCTIONS
has_greater_version ($module)
Returns 1 if your module in 'lib/' has a version and if it is greater than the version of the installed module, 0 otherwise.
1 is also returned if the module is not installed, i.e. your module is new.
1 is also returned if the module is installed but has no version defined, i.e. your module in 'lib/' is a fix of this bug.
has_greater_version_than_cpan ($module)
Returns 1 if your module in 'lib/' has a version and if it is greater than the module's version on CPAN, 0 otherwise.
1 is also returned if the module is there is no CPAN information available for your module, i.e. your module is new and will be the first release to CPAN or has no version defined.
Due to the interface of the CPAN module there's currently no way to tell if the module is not on CPAN or if there has been an error in getting the module information from CPAN. As a result this function should only be called if you are sure that there's a version of the module on CPAN.
Depending on the configuration of your CPAN shell the first call of this function may seem to block the test. When you notice this behaviour it's likely that the CPAN shell is trying to get the latest module index which may take some time.
Please note also that depending on your CPAN mirror the module information might be up to date or not.
INTERNAL FUNCTIONS
These are not to be called by anyone.
_get_installed_version ($module)
Gets the version of the installed module. The version information is found with the help of the CPAN module.
Returns undef if the file doesn't exist. Returns 'undef' (yes, the string) if it has no version. Returns the version otherwise.
We don't use CPAN::Shell::inst_version() since it doesn't remove blib before searching for the version and we want to have a diag() output in the test. And because the manpage doesn't list the function in the stable interface.
_get_version_from_lib ($module)
Gets the version of the module found in 'lib/'. Transforms the module name into a filename which points to a file found under 'lib/'.
MM-parse_version()> tries to find the version.
Returns undef if the file doesn't exist. Returns 'undef' (yes, the string) if it has no version. Returns the version otherwise.
_get_version_from_cpan ($module)
Gets the module's version as found on CPAN. The version information is found with the help of the CPAN module.
Returns undef if the module is not on CPAN or the CPAN module failed somehow. Returns the version otherwise.
NOTES
This module was inspired by brian d foy's talk 'Managing Complexity with Module::Release' at the Nordic Perl Workshop in 2006.
TODO
It might be nice that has_greater_version() and has_greater_version_than_cpan() wouldn't fail on equal versions if the modules source code is equal, too. Thanks to Slaven Rezic for that suggestion. That way the tests could be used in a normal test suite.
AUTHOR
Gregor Goldbach <ggoldbach@cpan.org>
SIMILAR MODULES
Test::Version tests if there is a VERSION defined.
Test::HasVersion does it, too, but has the ability to check all Perl modules in lib.
Neither of these compare versions.
COPYRIGHT
Copyright (c) 2007 by Gregor Goldbach. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.