=head1 SYNOPSIS
- use version;
- $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
- print $version; # v12.2.1
- print $version->numify; # 12.002001
- if ( $version gt "12.2" ) # true
+ # Parsing version strings (decimal or dotted-decimal)
- $alphaver = version->new("1.02_03"); # must be quoted!
- print $alphaver; # 1.02_0300
- print $alphaver->is_alpha(); # true
-
- $ver = qv("1.2.0"); # v1.2.0
+ use version 0.77; # get latest bug-fixes and API
+ $ver = version->parse($string)
- $perlver = version->new(5.005_03); # must not be quoted!
- print $perlver; # 5.005030
+ # Declaring a dotted-decimal $VERSION (keep on one line!)
-=head1 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.
-
-=head2 BEST PRACTICES
-
-If you intend for your module to be used by different releases of Perl,
-and/or for your $VERSION scalar to mean what you think it means, there
-are a few simple rules to follow:
+ use version 0.77; our $VERSION = version->declare("v1.2.3"); # formal
+ use version 0.77; our $VERSION = qv("v1.2.3"); # shorthand
+ use version 0.77; our $VERSION = qv("v1.2_3"); # alpha
-=over 4
+ # Declaring an old-style decimal $VERSION (use quotes!)
-=item * Be consistent
+ use version 0.77; our $VERSION = version->parse("1.0203"); # formal
+ use version 0.77; our $VERSION = version->parse("1.02_03"); # alpha
-Whichever of the two types of version objects that you choose to employ,
-you should stick to either L<Numeric Versions> or L<Extended Versions>
-and not mix them together. While this is I<possible>, it is very
-confusing to the average user.
+ # Comparing mixed version styles (decimals, dotted-decimals, objects)
-If you intend to use L<Extended Versions>, you are strongly encouraged
-to use the L<qv()> operator with a quoted term, e.g.:
-
- use version; our $VERSION = qv("1.2.3");
+ if ( version->parse($v1) == version->parse($v2) ) {
+ # do stuff
+ }
-on a single line as above.
+ # Sorting mixed version styles
-At the very least, decide on which of the several ways to initialize
-your version objects you prefer and stick with it. It is also best to
-be explicit about what value you intend to assign your version object
-and to not rely on hidden behavior of the parser.
+ @ordered = sort { version->parse($a) <=> version->parse($b) } @list;
-=item * Be careful
+=head1 DESCRIPTION
-If you are using Module::Build or ExtUtils::MakeMaker, so that you can
-release your module to CPAN, you have to recognize that none of those
-programs currently handles version objects natively (yet). That also
-goes for the CPAN indexer (PAUSE). Although there are modules on CPAN
-that employ the version module internally, the support for assigning a
-module $VERSION scalar is still lacking. Both Module::Build and the
-PAUSE indexer will [hopefully soon] include support for version
-objects.
+Version objects were added to Perl in 5.10. This module implements version
+objects for older version of Perl and provides the version object API for all
+versions of Perl. All previous releases before 0.74 are deprecated and should
+not be used due to incompatible API changes. Version 0.77 introduces the new
+'parse' and 'declare' methods to standardize usage. You are strongly urged to
+set 0.77 as a minimum in your code, e.g.
-=head2 What IS a version
+ use version 0.77; # even for Perl v.5.10.0
-For the purposes of this module, a version "number" is a sequence of
-positive integer values separated by one or more 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.
+=head1 TYPES OF VERSION OBJECTS
-There are actually two distinct kinds of version objects:
+There are two different types of version objects, corresponding to the two
+different styles of versions in use:
-=over 4
+=over 2
-=item * Numeric Versions
+=item Decimal Versions
-Any initial parameter which "looks like a number", see L<Numeric
-Versions>. This also covers versions with a single decimal point and
-a single embedded underscore, see L<Numeric Alpha Versions>, even though
-these must be quoted to preserve the underscore formatting.
+The classic floating-point number $VERSION. The advantage to this style is
+that you don't need to do anything special, just type a number (without
+quotes) into your source file.
-=item * Extended Versions
+=item Dotted Decimal Versions
-Any initial parameter which contains more than one decimal point
-and an optional embedded underscore, see L<Extended Versions>. This
-is what is commonly used in most open source software as the "external"
-version (the one used as part of the tag or tarfile name). The use
-of the exported L<qv()> function also produces this kind of version
-object.
+The more modern form of version assignment, with 3 (or potentially more)
+integers seperated by decimal points (e.g. v1.2.3). This is the form that
+Perl itself has used since 5.6.0 was released. The leading "v" is now
+strongly recommended for clarity, and will throw a warning in a future
+release if omitted.
=back
-Both of these methods will produce similar version objects, in that
-the default stringification will yield the version L<Normal Form> only
-if required:
-
- $v = version->new(1.002); # 1.002, but compares like 1.2.0
- $v = version->new(1.002003); # 1.002003
- $v2 = version->new( "1.2.3"); # v1.2.3
-
-In specific, version numbers initialized as L<Numeric Versions> will
-stringify in Numeric form. Version numbers initialized as L<Extended Versions>
-will be stringified as L<Normal Form>.
-
-=head2 Numeric Versions
-
-These correspond to historical versions of Perl itself prior to 5.6.0,
-as well as all other modules which follow the Camel rules for the
-$VERSION scalar. A numeric version is initialized with what looks like
-a floating point number. Leading zeros B<are> significant and trailing
-zeros are implied so that a minimum of three places is maintained
-between subversions. What this means is that any subversion (digits
-to the right of the decimal place) that contains less than three digits
-will have trailing zeros added to make up the difference, but only for
-purposes of comparison with other version objects. For example:
-
- # Prints Equivalent to
- $v = version->new( 1.2); # 1.200 v1.200.0
- $v = version->new( 1.02); # 1.020 v1.20.0
- $v = version->new( 1.002); # 1.002 v1.2.0
- $v = version->new( 1.0023); # 1.002300 v1.2.300
- $v = version->new( 1.00203); # 1.002030 v1.2.30
- $v = version->new( 1.002003); # 1.002003 v1.2.3
-
-All of the preceding examples are true whether or not the input value is
-quoted. The important feature is that the input value contains only a
-single decimal. See also L<Alpha Versions> for how to handle
+See L<VERSION OBJECT DETAILS> for further information.
-IMPORTANT NOTE: As shown above, if your numeric version contains more
-than 3 significant digits after the decimal place, it will be split on
-each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need
-to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.
-Any trailing zeros are ignored for mathematical comparison purposes.
+=head1 DECLARING VERSIONS
-=head2 Extended Versions
+If you have a module that uses a decimal $VERSION (floating point), and you
+do not intend to ever change that, this module is not for you. There is
+nothing that version.pm gains you over a simple $VERSION assignment:
-These are the newest form of versions, and correspond to Perl's own
-version style beginning with 5.6.0. Starting with Perl 5.10.0,
-and most likely Perl 6, this is likely to be the preferred form. This
-method normally requires that the input parameter be quoted, although
-Perl's after 5.8.1 can use v-strings as a special form of quoting, but
-this is highly discouraged.
+ our $VERSION = 1.02;
-Unlike L<Numeric Versions>, Extended Versions have more than
-a single decimal point, e.g.:
+Since Perl v5.10.0 includes the version.pm comparison logic anyways,
+you don't need to do anything at all.
- # Prints
- $v = version->new( "v1.200"); # v1.200.0
- $v = version->new("v1.20.0"); # v1.20.0
- $v = qv("v1.2.3); # v1.2.3
- $v = qv("1.2.3"); # v1.2.3
- $v = qv("1.20"); # v1.20.0
+=head2 How to convert a module from decimal to dotted-decimal
-In general, Extended Versions permit the greatest amount of freedom
-to specify a version, whereas Numeric Versions enforce a certain
-uniformity. See also L<New Operator> for an additional method of
-initializing version objects.
+If you have used a decimal $VERSION in the past and wish to switch to a
+dotted-decimal $VERSION, then you need to make a one-time conversion to
+the new format.
-Just like L<Numeric Versions>, Extended Versions can be used as
-L<Alpha Versions>.
+B<Important Note>: you must ensure that your new $VERSION is numerically
+greater than your current decimal $VERSION; this is not always obvious. First,
+convert your old decimal version (e.g. 1.02) to a normalized dotted-decimal
+form:
-=head2 Numeric Alpha Versions
+ $ perl -Mversion -e 'print version->parse("1.02")->normal'
+ v1.20.0
-The one time that a numeric version must be quoted is when a alpha form is
-used with an otherwise numeric version (i.e. a single decimal point). This
-is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
-versions for automatic updating purposes. Since some developers have used
-only two significant decimal places for their non-alpha releases, the
-version object will automatically take that into account if the initializer
-is quoted. For example Module::Example was released to CPAN with the
-following sequence of $VERSION's:
+Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0).
- # $VERSION Stringified
- 0.01 0.010
- 0.02 0.020
- 0.02_01 0.02_0100
- 0.02_02 0.02_0200
- 0.03 0.030
- etc.
+=head2 How to C<declare()> a dotted-decimal version
-As you can see, the version object created from the values in the first
-column may contain a trailing 0, but will otherwise be both mathematically
-equivalent and sorts alpha-numerically as would be expected.
+ use version 0.77; our $VERSION = version->declare("v1.2.3");
-=head2 Object Methods
+The C<declare()> method always creates dotted-decimal version objects. When
+used in a module, you B<must> put it on the same line as "use version" to
+ensure that $VERSION is read correctly by PAUSE and installer tools. You
+should also add 'version' to the 'configure_requires' section of your
+module metadata file. See instructions in L<ExtUtils::MakeMaker> or
+L<Module::Build> for details.
-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 base version objects.
+B<Important Note>: Even if you pass in what looks like a decimal number
+("1.2"), a dotted-decimal will be created ("v1.200.0"). To avoid confusion
+or unintentional errors on older Perls, follow these guidelines:
-=over 4
+=over 2
-=item * New Operator
+=item *
-Like all OO interfaces, the new() operator is used to initialize
-version objects. One way to increment versions when programming is to
-use the CVS variable $Revision, which is automatically incremented by
-CVS every time the file is committed to the repository.
+Always use a dotted-decimal with (at least) three components
-In order to facilitate this feature, the following
-code can be employed:
+=item *
- $VERSION = version->new(qw$Revision: 2.7 $);
+Always use a leading-v
-and the version object will be created as if the following code
-were used:
-
- $VERSION = version->new("v2.7");
-
-In other words, the version will be automatically parsed out of the
-string, and it will be quoted to preserve the meaning CVS normally
-carries for versions. The CVS $Revision$ increments differently from
-numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
-it were a L<Extended Version>.
+=item *
-A new version object can be created as a copy of an existing version
-object, either as a class method:
-
- $v1 = version->new(12.3);
- $v2 = version->new($v1);
-
-or as an object method:
-
- $v1 = version->new(12.3);
- $v2 = $v1->new();
-
-and in each case, $v1 and $v2 will be identical.
+Always quote the version
=back
-=over 4
-
-=item * qv()
+If you really insist on using version.pm with an ordinary decimal version,
+use C<parse()> instead of declare. See the L<PARSING AND COMPARING VERSIONS>
+for details.
-An alternate way to create a new version object is through the exported
-qv() sub. This is not strictly like other q? operators (like qq, qw),
-in that the only delimiters supported are parentheses (or spaces). It is
-the best way to initialize a short version without triggering the floating
-point interpretation. For example:
+See also L<VERSION OBJECT DETAILS> for more on version number conversion,
+quoting, calculated version numbers and declaring developer or "alpha" version
+numbers.
- $v1 = qv(1.2); # 1.2.0
- $v2 = qv("1.2"); # also 1.2.0
+=head1 PARSING AND COMPARING VERSIONS
-As you can see, either a bare number or a quoted string can usually
-be used interchangably, except in the case of a trailing zero, which
-must be quoted to be converted properly. For this reason, it is strongly
-recommended that all initializers to qv() be quoted strings instead of
-bare numbers.
+If you need to compare version numbers, but can't be sure whether they are
+expressed as numbers, strings, v-strings or version objects, then you can
+use version.pm to parse them all into objects for comparison.
-=back
+=head2 How to C<parse()> a version
-For the subsequent examples, the following three objects will be used:
+The C<parse()> method takes in anything that might be a version and returns
+a corresponding version object, doing any necessary conversion along the way.
- $ver = version->new("1.2.3.4"); # see "Quoting" below
- $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
- $nver = version->new(1.002); # see "Numeric Versions" above
+=over 2
-=over 4
+=item *
-=item * Normal Form
+Dotted-decimal: bare v-strings (v1.2.3) and strings with more than one
+decimal point and a leading 'v' ("v1.2.3"); NOTE you can technically use a
+v-string or strings with a leading-v and only one decimal point (v1.2 or
+"v1.2"), but you will confuse both yourself and others.
-For any version object which is initialized with multiple decimal
-places (either quoted or if possible v-string), or initialized using
-the L<qv()> operator, the stringified representation is returned in
-a normalized or reduced form (no extraneous zeros), and with a leading 'v':
+=item *
- print $ver->normal; # prints as v1.2.3.4
- print $ver->stringify; # ditto
- print $ver; # ditto
- print $nver->normal; # prints as v1.2.0
- print $nver->stringify; # prints as 1.002, see "Stringification"
-
-In order to preserve the meaning of the processed version, the
-normalized representation will always contain at least three sub terms.
-In other words, the following is guaranteed to always be true:
-
- my $newver = version->new($ver->stringify);
- if ($newver eq $ver ) # always true
- {...}
-
-=back
-
-=over 4
-
-=item * Numification
-
-Although all mathematical operations on version objects are forbidden
-by default, it is possible to retrieve a number which 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.002003004
- print $nver->numify; # prints 1.002
-
-Unlike the stringification operator, there is never any need to append
-trailing zeros to preserve the correct version value.
+Decimal: regular decimal numbers (literal or in a string)
=back
-=over 4
+Some examples:
-=item * Stringification
+ $variable version->parse($variable)
+ --------- -------------------------
+ 1.23 v1.230.0
+ "1.23" v1.230.0
+ v1.23 v1.23.0
+ "v1.23" v1.23.0
+ "1.2.3" v1.2.3
+ "v1.2.3" v1.2.3
-In order to mirror as much as possible the existing behavior of ordinary
-$VERSION scalars, the stringification operation will display differently,
-depending on whether the version was initialized as a L<Numeric Version>
-or L<Extended Version>.
+See L<VERSION OBJECT DETAILS> for more on version number conversion.
-What this means in practice is that if the normal CPAN and Camel rules are
-followed ($VERSION is a floating point number with no more than 3 decimal
-points), the stringified output will be exactly the same as the numified
-output. There will be no visible difference, although the internal
-representation will be different, and the L<Comparison operators> will
-function using the internal coding.
+=head2 How to compare version objects
-If a version object is initialized using a L<Extended Version> form, then
-the stringified form will be the L<Normal Form>. The $obj->normal
-operation can always be used to produce the L<Normal Form>, even if the
-version was originally a L<Numeric Version>.
-
- print $ver->stringify; # prints v1.2.3.4
- print $nver->stringify; # prints 1.002
-
-=back
+Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators. Perl
+automatically generates all of the other comparison operators based on those
+two so all the normal logical comparisons will work.
-=over 4
-
-=item * Comparison operators
-
-Both C<cmp> and C<E<lt>=E<gt>> 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.
-In addition to the obvious equalities listed below, appending a single
-trailing 0 term does not change the value of a version for comparison
-purposes. In other words "v1.2" and "1.2.0" will compare as identical.
-
-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.4 $ver eq "1.2.3.4" see discussion below
-
-It is probably best to chose either the numeric notation or the string
-notation and stick with it, to reduce confusion. Perl6 version objects
-B<may> only support numeric comparisons. See also L<Quoting>.
+ if ( version->parse($v1) == version->parse($v2) ) {
+ # do stuff
+ }
-WARNING: Comparing version with unequal numbers of decimal points (whether
-explicitly or implicitly initialized), may yield unexpected results at
-first glance. For example, the following inequalities hold:
+If a version object is compared against a non-version object, the non-object
+term will be converted to a version object using C<parse()>. This may give
+surprising results:
- version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
- version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
+ $v1 = version->parse("v0.95.0");
+ $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0
-For this reason, it is best to use either exclusively L<Numeric Versions> or
-L<Extended Versions> with multiple decimal points.
+Always comparing to a version object will help avoid surprises:
-=back
+ $bool = $v1 < version->parse("v0.96.0"); # TRUE
-=over 4
+=head1 VERSION OBJECT DETAILS
-=item * Logical Operators
+=head2 Equivalence between Decimal and Dotted-Decimal Versions
-If you need to test whether a version object
-has been initialized, you can simply test it directly:
+When Perl 5.6.0 was released, the decision was made to provide a
+transformation between the old-style decimal versions and new-style
+dotted-decimal versions:
- $vobj = version->new($something);
- if ( $vobj ) # true only if $something was non-blank
+ 5.6.0 == 5.006000
+ 5.005_04 == 5.5.40
-You can also test whether a version object is an L<Alpha version>, for
-example to prevent the use of some feature not present in the main
-release:
+The floating point number is taken and split first on the single decimal
+place, then each group of three digits to the right of the decimal makes up
+the next digit, and so on until the number of significant digits is exhausted,
+B<plus> enough trailing zeros to reach the next multiple of three.
- $vobj = version->new("1.2_3"); # MUST QUOTE
- ...later...
- if ( $vobj->is_alpha ) # True
+This was the method that version.pm adopted as well. Some examples may be
+helpful:
-=back
+ equivalent
+ decimal zero-padded dotted-decimal
+ ------- ----------- --------------
+ 1.2 1.200 v1.200.0
+ 1.02 1.020 v1.20.0
+ 1.002 1.002 v1.2.0
+ 1.0023 1.002300 v1.2.300
+ 1.00203 1.002030 v1.2.30
+ 1.002003 1.002003 v1.2.3
-=head2 Quoting
+=head2 Quoting rules
Because of the nature of the Perl parsing and tokenizing routines,
certain initialization values B<must> be quoted in order to correctly
-parse as the intended version, especially when using the L<qv()> operator.
-In all cases, a floating point number passed to version->new() will be
-identically converted whether or not the value itself is quoted. This is
-not true for L<qv()>, however, when trailing zeros would be stripped on
-an unquoted input, which would result in a very different version object.
-
-In addition, in order to be compatible with earlier Perl version styles,
-any use of versions of the form 5.006001 will be translated as v5.6.1.
-In other words, a version with a single decimal point will be parsed as
-implicitly having three digits between subversions, but only for internal
-comparison purposes.
-
-The complicating factor is that in bare numbers (i.e. unquoted), the
-underscore is a legal numeric character and is automatically stripped
-by the Perl tokenizer before the version code is called. However, if
-a number containing one or more decimals and an underscore is quoted, i.e.
-not bare, that is considered a L<Alpha Version> and the underscore is
-significant.
+parse as the intended version, especially when using the L<declare> or
+L<qv> methods. While you do not have to quote decimal numbers when
+creating version objects, it is always safe to quote B<all> initial values
+when using version.pm methods, as this will ensure that what you type is
+what is used.
+
+Additionally, if you quote your initializer, then the quoted value that goes
+B<in> will be be exactly what comes B<out> when your $VERSION is printed
+(stringified). If you do not quote your value, Perl's normal numeric handling
+comes into play and you may not get back what you were expecting.
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
$V2 = version->new(100/9); # Integer overflow in decimal number
print $V2; # yields something like 11.111.111.100
-Perl 5.8.1 and beyond will be able to automatically quote v-strings but
+Perl 5.8.1 and beyond are able to automatically quote v-strings but
that is not possible in earlier versions of Perl. In other words:
$version = version->new("v2.5.4"); # legal in all versions of Perl
=head2 What about v-strings?
-Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
-of bytes was introduced, called v-strings. They were intended to be an
-easy way to enter, for example, Unicode strings (which contain two bytes
-per character). Some programs have used them to encode printer control
-characters (e.g. CRLF). They were also intended to be used for $VERSION,
-but their use as such has been problematic from the start.
-
There are two ways to enter v-strings: a bare number with two or more
decimal points, or a bare number with one or more decimal points and a
leading 'v' character (also bare). For example:
$vs1 = 1.2.3; # encoded as \1\2\3
$vs2 = v1.2; # encoded as \1\2
-However, the use of v-strings to initialize version objects with this
-module is only possible with Perl 5.8.1 or better (which contain special
-code to enable it). Their use is B<strongly> discouraged in all
-circumstances (especially the leading 'v' style), since the meaning will
-change depending on which Perl you are running. It is better to directly
-use L<"Extended Versions"> to ensure the proper interpretation.
-
-
-=head2 Types of Versions Objects
+However, the use of bare v-strings to initialize version objects is
+B<strongly> discouraged in all circumstances. Also, bare
+v-strings are not completely supported in any version of Perl prior to
+5.8.1.
-There are two types of Version Objects:
+If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
+following limitations:
-=over 4
+1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses,
+based on some characteristics of v-strings. You B<must> use a three part
+version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
-=item * Ordinary versions
+2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
+core to be magical, which means that the version.pm code can automatically
+determine whether the v-string encoding was used.
-These are the versions that normal modules will use. Can contain as
-many subversions as required. In particular, those using RCS/CVS can
-use the following:
+3) In all cases, a version created using v-strings will have a stringified
+form that has a leading 'v' character, for the simple reason that sometimes
+it is impossible to tell whether one was present initially.
- $VERSION = version->new(qw$Revision: 2.7 $);
+=head2 Alpha versions
-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
-L<ExtUtils::MakeMaker/"VERSION_FROM">.
+For module authors using CPAN, the convention has been to note unstable
+releases with an underscore in the version string. (See L<CPAN>.) version.pm
+follows this convention and alpha releases will test as being newer than the
+more recent stable release, and less than the next stable release. For
+dotted-decimal versions, only the last element may be separated by an
+underscore:
-=item * Alpha Versions
+ # Declaring
+ use version 0.77; our $VERSION = version->declare("v1.2_3");
-For module authors using CPAN, the convention has been to note
-unstable releases with an underscore in the version string, see
-L<CPAN>. Alpha releases will test as being newer than the more recent
-stable release, and less than the next stable release. For example:
+ # Parsing
+ $v1 = version->parse("v1.2_3");
+ $v1 = version->parse("1.002_003");
- $alphaver = version->new("12.03_01"); # must be quoted
+=head1 OBJECT METHODS
-obeys the relationship
+=head2 is_alpha()
- 12.03 < $alphaver < 12.04
+True if and only if the version object was created with a underscore, e.g.
-Alpha versions with a single decimal point will be treated exactly as if
-they were L<Numeric Versions>, for parsing purposes. The stringification for
-alpha versions with a single decimal point may seem surprising, since any
-trailing zeros will visible. For example, the above $alphaver will print as
+ version->parse('1.002_03')->is_alpha; # TRUE
+ version->declare('1.2.3_4')->is_alpha; # TRUE
- 12.03_0100
+=head2 is_qv()
-which is mathematically equivalent and ASCII sorts exactly the same as
-without the trailing zeros.
+True only if the version object is a dotted-decimal version, e.g.
-Alpha versions with more than a single decimal point will be treated
-exactly as if they were L<Extended Versions>, and will display without any
-trailing (or leading) zeros, in the L<Version Normal> form. For example,
+ version->parse('v1.2.0')->is_qv; # TRUE
+ version->declare('v1.2')->is_qv; # TRUE
+ qv('1.2')->is_qv; # TRUE
+ version->parse('1.2')->is_qv; # FALSE
- $newver = version->new("12.3.1_1");
- print $newver; # v12.3.1_1
+=head2 normal()
-=head2 Replacement UNIVERSAL::VERSION
+Returns a string with a standard 'normalized' dotted-decimal form with a
+leading-v and at least 3 components.
-In addition to the version objects, this modules also replaces the core
-UNIVERSAL::VERSION function with one that uses version objects for its
-comparisons. The return from this operator is always the numified form,
-and the warning message generated includes both the numified and normal
-forms (for clarity).
+ version->declare('v1.2')->normal; # v1.2.0
+ version->parse('1.2')->normal; # v1.200.0
-For example:
+=head2 numify()
- package Foo;
- $VERSION = 1.2;
+Returns a value representing the object in a pure decimal form without
+trailing zeroes.
- package Bar;
- $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
+ version->declare('v1.2')->numify; # 1.002
+ version->parse('1.2')->numify; # 1.2
- package main;
- use version;
+=head2 stringify()
- print $Foo::VERSION; # prints 1.2
+Returns a string that is as close to the original representation as possible.
+If the original representation was a numeric literal, it will be returned the
+way perl would normally represent it in a string. This method is used whenever
+a version object is interpolated into a string.
- print $Bar::VERSION; # prints 1.003005
+ version->declare('v1.2')->stringify; # v1.2
+ version->parse('1.200')->stringify; # 1.200
+ version->parse(1.02_30)->stringify; # 1.023
- eval "use CGI 10"; # some far future release
- print $@; # prints "CGI version 10 (10.0.0) required..."
+=head1 EXPORTED FUNCTIONS
-IMPORTANT NOTE: This may mean that code which searches for a specific
-string (to determine whether a given module is available) may need to be
-changed.
+=head2 qv()
-The replacement UNIVERSAL::VERSION, when used as a function, like this:
+This function is no longer recommended for use, but is maintained for
+compatibility with existing code. If you do not want to have it exported
+to your namespace, use this form:
- print $module->VERSION;
-
-will also exclusively return the numified form. Technically, the
-$module->VERSION function returns a string (PV) that can be converted to a
-number following the normal Perl rules, when used in a numeric context.
-
-=head1 SUBCLASSING
-
-This module is specifically designed and tested to be easily subclassed.
-In practice, you only need to override the methods you want to change, but
-you have to take some care when overriding new() (since that is where all
-of the parsing takes place). For example, this is a perfect acceptable
-derived class:
-
- package myversion;
- use base version;
- sub new {
- my($self,$n)=@_;
- my $obj;
- # perform any special input handling here
- $obj = $self->SUPER::new($n);
- # and/or add additional hash elements here
- return $obj;
- }
-
-See also L<version::AlphaBeta> on CPAN for an alternate representation of
-version strings.
-
-B<NOTE:> the L<qv> operator is not a class method and will not be inherited
-in the same way as the other methods. L<qv> will always return an object of
-type L<version> and not an object in the derived class. If you need to
-have L<qv> return an object in your derived class, add something like this:
-
- *::qv = sub { return bless version::qv(shift), __PACKAGE__ };
-
-as seen in the test file F<t/02derived.t>.
-
-=head1 EXPORT
-
-qv - Extended Version initialization operator
+ use version 0.77 ();
=head1 AUTHOR
=head1 SEE ALSO
+L<version::Internal>.
+
L<perl>.
=cut