Version Formats

Perl::Version supports a few different version string formats.

1, 1.2

Versions that look like a number. If you pass a numeric value its string equivalent will be parsed:

    my $version = Perl::Version->new( 1.2 );
    print "$version\n";
    

prints

    1.2
    

In fact there is no special treatment for versions that resemble decimal numbers. This is worthy of comment only because it differs from version.pm which treats actual numbers used as versions as a special case and performs various transformations on the stored version.

1.2.3, 1.2.3.4

Simple versions with three or more components.

v1.2.3

Versions with a leading 'v'.

5.008006

Fielded numeric versions. You'll likely have seen this in relation to versions of Perl itself. If a version string has a single decimal point and the part after the point is three more more digits long, components are extracted from each group of three digits in the fractional part.

For example

    my $version = Perl::Version->new( 1.002003004005006 );
    print $version->normal;
    

prints

    v1.2.3.4.5.6
    

vstring

Perls later than 5.8.1 support vstring format. A vstring looks like a number with more than one decimal point and (optionally) a leading 'v'. The 'v' is mandatory for vstrings containing fewer than two decimal points.

Perl::Version will successfully parse vstrings

    my $version = Perl::Version->new( v1.2 );
    print "$version\n";
    

prints

    v1.2
    

Note that stringifying a Perl::Version constructed from a vstring will result in a regular string. Because it has no way of knowing whether the vstring constant had a 'v' prefix it always generates one when stringifying back to a version string.

CVS version

A common idiom for users of CVS is to use keyword replacement to generate a version automatically like this:

    $VERSION = version->new( qw$Revision: 2.7 $ );
    

Perl::Version does the right thing with such versions so that

    my $version = Perl::Version->new( qw$Revision: 2.7 $ );
    $version->inc_revision;
    print "$version\n";
    

prints

    Revision: 3.0
    

Real Numbers

Real numbers are stringified before parsing. This has two implications: trailing zeros after the decimal point will be lost and any underscore characters in the number are discarded.

Perl allows underscores anywhere in numeric constants as an aid to formatting. These are discarded when Perl converts the number into its internal format. This means that

    # Numeric version
    print Perl::Version->new( 1.001_001 )->stringify;

prints

    1.001001

but

    # String version
    print Perl::Version->new( '1.001_001' )->stringify;

prints

    1.001_001

as expected.

In general you should probably avoid versions expressed either as decimal numbers or vstrings. The safest option is to pass a regular string to Perl::Version->new().

Alpha Versions

By convention if a version string has suffix that consists of an underscore followed by one or more digits it represents an alpha or developer release. CPAN treats modules with such version strings specially to reflect their alpha status.

This alpha notation is one reason why using decimal numbers as versions is a bad idea. Underscore is a valid character in numeric constants which is discarded by Perl when a program's source is parsed so any intended alpha suffix will become part of the version number.

To be considered alpha a version must have a non-zero alpha component like this

    3.0.4_001

Generally the alpha component will be formatted with leading zeros but this is not a requirement.

Component Naming

A version number consists of a series of components. By Perl convention the first three components are named 'revision', 'version' and 'subversion':

    $ perl -V
    Summary of my perl5 (revision 5 version 8 subversion 6) configuration:
    
    (etc)

Perl::Version follows that convention. Any component may be accessed by passing a number from 0 to N-1 to the component or increment but for convenience the first three components are aliased as revision, version and subversion.

    $version->increment( 0 );

is the same as

    $version->inc_revision;

and

    my $subv = $version->subversion;

is the same as

    my $subv = $version->component( 2 );

The alpha component is named 'alpha'.

Comparison with version.pm

If you're familiar with version.pm you'll notice that there's a certain amount of overlap between what it does and this module. I originally created this module as a mutable subclass of version.pm but the requirement to be able to reformat a modified version to match the formatting of the original didn't sit well with version.pm's internals.

As a result this module is not dependent or based on version.pm.

Accessors

"component"

Set or get one of the components of a version.

    # Set the subversion
    $version->component( 2, 17 );
    
    # Get the revision
    my $rev = $version->component( 0 );
    

Instead of a component number you may pass a name: 'revision', 'version', 'subversion' or 'alpha':

    my $rev = $version->component( 'revision' );
    

"components"

Get or set all of the components of a version.

    # Set the number of components
    $version->components( 4 );
    
    # Get the number of components
    my $parts = $version->components;
    
    # Get the individual components as an array
    my @parts = $version->components;
    
    # Set the components from an array
    $version->components( [ 5, 9, 2 ] );
    

Hmm. That's a lot of interface for one subroutine. Sorry about that.

"revision"

Alias for component( 0 ). Gets or sets the revision component.

"version"

Alias for component( 1 ). Gets or sets the version component.

"subversion"

Alias for component( 2 ). Gets or sets the subversion component.

"alpha"

Get or set the alpha component of a version. Returns 0 for versions with no alpha.

    # Set alpha
    $version->alpha( 12 );
    
    # Get alpha
    my $alp = $version->alpha;
    

"is_alpha"

Return true if a version has a non-zero alpha component.

"set"

Set the version to match another version preserving the formatting of this version.

    $version->set( $other_version );
    

You may also set the version from a literal string:

    $version->set( '1.2.3' );
    

The version will be updated to the value of the version string but will retain its current formatting.

Incrementing

"increment"

Increment a component of a version.

    my $version = Perl::Version->new( '3.1.4' );
    $version->increment( 1 );
    print "$version\n";
    

prints

    3.2.0
    

Components to the right of the incremented component will be set to zero as will any alpha component.

As an alternative to passing a component number one of the predefined component names 'revision', 'version', 'subversion' or 'alpha' may be passed.

"inc_alpha"

Increment a version's alpha component.

"inc_revision"

Increment a version's revision component.

"inc_subversion"

Increment a version's subversion component.

"inc_version"

Increment a version's version component.

Formatting

"normal"

Return a normalised representation of a version.

    my $version = Perl::Version->new( '5.008007_01' );
    print $version->normal, "\n";
    

prints

    v5.8.7_001
    

"numify"

Return a numeric representation of a version. The numeric form is most frequently used for versions of Perl itself.

    my $version = Perl::Version->new( '5.8.7_1' );
    print $version->normal, "\n";
    

prints

    5.008007_001
    

"stringify"

Return the version formatted as closely as possible to the version from which it was initialised.

    my $version = Perl::Version->new( '5.008007_01' );
    $version->inc_alpha;
    print $version->stringify, "\n";
    

prints

    5.008007_02
    

and

    my $version = Perl::Version->new( '5.8.7_1' );
    $version->inc_alpha;
    print $version->stringify, "\n";
    

prints

    5.8.7_2
    

Comparison

"vcmp"

Perform 'spaceship' comparison between two version and return -1, 0 or 1 depending on their ordering. Comparisons are semantically correct so that

    my $v1 = Perl::Version->new( '1.002001' );
    my $v2 = Perl::Version->new( '1.1.3' );
    print ($v1->vcmp( $v2 ) > 0 ? 'yes' : 'no'), "\n";
    

prints

    yes
    

Overloaded Operators

"<=>" and "cmp"

The "<=>" and "cmp" operators are overloaded (by the vcmp method) so that comparisons between versions work as expected. This means that the other numeric and string comparison operators also work as expected.

    my $v1 = Perl::Version->new( '1.002001' );
    my $v2 = Perl::Version->new( '1.1.3' );
    print "OK!\n" if $v1 > $v2;
    

prints

    OK!
    

"" (stringification)

Perl::Version objects are converted to strings by calling the stringify method. This usually results in formatting close to that of the original version string.

Constants

"REGEX"

An unanchored regular expression that matches any of the version formats supported by Perl::Version. Three captures get the prefix part, the main body of the version and any alpha suffix respectively.

    my $version = 'v1.2.3.4_5';
    my ($prefix, $main, $suffix) = ($version =~ Perl::Version::REGEX);
    print "$prefix\n$main\n$suffix\n";
    

prints

    v
    1.2.3.4
    _5
    

"MATCH"

An anchored regular expression that matches a correctly formatted version string. Five captures get any leading whitespace, the prefix part, the main body of the version, any alpha suffix and any trailing spaces respectively.

    my $version = '  v1.2.3.4_5  ';
    my ($before, $prefix, $main, $suffix, $after) 
                 = ($version =~ Perl::Version::MATCH);
    print "|$before|$prefix|$main|$suffix|$after|\n";
    

prints

    | |v|1.2.3.4|_5| |
    

Error messages

"Illegal version string: %s"

The version string supplied to "new" can't be parsed as a valid version. Valid versions match this regex:

    qr/ ( (?i: Revision: \s+ ) | v | )
          ( \d+ (?: [.] \d+)* )
          ( (?: _ \d+ )? ) /x;
    

"new must be called as a class or object method"

"new" can't be called as a normal subroutine. Use

    $version_object->new( '1.2.3' );
    

or

    Perl::Version->new( '1.2.3' );
    

instead of

    Perl::Version::new( '1.2.3' );
    

"Unknown component name: %s"

You've attempted to access a component by name using a name that isn't recognised. Valid component names are 'revision', 'version', 'subversion' and 'alpha'. Case is not significant.

"Can't compare with %s"

You've tried to compare a Perl::Version with something other than a version string, a number or another Perl::Version.

"Can't set the number of components to 0"

Versions must have at least one component.

"You must specify a component number"

You've called component or increment without specifying the number (or name) of the component to access.

"Component %s is out of range 0..%s"

You've attempted to increment a component of a version but you've specified a component that doesn't exist within the version:

    # Fails
    my $version = Perl::Version->new( '1.4' );
    $version->increment( 2 );
    

Slightly confusingly you'll see this message even if you specified the component number implicitly by using one of the named convenience accessors.