This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add CPAN ChangeLog to MANIFEST.
[perl5.git] / lib / version.pm
CommitLineData
a7ad731c
HS
1#!/usr/local/bin/perl -w
2package version;
3
4use 5.005_03;
5use strict;
6
7require DynaLoader;
8use vars qw(@ISA $VERSION $CLASS);
9
10@ISA = qw(DynaLoader);
11
26ec6fc3 12$VERSION = (qw$Revision: 2.3 $)[1]/10;
a7ad731c
HS
13
14$CLASS = 'version';
15
26ec6fc3 16local $^W; # shut up the 'redefined' warning for UNIVERSAL::VERSION
a7ad731c
HS
17bootstrap version if $] < 5.009;
18
19# Preloaded methods go here.
20
211;
22__END__
23
24=head1 NAME
25
26version - Perl extension for Version Objects
27
28=head1 SYNOPSIS
29
30 use version;
31 $version = new version "12.2.1"; # must be quoted!
32 print $version; # 12.2.1
33 print $version->numify; # 12.002001
34 if ( $version > 12.2 ) # true
35
36 $vstring = new version qw(v1.2); # must be quoted!
37 print $vstring; # 1.2
38
39 $betaver = new version "1.2_3"; # must be quoted!
40 print $betaver; # 1.2_3
41
42 $perlver = new version "5.005_03"; # must be quoted!
43 print $perlver; # 5.5.30
44
45=head1 DESCRIPTION
46
47Overloaded version objects for all versions of Perl. This module
26ec6fc3 48implements all of the features of version objects which will be part
a7ad731c
HS
49of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">.
50
51=head2 What IS a version
52
53For the purposes of this module, a version "number" is a sequence of
54positive integral values separated by decimal points and optionally a
55single underscore. This corresponds to what Perl itself uses for a
56version, as well as extending the "version as number" that is discussed
57in the various editions of the Camel book.
58
46314c13
JP
59However, in order to be compatible with earlier Perl version styles,
60any use of versions of the form 5.006001 will be translated as 5.6.1,
26ec6fc3
JP
61In other words, a version with a single decimal place will be parsed
62as implicitly having three places between subversion.
46314c13
JP
63
64Any value passed to the new() operator will be parsed only so far as it
65contains a numeric, decimal, or underscore character. So, for example:
66
67 $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0
68 $v2 = new version "something"; # $v2 == "" and $v2->numify == 0
69
70NOTE: it is strongly recommended that version objects only be created
71with numeric values based on the different types of versions in this
72documentation, see L<"Types of Versions Objects">. That way, there is
73no confusion about what constitutes the version.
74
a7ad731c
HS
75=head2 Object Methods
76
77Overloading has been used with version objects to provide a natural
78interface for their use. All mathematical operations are forbidden,
79since they don't make any sense for versions. For the subsequent
80examples, the following two objects will be used:
81
82 $ver = new version "1.2.3"; # see "Quoting" below
83 $beta = new version "1.2_3"; # see "Beta versions" below
84
85=item * Stringification - Any time a version object is used as a string,
86a stringified representation is returned in reduced form (no extraneous
87zeros):
88
89 print $ver->stringify; # prints 1.2.3
90 print $ver; # same thing
91
92=item * Numification - although all mathematical operations on version
93objects are forbidden by default, it is possible to retrieve a number
94which roughly corresponds to the version object through the use of the
95$obj->numify method. For formatting purposes, when displaying a number
96which corresponds a version object, all sub versions are assumed to have
97three decimal places. So for example:
98
99 print $ver->numify; # prints 1.002003
100
101=item * Comparison operators - Both cmp and <=> operators perform the
102same comparison between terms (upgrading to a version object
103automatically). Perl automatically generates all of the other comparison
104operators based on those two. For example, the following relations hold:
105
106 As Number As String Truth Value
107 --------- ------------ -----------
108 $ver > 1.0 $ver gt "1.0" true
109 $ver < 2.5 $ver lt true
110 $ver != 1.3 $ver ne "1.3" true
111 $ver == 1.2 $ver eq "1.2" false
112 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
113 $ver == v1.2.3 $ver eq "v1.2.3" ditto
114
115In versions of Perl prior to the 5.9.0 development releases, it is not
116permitted to use bare v-strings in either form, due to the nature of Perl's
117parsing operation. After that version (and in the stable 5.10.0 release),
118v-strings can be used with version objects without problem, see L<"Quoting">
119for more discussion of this topic. In the case of the last two lines of
120the table above, only the string comparison will be true; the numerical
121comparison will test false. However, you can do this:
122
26ec6fc3 123 $ver == "1.2.3" or $ver == "v1.2.3" # both true
a7ad731c
HS
124
125even though you are doing a "numeric" comparison with a "string" value.
126It is probably best to chose either the numeric notation or the string
127notation and stick with it, to reduce confusion. See also L<"Quoting">.
128
129=head2 Quoting
130
131Because of the nature of the Perl parsing and tokenizing routines,
132you should always quote the parameter to the new() operator/method. The
133exact notation is vitally important to correctly determine the version
134that is requested. You don't B<have> to quote the version parameter,
135but you should be aware of what Perl is likely to do in those cases.
136
137If you use a mathematic formula that resolves to a floating point number,
138you are dependent on Perl's conversion routines to yield the version you
139expect. You are pretty safe by dividing by a power of 10, for example,
140but other operations are not likely to be what you intend. For example:
141
142 $VERSION = new version (qw$Revision: 1.4)[1]/10;
143 print $VERSION; # yields 0.14
144 $V2 = new version 100/9; # Integer overflow in decimal number
145 print $V2; # yields 11_1285418553
146
147You B<can> use a bare number, if you only have a major and minor version,
148since this should never in practice yield a floating point notation
149error. For example:
150
151 $VERSION = new version 10.2; # almost certainly ok
152 $VERSION = new version "10.2"; # guaranteed ok
153
154Perl 5.9.0 and beyond will be able to automatically quote v-strings
155(which may become the recommended notation), but that is not possible in
156earlier versions of Perl. In other words:
157
158 $version = new version "v2.5.4"; # legal in all versions of Perl
159 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
160
161
162=head2 Types of Versions Objects
163
164There are three basic types of Version Objects:
165
166=item * Ordinary versions - These are the versions that normal
167modules will use. Can contain as many subversions as required.
168In particular, those using RCS/CVS can use one of the following:
169
26ec6fc3
JP
170 $VERSION = new version (qw$Revision: 2.3 $)[1]; # all Perls
171 $VERSION = new version qw$Revision: 2.3 $[1]; # Perl >= 5.6.0
a7ad731c
HS
172
173and the current RCS Revision for that file will be inserted
174automatically. If the file has been moved to a branch, the
175Revision will have three or more elements; otherwise, it will
176have only two. This allows you to automatically increment
177your module version by using the Revision number from the primary
178file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
179
a7ad731c
HS
180=item * Beta versions - For module authors using CPAN, the
181convention has been to note unstable releases with an underscore
182in the version string, see L<CPAN>. Beta releases will test as being
183newer than the more recent stable release, and less than the next
184stable release. For example:
185
186 $betaver = new version "12.3_1"; # must quote
187
188obeys the relationship
189
190 12.3 < $betaver < 12.4
191
192As a matter of fact, if is also true that
193
194 12.3.0 < $betaver < 12.3.1
195
196where the subversion is identical but the beta release is less than
197the non-beta release.
198
199=item * Perl-style versions - an exceptional case is versions that
200were only used by Perl releases prior to 5.6.0. If a version
201string contains an underscore immediately followed by a zero followed
202by a non-zero number, the version is processed according to the rules
203described in L<perldelta/Improved Perl version numbering system>
204released with Perl 5.6.0. As an example:
205
206 $perlver = new version "5.005_03";
207
208is interpreted, not as a beta release, but as the version 5.5.30, NOTE
209that the major and minor versions are unchanged but the subversion is
26ec6fc3 210multiplied by 10, since the above was implicitly read as 5.005.030.
a7ad731c
HS
211There are modules currently on CPAN which may fall under of this rule, so
212module authors are urged to pay close attention to what version they are
213specifying.
214
215=head2 Replacement UNIVERSAL::VERSION
216
217In addition to the version objects, this modules also replaces the core
218UNIVERSAL::VERSION function with one that uses version objects for its
219comparisons. So, for example, with all existing versions of Perl,
220something like the following pseudocode would fail:
221
222 package vertest;
223 $VERSION = 0.45;
224
225 package main;
226 use vertest 0.5;
227
228even though those versions are meant to be read as 0.045 and 0.005
229respectively. The UNIVERSAL::VERSION replacement function included
230with this module changes that behavior so that it will B<not> fail.
231
232=head1 EXPORT
233
234None by default.
235
236=head1 AUTHOR
237
238John Peacock E<lt>jpeacock@rowman.comE<gt>
239
240=head1 SEE ALSO
241
242L<perl>.
243
244=cut