.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Perl::Version 3"
.TH Perl::Version 3 "2010-09-19" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Perl::Version \- Parse and manipulate Perl version strings
.SH "VERSION"
.IX Header "VERSION"
This document describes Perl::Version version 1.011
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Perl::Version;
\&
\& # Init from string
\& my $version = Perl::Version\->new( \*(Aq1.2.3\*(Aq );
\&
\& # Stringification preserves original format
\& print "$version\en"; # prints \*(Aq1.2.3\*(Aq
\&
\& # Normalised
\& print $version\->normal, "\en"; # prints \*(Aqv1.2.3\*(Aq
\&
\& # Numified
\& print $version\->numify, "\en"; # prints \*(Aq1.002003\*(Aq
\&
\& # Explicitly stringified
\& print $version\->stringify, "\en"; # prints \*(Aq1.2.3\*(Aq
\&
\& # Increment the subversion (the third component)
\& $version\->inc_subversion;
\&
\& # Stringification returns the updated version formatted
\& # as the original was
\& print "$version\en"; # prints \*(Aq1.2.4\*(Aq
\&
\& # Normalised
\& print $version\->normal, "\en"; # prints \*(Aqv1.2.4\*(Aq
\&
\& # Numified
\& print $version\->numify, "\en"; # prints \*(Aq1.002004\*(Aq
\&
\& # Refer to subversion component by position ( zero based )
\& $version\->increment( 2 );
\&
\& print "$version\en"; # prints \*(Aq1.2.5\*(Aq
\&
\& # Increment the version (second component) which sets all
\& # components to the right of it to zero.
\& $version\->inc_version;
\&
\& print "$version\en"; # prints \*(Aq1.3.0\*(Aq
\&
\& # Increment the revision (main version number)
\& $version\->inc_revision;
\&
\& print "$version\en"; # prints \*(Aq2.0.0\*(Aq
\&
\& # Increment the alpha number
\& $version\->inc_alpha;
\&
\& print "$version\en"; # prints \*(Aq2.0.0_001\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Perl::Version provides a simple interface for parsing, manipulating and
formatting Perl version strings.
.PP
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.
.PP
For example:
.PP
.Vb 3
\& my $version = Perl::Version\->new( \*(Aq1.2.3\*(Aq );
\& $version\->inc_version;
\& print "$version\en";
.Ve
.PP
prints
.PP
.Vb 1
\& 1.3.0
.Ve
.PP
whereas
.PP
.Vb 3
\& my $version = Perl::Version\->new( \*(Aqv1.02.03\*(Aq );
\& $version\->inc_version;
\& print "$version\en";
.Ve
.PP
prints
.PP
.Vb 1
\& v1.03.00
.Ve
.PP
Both are representations of the same version and they'd compare equal
but their formatting is different.
.PP
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
.PP
.Vb 1
\& 1.10.03
.Ve
.PP
Do you suppose that second component '10' is zero padded like the third
component? Perl::Version will assume that it is:
.PP
.Vb 3
\& my $version = Perl::Version\->new( \*(Aq1.10.03\*(Aq );
\& $version\->inc_revision;
\& print "$version\en";
.Ve
.PP
will print
.PP
.Vb 1
\& 2.00.00
.Ve
.PP
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.
.PP
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.
.SS "Version Formats"
.IX Subsection "Version Formats"
Perl::Version supports a few different version string formats.
.IP " 1, 1.2" 4
.IX Item " 1, 1.2"
Versions that look like a number. If you pass a numeric value its string
equivalent will be parsed:
.Sp
.Vb 2
\& my $version = Perl::Version\->new( 1.2 );
\& print "$version\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& 1.2
.Ve
.Sp
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.
.IP " 1.2.3, 1.2.3.4" 4
.IX Item " 1.2.3, 1.2.3.4"
Simple versions with three or more components.
.IP " v1.2.3" 4
.IX Item " v1.2.3"
Versions with a leading 'v'.
.IP " 5.008006" 4
.IX Item " 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.
.Sp
For example
.Sp
.Vb 2
\& my $version = Perl::Version\->new( 1.002003004005006 );
\& print $version\->normal;
.Ve
.Sp
prints
.Sp
.Vb 1
\& v1.2.3.4.5.6
.Ve
.IP "vstring" 4
.IX Item "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.
.Sp
Perl::Version will successfully parse vstrings
.Sp
.Vb 2
\& my $version = Perl::Version\->new( v1.2 );
\& print "$version\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& v1.2
.Ve
.Sp
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.
.IP "\s-1CVS\s0 version" 4
.IX Item "CVS version"
A common idiom for users of \s-1CVS\s0 is to use keyword replacement to
generate a version automatically like this:
.Sp
.Vb 1
\& $VERSION = version\->new( qw$Revision: 2.7 $ );
.Ve
.Sp
Perl::Version does the right thing with such versions so that
.Sp
.Vb 3
\& my $version = Perl::Version\->new( qw$Revision: 2.7 $ );
\& $version\->inc_revision;
\& print "$version\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& Revision: 3.0
.Ve
.PP
\fIReal Numbers\fR
.IX Subsection "Real Numbers"
.PP
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.
.PP
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
.PP
.Vb 2
\& # Numeric version
\& print Perl::Version\->new( 1.001_001 )\->stringify;
.Ve
.PP
prints
.PP
.Vb 1
\& 1.001001
.Ve
.PP
but
.PP
.Vb 2
\& # String version
\& print Perl::Version\->new( \*(Aq1.001_001\*(Aq )\->stringify;
.Ve
.PP
prints
.PP
.Vb 1
\& 1.001_001
.Ve
.PP
as expected.
.PP
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\->\fInew()\fR.
.PP
\fIAlpha Versions\fR
.IX Subsection "Alpha Versions"
.PP
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. \s-1CPAN\s0 treats modules with such version strings
specially to reflect their alpha status.
.PP
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.
.PP
To be considered alpha a version must have a non-zero alpha
component like this
.PP
.Vb 1
\& 3.0.4_001
.Ve
.PP
Generally the alpha component will be formatted with leading zeros but
this is not a requirement.
.SS "Component Naming"
.IX Subsection "Component Naming"
A version number consists of a series of components. By Perl convention
the first three components are named 'revision', 'version' and
\&'subversion':
.PP
.Vb 2
\& $ perl \-V
\& Summary of my perl5 (revision 5 version 8 subversion 6) configuration:
\&
\& (etc)
.Ve
.PP
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.
.PP
.Vb 1
\& $version\->increment( 0 );
.Ve
.PP
is the same as
.PP
.Vb 1
\& $version\->inc_revision;
.Ve
.PP
and
.PP
.Vb 1
\& my $subv = $version\->subversion;
.Ve
.PP
is the same as
.PP
.Vb 1
\& my $subv = $version\->component( 2 );
.Ve
.PP
The alpha component is named 'alpha'.
.SS "Comparison with version.pm"
.IX Subsection "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.
.PP
As a result this module is not dependent or based on version.pm.
.SH "INTERFACE"
.IX Header "INTERFACE"
.ie n .IP """new""" 4
.el .IP "\f(CWnew\fR" 4
.IX Item "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.
.Sp
.Vb 5
\& my @version = (
\& \*(Aq1.3.0\*(Aq, \*(Aqv1.03.00\*(Aq, \*(Aq1.10.03\*(Aq, \*(Aq2.00.00\*(Aq,
\& \*(Aq1.2\*(Aq, \*(Aqv1.2.3.4.5.6\*(Aq, \*(Aqv1.2\*(Aq, \*(AqRevision: 3.0\*(Aq,
\& \*(Aq1.001001\*(Aq, \*(Aq1.001_001\*(Aq, \*(Aq3.0.4_001\*(Aq,
\& );
\&
\& for my $v ( @version ) {
\& my $version = Perl::Version\->new( $v );
\& $version\->inc_version;
\& print "$version\en";
\& }
.Ve
.Sp
prints
.Sp
.Vb 11
\& 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
.Ve
.Sp
In each case the incremented version is formatted in the same way as the original.
.Sp
If no arguments are passed an empty version intialised to 'v0' will be
constructed.
.Sp
In order to support \s-1CVS\s0 version syntax
.Sp
.Vb 1
\& my $version = Perl::Version\->new( qw$Revision: 2.7 $ );
.Ve
.Sp
\&\f(CW\*(C`new\*(C'\fR may be passed an array in which case it concatenates all of its
arguments with spaces before parsing the result.
.Sp
If the string can't be parsed as a version \f(CW\*(C`new\*(C'\fR will croak with a
suitable error. See \s-1DIAGNOSTICS\s0 for more information.
.SS "Accessors"
.IX Subsection "Accessors"
.ie n .IP """component""" 4
.el .IP "\f(CWcomponent\fR" 4
.IX Item "component"
Set or get one of the components of a version.
.Sp
.Vb 2
\& # Set the subversion
\& $version\->component( 2, 17 );
\&
\& # Get the revision
\& my $rev = $version\->component( 0 );
.Ve
.Sp
Instead of a component number you may pass a name: 'revision',
\&'version', 'subversion' or 'alpha':
.Sp
.Vb 1
\& my $rev = $version\->component( \*(Aqrevision\*(Aq );
.Ve
.ie n .IP """components""" 4
.el .IP "\f(CWcomponents\fR" 4
.IX Item "components"
Get or set all of the components of a version.
.Sp
.Vb 2
\& # 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 ] );
.Ve
.Sp
Hmm. That's a lot of interface for one subroutine. Sorry about that.
.ie n .IP """revision""" 4
.el .IP "\f(CWrevision\fR" 4
.IX Item "revision"
Alias for \f(CWcomponent( 0 )\fR. Gets or sets the revision component.
.ie n .IP """version""" 4
.el .IP "\f(CWversion\fR" 4
.IX Item "version"
Alias for \f(CWcomponent( 1 )\fR. Gets or sets the version component.
.ie n .IP """subversion""" 4
.el .IP "\f(CWsubversion\fR" 4
.IX Item "subversion"
Alias for \f(CWcomponent( 2 )\fR. Gets or sets the subversion component.
.ie n .IP """alpha""" 4
.el .IP "\f(CWalpha\fR" 4
.IX Item "alpha"
Get or set the alpha component of a version. Returns 0 for versions with no alpha.
.Sp
.Vb 2
\& # Set alpha
\& $version\->alpha( 12 );
\&
\& # Get alpha
\& my $alp = $version\->alpha;
.Ve
.ie n .IP """is_alpha""" 4
.el .IP "\f(CWis_alpha\fR" 4
.IX Item "is_alpha"
Return true if a version has a non-zero alpha component.
.ie n .IP """set""" 4
.el .IP "\f(CWset\fR" 4
.IX Item "set"
Set the version to match another version preserving the formatting of this version.
.Sp
.Vb 1
\& $version\->set( $other_version );
.Ve
.Sp
You may also set the version from a literal string:
.Sp
.Vb 1
\& $version\->set( \*(Aq1.2.3\*(Aq );
.Ve
.Sp
The version will be updated to the value of the version string but will
retain its current formatting.
.SS "Incrementing"
.IX Subsection "Incrementing"
.ie n .IP """increment""" 4
.el .IP "\f(CWincrement\fR" 4
.IX Item "increment"
Increment a component of a version.
.Sp
.Vb 3
\& my $version = Perl::Version\->new( \*(Aq3.1.4\*(Aq );
\& $version\->increment( 1 );
\& print "$version\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& 3.2.0
.Ve
.Sp
Components to the right of the incremented component will be set to zero
as will any alpha component.
.Sp
As an alternative to passing a component number one of the predefined
component names 'revision', 'version', 'subversion' or 'alpha' may be
passed.
.ie n .IP """inc_alpha""" 4
.el .IP "\f(CWinc_alpha\fR" 4
.IX Item "inc_alpha"
Increment a version's alpha component.
.ie n .IP """inc_revision""" 4
.el .IP "\f(CWinc_revision\fR" 4
.IX Item "inc_revision"
Increment a version's revision component.
.ie n .IP """inc_subversion""" 4
.el .IP "\f(CWinc_subversion\fR" 4
.IX Item "inc_subversion"
Increment a version's subversion component.
.ie n .IP """inc_version""" 4
.el .IP "\f(CWinc_version\fR" 4
.IX Item "inc_version"
Increment a version's version component.
.SS "Formatting"
.IX Subsection "Formatting"
.ie n .IP """normal""" 4
.el .IP "\f(CWnormal\fR" 4
.IX Item "normal"
Return a normalised representation of a version.
.Sp
.Vb 2
\& my $version = Perl::Version\->new( \*(Aq5.008007_01\*(Aq );
\& print $version\->normal, "\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& v5.8.7_001
.Ve
.ie n .IP """numify""" 4
.el .IP "\f(CWnumify\fR" 4
.IX Item "numify"
Return a numeric representation of a version. The numeric form is most
frequently used for versions of Perl itself.
.Sp
.Vb 2
\& my $version = Perl::Version\->new( \*(Aq5.8.7_1\*(Aq );
\& print $version\->normal, "\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& 5.008007_001
.Ve
.ie n .IP """stringify""" 4
.el .IP "\f(CWstringify\fR" 4
.IX Item "stringify"
Return the version formatted as closely as possible to the version from
which it was initialised.
.Sp
.Vb 3
\& my $version = Perl::Version\->new( \*(Aq5.008007_01\*(Aq );
\& $version\->inc_alpha;
\& print $version\->stringify, "\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& 5.008007_02
.Ve
.Sp
and
.Sp
.Vb 3
\& my $version = Perl::Version\->new( \*(Aq5.8.7_1\*(Aq );
\& $version\->inc_alpha;
\& print $version\->stringify, "\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& 5.8.7_2
.Ve
.SS "Comparison"
.IX Subsection "Comparison"
.ie n .IP """vcmp""" 4
.el .IP "\f(CWvcmp\fR" 4
.IX Item "vcmp"
Perform 'spaceship' comparison between two version and return \-1, 0 or 1
depending on their ordering. Comparisons are semantically correct so that
.Sp
.Vb 2
\& my $v1 = Perl::Version\->new( \*(Aq1.002001\*(Aq );
\& my $v2 = Perl::Version\->new( \*(Aq1.1.3\*(Aq );
\&
\& print ($v1\->vcmp( $v2 ) > 0 ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq), "\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& yes
.Ve
.SS "Overloaded Operators"
.IX Subsection "Overloaded Operators"
.ie n .IP """<=>"" and ""cmp""" 4
.el .IP "\f(CW<=>\fR and \f(CWcmp\fR" 4
.IX Item "<=> and cmp"
The \f(CW\*(C`<=>\*(C'\fR and \f(CW\*(C`cmp\*(C'\fR 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.
.Sp
.Vb 2
\& my $v1 = Perl::Version\->new( \*(Aq1.002001\*(Aq );
\& my $v2 = Perl::Version\->new( \*(Aq1.1.3\*(Aq );
\&
\& print "OK!\en" if $v1 > $v2;
.Ve
.Sp
prints
.Sp
.Vb 1
\& OK!
.Ve
.ie n .IP """"" (stringification)" 4
.el .IP "\f(CW``''\fR (stringification)" 4
.IX Item """"" (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.
.SS "Constants"
.IX Subsection "Constants"
.ie n .IP """REGEX""" 4
.el .IP "\f(CWREGEX\fR" 4
.IX Item "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.
.Sp
.Vb 3
\& my $version = \*(Aqv1.2.3.4_5\*(Aq;
\& my ($prefix, $main, $suffix) = ($version =~ Perl::Version::REGEX);
\& print "$prefix\en$main\en$suffix\en";
.Ve
.Sp
prints
.Sp
.Vb 3
\& v
\& 1.2.3.4
\& _5
.Ve
.ie n .IP """MATCH""" 4
.el .IP "\f(CWMATCH\fR" 4
.IX Item "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.
.Sp
.Vb 4
\& my $version = \*(Aq v1.2.3.4_5 \*(Aq;
\& my ($before, $prefix, $main, $suffix, $after)
\& = ($version =~ Perl::Version::MATCH);
\& print "|$before|$prefix|$main|$suffix|$after|\en";
.Ve
.Sp
prints
.Sp
.Vb 1
\& | |v|1.2.3.4|_5| |
.Ve
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.SS "Error messages"
.IX Subsection "Error messages"
.ie n .IP """Illegal version string: %s""" 4
.el .IP "\f(CWIllegal version string: %s\fR" 4
.IX Item "Illegal version string: %s"
The version string supplied to \f(CW\*(C`new\*(C'\fR can't be parsed as a valid
version. Valid versions match this regex:
.Sp
.Vb 3
\& qr/ ( (?i: Revision: \es+ ) | v | )
\& ( \ed+ (?: [.] \ed+)* )
\& ( (?: _ \ed+ )? ) /x;
.Ve
.ie n .IP """new must be called as a class or object method""" 4
.el .IP "\f(CWnew must be called as a class or object method\fR" 4
.IX Item "new must be called as a class or object method"
\&\f(CW\*(C`new\*(C'\fR can't be called as a normal subroutine. Use
.Sp
.Vb 1
\& $version_object\->new( \*(Aq1.2.3\*(Aq );
.Ve
.Sp
or
.Sp
.Vb 1
\& Perl::Version\->new( \*(Aq1.2.3\*(Aq );
.Ve
.Sp
instead of
.Sp
.Vb 1
\& Perl::Version::new( \*(Aq1.2.3\*(Aq );
.Ve
.ie n .IP """Unknown component name: %s""" 4
.el .IP "\f(CWUnknown component name: %s\fR" 4
.IX Item "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.
.ie n .IP """Can\*(Aqt compare with %s""" 4
.el .IP "\f(CWCan\*(Aqt compare with %s\fR" 4
.IX Item "Cant compare with %s"
You've tried to compare a Perl::Version with something other than a
version string, a number or another Perl::Version.
.ie n .IP """Can\*(Aqt set the number of components to 0""" 4
.el .IP "\f(CWCan\*(Aqt set the number of components to 0\fR" 4
.IX Item "Cant set the number of components to 0"
Versions must have at least one component.
.ie n .IP """You must specify a component number""" 4
.el .IP "\f(CWYou must specify a component number\fR" 4
.IX Item "You must specify a component number"
You've called component or increment without specifying the number (or
name) of the component to access.
.ie n .IP """Component %s is out of range 0..%s""" 4
.el .IP "\f(CWComponent %s is out of range 0..%s\fR" 4
.IX Item "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:
.Sp
.Vb 3
\& # Fails
\& my $version = Perl::Version\->new( \*(Aq1.4\*(Aq );
\& $version\->increment( 2 );
.Ve
.Sp
Slightly confusingly you'll see this message even if you specified the
component number implicitly by using one of the named convenience
accessors.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Perl::Version requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
No non-core modules.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-perl\-version@rt.cpan.org\*(C'\fR, or through the web interface at
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR
.PP
Hans Dieter Pearcey \f(CW\*(C`<hdp@cpan.org>\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2007, Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.