/ 
version-0.25
River stage five • 1283 direct dependents • 22761 total dependents
/ version

NAME

version - Perl extension for Version Objects

SYNOPSIS

use version;
$version = new version "12.2.1"; # must be quoted!
print $version; 		# 12.2.1
print $version->numify; 	# 12.002001
if ( $version > 12.2 )	# true

$vstring = new version qw(v1.2); # must be quoted!
print $vstring;		# 1.2

$betaver = new version "1.2_3"; # must be quoted!
print $betaver;		# 1.2_3

$perlver = new version "5.005_03"; # must be quoted!
print $perlver;		# 5.5.30

DESCRIPTION

Overloaded version objects for all versions of Perl. This module implements all of the features of version objects which will be part of Perl 5.10.0 except automatic v-string handling. See "Quoting".

What IS a version

For the purposes of this module, a version "number" is a sequence of positive integral values separated by decimal points and optionally a single underscore. This corresponds to what Perl itself uses for a version, as well as extending the "version as number" that is discussed in the various editions of the Camel book.

However, in order to be compatible with earlier Perl version styles, any use of versions of the form 5.006001 will be translated as 5.6.1, In other words, a version with a single decimal place will be parsed as implicitly having three places between subversion.

Any value passed to the new() operator will be parsed only so far as it contains a numeric, decimal, or underscore character. So, for example:

$v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0
$v2 = new version "something"; # $v2 == "" and $v2->numify == 0

NOTE: it is strongly recommended that version objects only be created with numeric values based on the different types of versions in this documentation, see "Types of Versions Objects". That way, there is no confusion about what constitutes the version.

Object Methods

Overloading has been used with version objects to provide a natural interface for their use. All mathematical operations are forbidden, since they don't make any sense for versions. For the subsequent examples, the following two objects will be used:

$ver  = new version "1.2.3"; # see "Quoting" below
$beta = new version "1.2_3"; # see "Beta versions" below

  • Stringification - Any time a version object is used as a string, a stringified representation is returned in reduced form (no extraneous zeros):

    print $ver->stringify;      # prints 1.2.3
print $ver;                 # same thing

  • Numification - although all mathematical operations on version objects are forbidden by default, it is possible to retrieve a number which roughly corresponds to the version object through the use of the $obj->numify method. For formatting purposes, when displaying a number which corresponds a version object, all sub versions are assumed to have three decimal places. So for example:

    print $ver->numify;         # prints 1.002003

  • Comparison operators - Both cmp and <=> operators perform the same comparison between terms (upgrading to a version object automatically). Perl automatically generates all of the other comparison operators based on those two. For example, the following relations hold:

    As Number       As String          Truth Value
---------       ------------       -----------
$ver >  1.0     $ver gt "1.0"      true
$ver <  2.5     $ver lt            true
$ver != 1.3     $ver ne "1.3"      true
$ver == 1.2     $ver eq "1.2"      false
$ver == 1.2.3   $ver eq "1.2.3"    see discussion below
$ver == v1.2.3  $ver eq "v1.2.3"   ditto

    In versions of Perl prior to the 5.9.0 development releases, it is not permitted to use bare v-strings in either form, due to the nature of Perl's parsing operation. After that version (and in the stable 5.10.0 release), v-strings can be used with version objects without problem, see "Quoting" for more discussion of this topic. In the case of the last two lines of the table above, only the string comparison will be true; the numerical comparison will test false. However, you can do this:

    $ver == "1.2.3" or $ver == "v1.2.3"	# both true

    even though you are doing a "numeric" comparison with a "string" value. It is probably best to chose either the numeric notation or the string notation and stick with it, to reduce confusion. See also "Quoting".

Quoting

Because of the nature of the Perl parsing and tokenizing routines, you should always quote the parameter to the new() operator/method. The exact notation is vitally important to correctly determine the version that is requested. You don't have to quote the version parameter, but you should be aware of what Perl is likely to do in those cases.

If you use a mathematic formula that resolves to a floating point number, you are dependent on Perl's conversion routines to yield the version you expect. You are pretty safe by dividing by a power of 10, for example, but other operations are not likely to be what you intend. For example:

$VERSION = new version (qw$Revision: 1.4)[1]/10;
print $VERSION;          # yields 0.14
$V2 = new version 100/9; # Integer overflow in decimal number
print $V2;               # yields 11_1285418553

You can use a bare number, since this should never in practice yield a floating point notation error. However this is parsed differently than a quoted version. For example:

$VERSION = new version  10.2;  # parsed as 10.200
$VERSION = new version "10.2"; # parsed as 10.2

For decimal numbers used as versions, the parsing will automatically group the digits to the right of the decimal place in threes, and append trailing zeros to come out to an even three places. So, for example:

$VERSION = new version 1.2;      # parsed as 1.200
$VERSION = new version 1.02;     # parsed as 1.20
$VERSION = new version 1.002;    # parsed as 1.2
$VERSION = new version 1.002003; # parsed as 1.2.3
$VERSION = new version 1.00203;  # parsed as 1.2.30
$VERSION = new version 5.005_03; # parsed as 5.5.30

That last one is somewhat suprising, as it is not parsed like a "Beta version" because underscores in bare numbers are automatically ignored by Perl itself.

Perl 5.9.0 and beyond will be able to automatically quote v-strings (which may become the recommended notation), but that is not possible in earlier versions of Perl. In other words:

$version = new version "v2.5.4";  # legal in all versions of Perl
$newvers = new version v2.5.4;    # legal only in Perl > 5.9.0

Types of Versions Objects

There are two types of Version Objects:

  • Ordinary versions - These are the versions that normal modules will use. Can contain as many subversions as required. In particular, those using RCS/CVS can use one of the following:

    $VERSION = new version ((qw$Revision: 2.5 $)[1]); # all Perls
$VERSION = new version (qw$Revision: 2.5 $[1]);   # Perl >= 5.6.0

    and the current RCS Revision for that file will be inserted automatically. If the file has been moved to a branch, the Revision will have three or more elements; otherwise, it will have only two. This allows you to automatically increment your module version by using the Revision number from the primary file in a distribution, see "VERSION_FROM" in ExtUtils::MakeMaker.

  • Beta versions - For module authors using CPAN, the convention has been to note unstable releases with an underscore in the version string, see CPAN. Beta releases will test as being newer than the more recent stable release, and less than the next stable release. For example:

    $betaver = new version "12.3_1"; # must quote

    obeys the relationship

    12.3 < $betaver < 12.4

    As a matter of fact, if is also true that

    12.3.0 < $betaver < 12.3.1

    where the subversion is identical but the beta release is less than the non-beta release.

Replacement UNIVERSAL::VERSION

In addition to the version objects, this modules also replaces the core UNIVERSAL::VERSION function with one that uses version objects for its comparisons. So, for example, with all existing versions of Perl, something like the following pseudocode would fail:

package vertest;
$VERSION = "0.45";

package main;
use vertest "0.5";

even though those versions are meant to be read as the 45th minor version and the 5th minor version respectively. The UNIVERSAL::VERSION replacement function included with this module changes that behavior so that it will not fail.

EXPORT

None by default.

AUTHOR

John Peacock <jpeacock@rowman.com>

SEE ALSO

perl.

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 85:

'=item' outside of any '=over'

Around line 129:

You forgot a '=back' before '=head2'

Around line 181:

'=item' outside of any '=over'

Around line 214:

You forgot a '=back' before '=head2'