# Declaring a dotted-decimal $VERSION (keep on one line!)
- 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
+ use version; our $VERSION = version->declare("v1.2.3"); # formal
+ use version; our $VERSION = qv("v1.2.3"); # shorthand
+ use version; our $VERSION = qv("v1.2_3"); # alpha
# Declaring an old-style decimal $VERSION (use quotes!)
- use version 0.77; our $VERSION = version->parse("1.0203"); # formal
- use version 0.77; our $VERSION = version->parse("1.02_03"); # alpha
+ our $VERSION = "1.0203"; # recommended
+ use version; our $VERSION = version->parse("1.0203"); # formal
+ use version; our $VERSION = version->parse("1.02_03"); # alpha
# Comparing mixed version styles (decimals, dotted-decimals, objects)
=item Decimal Versions
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.
+that you don't need to do anything special, just type a number into your
+source file. Quoting is recommended, as it ensures that trailing zeroes
+("1.50") are preserved in any warnings or other output.
=item Dotted Decimal Versions
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
+integers separated 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.
+release if omitted. A leading 'v' character is required to pass the
+L</is_strict()> test.
=back
-See L<VERSION OBJECT DETAILS> for further information.
-
=head1 DECLARING 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:
- our $VERSION = 1.02;
+ our $VERSION = "1.02";
Since Perl v5.10.0 includes the version.pm comparison logic anyways,
you don't need to do anything at all.
=head2 How to C<declare()> a dotted-decimal version
- use version 0.77; our $VERSION = version->declare("v1.2.3");
+ use version; our $VERSION = version->declare("v1.2.3");
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
use C<parse()> instead of declare. See the L<PARSING AND COMPARING VERSIONS>
for details.
-See also L<VERSION OBJECT DETAILS> for more on version number conversion,
+See also L<version::Internals> for more on version number conversion,
quoting, calculated version numbers and declaring developer or "alpha" version
numbers.
=head1 PARSING AND COMPARING VERSIONS
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
+expressed as numbers, strings, v-strings or version objects, then you should
use version.pm to parse them all into objects for comparison.
=head2 How to C<parse()> a version
"1.2.3" v1.2.3
"v1.2.3" v1.2.3
-See L<VERSION OBJECT DETAILS> for more on version number conversion.
+See L<version::Internals> for more on version number conversion.
=head2 How to check for a legal version string
=item C<is_lax()>
-The lax criteria corresponds to what is currently allowed by the
+The lax criteria corresponds to what is currently allowed by the
version parser. All of the following formats are acceptable
for dotted-decimal formats strings:
=item C<is_strict()>
-If you want to limit youself to a much more narrow definition of what
+If you want to limit yourself to a much more narrow definition of what
a version string constitutes, C<is_strict()> is limited to version
strings like the following list:
See L<version::Internals> for details of the regular expressions
that define the legal version string forms, as well as how to use
-those regular expressions in your own code.
+those regular expressions in your own code if C<is_lax()> and
+C<is_strict()> are not sufficient for your needs.
=head2 How to compare version objects
-Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators. Perl
+Version objects overload the C<cmp> and C<< <=> >> operators. Perl
automatically generates all of the other comparison operators based on those
two so all the normal logical comparisons will work.
$bool = $v1 < version->parse("v0.96.0"); # TRUE
-=head1 VERSION OBJECT DETAILS
-
-=head2 Equivalence between Decimal and Dotted-Decimal Versions
-
-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:
-
- 5.6.0 == 5.006000
- 5.005_04 == 5.5.40
-
-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.
-
-This was the method that version.pm adopted as well. Some examples may be
-helpful:
-
- 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 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<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
-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 = version->new((qw$Revision: 1.4)[1]/10);
- print $VERSION; # yields 0.14
- $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 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
- $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
-
-=head2 What about v-strings?
-
-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 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.
-
-If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
-following limitations:
-
-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.
-
-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.
-
-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.
-
-=head2 Alpha versions
-
-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:
+Note that "alpha" version objects (where the version string contains
+a trailing underscore segment) compare as less than the equivalent
+version without an underscore:
- # Declaring
- use version 0.77; our $VERSION = version->declare("v1.2_3");
+ $bool = version->parse("1.23_45") < version->parse("1.2345"); # TRUE
- # Parsing
- $v1 = version->parse("v1.2_3");
- $v1 = version->parse("1.002_003");
+See L<version::Internals> for more details on "alpha" versions.
=head1 OBJECT METHODS
(Not exported by default)
This function takes a scalar argument and returns a boolean value indicating
-whether the argument meets the "lax" rules for a version number.
+whether the argument meets the "lax" rules for a version number. Leading and
+trailing spaces are not allowed.
=head2 is_strict()
(Not exported by default)
This function takes a scalar argument and returns a boolean value indicating
-whether the argument meets the "strict" rules for a version number.
+whether the argument meets the "strict" rules for a version number. Leading
+and trailing spaces are not allowed.
=head1 AUTHOR
=head1 SEE ALSO
-L<version::Internal>.
+L<version::Internals>.
L<perl>.
https://perl5.git.perl.org / perl5.git / blobdiff