Provided by: libperl-version-perl_1.010-1_all bug

NAME

       Perl::Version - Parse and manipulate Perl version strings

VERSION

       This document describes Perl::Version version 1.010

SYNOPSIS

           use Perl::Version;

           # Init from string
           my $version = Perl::Version->new( '1.2.3' );

           # Stringification preserves original format
           print "$version\n";                 # prints '1.2.3'

           # Normalised
           print $version->normal, "\n";       # prints 'v1.2.3'

           # Numified
           print $version->numify, "\n";       # prints '1.002003'

           # Explicitly stringified
           print $version->stringify, "\n";    # prints '1.2.3'

           # Increment the subversion (the third component)
           $version->inc_subversion;

           # Stringification returns the updated version formatted
           # as the original was
           print "$version\n";                 # prints '1.2.4'

           # Normalised
           print $version->normal, "\n";       # prints 'v1.2.4'

           # Numified
           print $version->numify, "\n";       # prints '1.002004'

           # Refer to subversion component by position ( zero based )
           $version->increment( 2 );

           print "$version\n";                 # prints '1.2.5'

           # Increment the version (second component) which sets all
           # components to the right of it to zero.
           $version->inc_version;

           print "$version\n";                 # prints '1.3.0'

           # Increment the revision (main version number)
           $version->inc_revision;

           print "$version\n";                 # prints '2.0.0'

           # Increment the alpha number
           $version->inc_alpha;

           print "$version\n";                 # prints '2.0.0_001'

DESCRIPTION

       Perl::Version provides a simple interface for parsing, manipulating and formatting Perl
       version strings.

       Unlike version.pm (which concentrates on parsing and comparing version strings)
       Perl::Version is designed for cases where you'd like to parse a version, modify it and get
       back the modified version formatted like the original.

       For example:

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

       prints

           1.3.0

       whereas

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

       prints

           v1.03.00

       Both are representations of the same version and they'd compare equal but their formatting
       is different.

       Perl::Version tries hard to guess and recreate the format of the original version and in
       most cases it succeeds. In rare cases the formatting is ambiguous. Consider

           1.10.03

       Do you suppose that second component '10' is zero padded like the third component?
       Perl::Version will assume that it is:

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

       will print

           2.00.00

       If all of the components after the first are the same length (two characters in this case)
       and any of them begins with a zero Perl::Version will assume that they're all zero padded
       to the same length.

       The first component and any alpha suffix are handled separately. In each case if either of
       them starts with a zero they will be zero padded to the same length when stringifying the
       version.

   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.

INTERFACE

       "new"
           Create a new Perl::Version by parsing a version string. As discussed above a number of
           different version formats are supported. Along with the value of the version
           formatting information is captured so that the version can be modified and the updated
           value retrieved in the same format as the original.

               my @version = (
                   '1.3.0',    'v1.03.00',     '1.10.03', '2.00.00',
                   '1.2',      'v1.2.3.4.5.6', 'v1.2',    'Revision: 3.0',
                   '1.001001', '1.001_001',    '3.0.4_001',
               );

               for my $v ( @version ) {
                   my $version = Perl::Version->new( $v );
                   $version->inc_version;
                   print "$version\n";
               }

           prints

               1.4.0
               v1.04.00
               1.11.00
               2.01.00
               1.3
               v1.3.0.0.0.0
               v1.3
               Revision: 3.1
               1.002000
               1.002
               3.1.0

           In each case the incremented version is formatted in the same way as the original.

           If no arguments are passed an empty version intialised to 'v0' will be constructed.

           In order to support CVS version syntax

               my $version = Perl::Version->new( qw$Revision: 2.7 $ );

           "new" may be passed an array in which case it concatenates all of its arguments with
           spaces before parsing the result.

           If the string can't be parsed as a version "new" will croak with a suitable error. See
           DIAGNOSTICS for more information.

   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 comparisions
           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| |

DIAGNOSTICS

   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.

CONFIGURATION AND ENVIRONMENT

       Perl::Version requires no configuration files or environment variables.

DEPENDENCIES

       No non-core modules.

INCOMPATIBILITIES

       None reported.

BUGS AND LIMITATIONS

       No bugs have been reported.

       Please report any bugs or feature requests to "bug-perl-version@rt.cpan.org", or through
       the web interface at <http://rt.cpan.org>.

AUTHOR

       Andy Armstrong "<andy@hexten.net>"

       Hans Dieter Pearcey "<hdp@cpan.org>"

LICENCE AND COPYRIGHT

       Copyright (c) 2007, Andy Armstrong "<andy@hexten.net>". All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE,
       TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
       COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF
       ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
       THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE
       DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT
       HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY
       THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
       INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
       LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY
       OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
       SUCH DAMAGES.