This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
new files lib/version.pm and lib/version.t for change #17990.
[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
12$VERSION = (qw$Revision: 2.1 $)[1]/10;
13
14$CLASS = 'version';
15
16bootstrap version if $] < 5.009;
17
18# Preloaded methods go here.
19
201;
21__END__
22
23=head1 NAME
24
25version - Perl extension for Version Objects
26
27=head1 SYNOPSIS
28
29 use version;
30 $version = new version "12.2.1"; # must be quoted!
31 print $version; # 12.2.1
32 print $version->numify; # 12.002001
33 if ( $version > 12.2 ) # true
34
35 $vstring = new version qw(v1.2); # must be quoted!
36 print $vstring; # 1.2
37
38 $betaver = new version "1.2_3"; # must be quoted!
39 print $betaver; # 1.2_3
40
41 $perlver = new version "5.005_03"; # must be quoted!
42 print $perlver; # 5.5.30
43
44=head1 DESCRIPTION
45
46Overloaded version objects for all versions of Perl. This module
47implments all of the features of version objects which will be part
48of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">.
49
50=head2 What IS a version
51
52For the purposes of this module, a version "number" is a sequence of
53positive integral values separated by decimal points and optionally a
54single underscore. This corresponds to what Perl itself uses for a
55version, as well as extending the "version as number" that is discussed
56in the various editions of the Camel book.
57
58=head2 Object Methods
59
60Overloading has been used with version objects to provide a natural
61interface for their use. All mathematical operations are forbidden,
62since they don't make any sense for versions. For the subsequent
63examples, the following two objects will be used:
64
65 $ver = new version "1.2.3"; # see "Quoting" below
66 $beta = new version "1.2_3"; # see "Beta versions" below
67
68=item * Stringification - Any time a version object is used as a string,
69a stringified representation is returned in reduced form (no extraneous
70zeros):
71
72 print $ver->stringify; # prints 1.2.3
73 print $ver; # same thing
74
75=item * Numification - although all mathematical operations on version
76objects are forbidden by default, it is possible to retrieve a number
77which roughly corresponds to the version object through the use of the
78$obj->numify method. For formatting purposes, when displaying a number
79which corresponds a version object, all sub versions are assumed to have
80three decimal places. So for example:
81
82 print $ver->numify; # prints 1.002003
83
84=item * Comparison operators - Both cmp and <=> operators perform the
85same comparison between terms (upgrading to a version object
86automatically). Perl automatically generates all of the other comparison
87operators based on those two. For example, the following relations hold:
88
89 As Number As String Truth Value
90 --------- ------------ -----------
91 $ver > 1.0 $ver gt "1.0" true
92 $ver < 2.5 $ver lt true
93 $ver != 1.3 $ver ne "1.3" true
94 $ver == 1.2 $ver eq "1.2" false
95 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
96 $ver == v1.2.3 $ver eq "v1.2.3" ditto
97
98In versions of Perl prior to the 5.9.0 development releases, it is not
99permitted to use bare v-strings in either form, due to the nature of Perl's
100parsing operation. After that version (and in the stable 5.10.0 release),
101v-strings can be used with version objects without problem, see L<"Quoting">
102for more discussion of this topic. In the case of the last two lines of
103the table above, only the string comparison will be true; the numerical
104comparison will test false. However, you can do this:
105
106 $ver == "1.2.3" or $ver = "v.1.2.3" # both true
107
108even though you are doing a "numeric" comparison with a "string" value.
109It is probably best to chose either the numeric notation or the string
110notation and stick with it, to reduce confusion. See also L<"Quoting">.
111
112=head2 Quoting
113
114Because of the nature of the Perl parsing and tokenizing routines,
115you should always quote the parameter to the new() operator/method. The
116exact notation is vitally important to correctly determine the version
117that is requested. You don't B<have> to quote the version parameter,
118but you should be aware of what Perl is likely to do in those cases.
119
120If you use a mathematic formula that resolves to a floating point number,
121you are dependent on Perl's conversion routines to yield the version you
122expect. You are pretty safe by dividing by a power of 10, for example,
123but other operations are not likely to be what you intend. For example:
124
125 $VERSION = new version (qw$Revision: 1.4)[1]/10;
126 print $VERSION; # yields 0.14
127 $V2 = new version 100/9; # Integer overflow in decimal number
128 print $V2; # yields 11_1285418553
129
130You B<can> use a bare number, if you only have a major and minor version,
131since this should never in practice yield a floating point notation
132error. For example:
133
134 $VERSION = new version 10.2; # almost certainly ok
135 $VERSION = new version "10.2"; # guaranteed ok
136
137Perl 5.9.0 and beyond will be able to automatically quote v-strings
138(which may become the recommended notation), but that is not possible in
139earlier versions of Perl. In other words:
140
141 $version = new version "v2.5.4"; # legal in all versions of Perl
142 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
143
144
145=head2 Types of Versions Objects
146
147There are three basic types of Version Objects:
148
149=item * Ordinary versions - These are the versions that normal
150modules will use. Can contain as many subversions as required.
151In particular, those using RCS/CVS can use one of the following:
152
153 $VERSION = new version (qw$Revision: 2.1 $)[1]; # all Perls
154 $VERSION = new version qw$Revision: 2.1 $[1]; # Perl >= 5.6.0
155
156and the current RCS Revision for that file will be inserted
157automatically. If the file has been moved to a branch, the
158Revision will have three or more elements; otherwise, it will
159have only two. This allows you to automatically increment
160your module version by using the Revision number from the primary
161file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
162
163In order to be compatible with earlier Perl version styles, any use
164of versions of the form 5.006001 will be translated as 5.6.1, In
165other words a version with a single decimal place will be parsed
166as implicitely having three places between subversion.
167
168=item * Beta versions - For module authors using CPAN, the
169convention has been to note unstable releases with an underscore
170in the version string, see L<CPAN>. Beta releases will test as being
171newer than the more recent stable release, and less than the next
172stable release. For example:
173
174 $betaver = new version "12.3_1"; # must quote
175
176obeys the relationship
177
178 12.3 < $betaver < 12.4
179
180As a matter of fact, if is also true that
181
182 12.3.0 < $betaver < 12.3.1
183
184where the subversion is identical but the beta release is less than
185the non-beta release.
186
187=item * Perl-style versions - an exceptional case is versions that
188were only used by Perl releases prior to 5.6.0. If a version
189string contains an underscore immediately followed by a zero followed
190by a non-zero number, the version is processed according to the rules
191described in L<perldelta/Improved Perl version numbering system>
192released with Perl 5.6.0. As an example:
193
194 $perlver = new version "5.005_03";
195
196is interpreted, not as a beta release, but as the version 5.5.30, NOTE
197that the major and minor versions are unchanged but the subversion is
198multiplied by 10, since the above was implicitely read as 5.005.030.
199There are modules currently on CPAN which may fall under of this rule, so
200module authors are urged to pay close attention to what version they are
201specifying.
202
203=head2 Replacement UNIVERSAL::VERSION
204
205In addition to the version objects, this modules also replaces the core
206UNIVERSAL::VERSION function with one that uses version objects for its
207comparisons. So, for example, with all existing versions of Perl,
208something like the following pseudocode would fail:
209
210 package vertest;
211 $VERSION = 0.45;
212
213 package main;
214 use vertest 0.5;
215
216even though those versions are meant to be read as 0.045 and 0.005
217respectively. The UNIVERSAL::VERSION replacement function included
218with this module changes that behavior so that it will B<not> fail.
219
220=head1 EXPORT
221
222None by default.
223
224=head1 AUTHOR
225
226John Peacock E<lt>jpeacock@rowman.comE<gt>
227
228=head1 SEE ALSO
229
230L<perl>.
231
232=cut
233#!/usr/local/bin/perl -w
234package version;
235
236use 5.005_03;
237use strict;
238
239require Exporter;
240require DynaLoader;
241use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $CLASS);
242
243@ISA = qw(Exporter DynaLoader);
244
245# This allows declaration use version ':all';
246# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
247# will save memory.
248%EXPORT_TAGS = ( 'all' => [ qw(
249
250) ] );
251
252@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
253
254@EXPORT = qw(
255);
256
257$VERSION = (qw$Revision: 1.8 $)[1]/10;
258
259$CLASS = 'version';
260
261bootstrap version if $] < 5.009;
262
263# Preloaded methods go here.
264
2651;
266__END__
267
268=head1 NAME
269
270version - Perl extension for Version Objects
271
272=head1 SYNOPSIS
273
274 use version;
275 $version = new version "12.2.1"; # must be quoted!
276 print $version; # 12.2.1
277 print $version->numify; # 12.002001
278 if ( $version > 12.2 ) # true
279
280 $vstring = new version qw(v1.2); # must be quoted!
281 print $vstring; # 1.2
282
283 $betaver = new version "1.2_3"; # must be quoted!
284 print $betaver; # 1.2_3
285
286 $perlver = new version "5.005_03"; # must be quoted!
287 print $perlver; # 5.5.30
288
289=head1 DESCRIPTION
290
291Overloaded version objects for all versions of Perl. This module
292implments all of the features of version objects which will be part
293of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">.
294
295=head2 What IS a version
296
297For the purposes of this module, a version "number" is a sequence of
298positive integral values separated by decimal points and optionally a
299single underscore. This corresponds to what Perl itself uses for a
300version, as well as including the "version as number" that is discussed
301in the various editions of the Camel book.
302
303=head2 Object Methods
304
305Overloading has been used with version objects to provide a natural
306interface for their use. All mathematical operations are forbidden,
307since they don't make any sense for versions. For the subsequent
308examples, the following two objects will be used:
309
310 $ver = new version "1.2.3"; # see "Quoting" below
311 $beta = new version "1.2_3"; # see "Beta versions" below
312
313=item * Stringification - Any time a version object is used as a string,
314a stringified representation is returned in reduced form (no extraneous
315zeros):
316
317 print $ver->stringify; # prints 1.2.3
318 print $ver; # same thing
319
320=item * Numification - although all mathematical operations on version
321objects are forbidden by default, it is possible to retrieve a number
322which roughly corresponds to the version object through the use of the
323$obj->numify method. For formatting purposes, when displaying a number
324which corresponds a version object, all sub versions are assumed to have
325three decimal places. So for example:
326
327 print $ver->numify; # prints 1.002003
328
329=item * Comparison operators - Both cmp and <=> operators perform the
330same comparison between terms (upgrading to a version object
331automatically). Perl automatically generates all of the other comparison
332operators based on those two. For example, the following relations hold:
333
334 As Number As String Truth Value
335 --------- ------------ -----------
336 $ver > 1.0 $ver gt "1.0" true
337 $ver < 2.5 $ver lt true
338 $ver != 1.3 $ver ne "1.3" true
339 $ver == 1.2 $ver eq "1.2" false
340 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
341 $ver == v1.2.3 $ver eq "v1.2.3" ditto
342
343In versions of Perl prior to the 5.9.0 development releases, it is not
344permitted to use bare v-strings in either form, due to the nature of Perl's
345parsing operation. After that version (and in the stable 5.10.0 release),
346v-strings can be used with version objects without problem, see L<"Quoting">
347for more discussion of this topic. In the case of the last two lines of
348the table above, only the string comparison will be true; the numerical
349comparison will test false. However, you can do this:
350
351 $ver == "1.2.3" or $ver = "v.1.2.3" # both true
352
353even though you are doing a "numeric" comparison with a "string" value.
354It is probably best to chose either the numeric notation or the string
355notation and stick with it, to reduce confusion. See also L<"Quoting">.
356
357=head2 Quoting
358
359Because of the nature of the Perl parsing and tokenizing routines,
360you should always quote the parameter to the new() operator/method. The
361exact notation is vitally important to correctly determine the version
362that is requested. You don't B<have> to quote the version parameter,
363but you should be aware of what Perl is likely to do in those cases.
364
365If you use a mathematic formula that resolves to a floating point number,
366you are dependent on Perl's conversion routines to yield the version you
367expect. You are pretty safe by dividing by a power of 10, for example,
368but other operations are not likely to be what you intend. For example:
369
370 $VERSION = new version (qw$Revision: 1.4)[1]/10;
371 print $VERSION; # yields 0.14
372 $V2 = new version 100/9; # Integer overflow in decimal number
373 print $V2; # yields 11_1285418553
374
375You B<can> use a bare number, if you only have a major and minor version,
376since this should never in practice yield a floating point notation
377error. For example:
378
379 $VERSION = new version 10.2; # almost certainly ok
380 $VERSION = new version "10.2"; # guaranteed ok
381
382Perl 5.9.0 and beyond will be able to automatically quote v-strings
383(which may become the recommended notation), but that is not possible in
384earlier versions of Perl. In other words:
385
386 $version = new version "v2.5.4"; # legal in all versions of Perl
387 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
388
389
390=head2 Types of Versions Objects
391
392There are three basic types of Version Objects:
393
394=item * Ordinary versions - These are the versions that normal
395modules will use. Can contain as many subversions as required.
396In particular, those using RCS/CVS can use one of the following:
397
398 $VERSION = new version (qw$Revision: 1.8 $)[1]; # all Perls
399 $VERSION = new version qw$Revision: 1.8 $[1]; # Perl >= 5.6.0
400
401and the current RCS Revision for that file will be inserted
402automatically. If the file has been moved to a branch, the
403Revision will have three or more elements; otherwise, it will
404have only two. This allows you to automatically increment
405your module version by using the Revision number from the primary
406file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
407
408=item * Beta versions - For module authors using CPAN, the
409convention has been to note unstable releases with an underscore
410in the version string, see L<CPAN>. Beta releases will test as being
411newer than the more recent stable release, and less than the next
412stable release. For example:
413
414 $betaver = new version "12.3_1"; # must quote
415
416obeys the relationship
417
418 12.3 < $betaver < 12.4
419
420As a matter of fact, if is also true that
421
422 12.3.0 < $betaver < 12.3.1
423
424where the subversion is identical but the beta release is less than
425the non-beta release.
426
427=item * Perl-style versions - an exceptional case is versions that
428were only used by Perl releases prior to 5.6.0. If a version
429string contains an underscore immediately followed by a zero followed
430by a non-zero number, the version is processed according to the rules
431described in L<perldelta/Improved Perl version numbering system>
432released with Perl 5.6.0. As an example:
433
434 $perlver = new version "5.005_03";
435
436is interpreted, not as a beta release, but as the version 5.5.30, NOTE
437that the major and minor versions are unchanged but the subversion is
438multiplied by 10, since the above was implicitely read as 5.005.030.
439There are modules currently on CPAN which may fall under of this rule, so
440module authors are urged to pay close attention to what version they are
441specifying.
442
443=head2 Replacement UNIVERSAL::VERSION
444
445In addition to the version objects, this modules also replaces the core
446UNIVERSAL::VERSION function with one that uses version objects for its
447comparisons. So, for example, with all existing versions of Perl,
448something like the following pseudocode would fail:
449
450 package vertest;
451 $VERSION = 0.45;
452
453 package main;
454 use vertest 0.5;
455
456even though those versions are meant to be read as 0.045 and 0.005
457respectively. The UNIVERSAL::VERSION replacement function included
458with this module changes that behavior so that it will B<not> fail.
459
460=head1 EXPORT
461
462None by default.
463
464=head1 AUTHOR
465
466John Peacock E<lt>jpeacock@rowman.comE<gt>
467
468=head1 SEE ALSO
469
470L<perl>.
471
472=cut