Perl::Version(3pm)

1Perl::Version(3)      User Contributed Perl Documentation     Perl::Version(3)
2
3
4

NAME

6       Perl::Version - Parse and manipulate Perl version strings
7

VERSION

9       This document describes Perl::Version version 1.009
10

SYNOPSIS

12           use Perl::Version;
13
14           # Init from string
15           my $version = Perl::Version->new( '1.2.3' );
16
17           # Stringification preserves original format
18           print "$version\n";                 # prints '1.2.3'
19
20           # Normalised
21           print $version->normal, "\n";       # prints 'v1.2.3'
22
23           # Numified
24           print $version->numify, "\n";       # prints '1.002003'
25
26           # Explicitly stringified
27           print $version->stringify, "\n";    # prints '1.2.3'
28
29           # Increment the subversion (the third component)
30           $version->inc_subversion;
31
32           # Stringification returns the updated version formatted
33           # as the original was
34           print "$version\n";                 # prints '1.2.4'
35
36           # Normalised
37           print $version->normal, "\n";       # prints 'v1.2.4'
38
39           # Numified
40           print $version->numify, "\n";       # prints '1.002004'
41
42           # Refer to subversion component by position ( zero based )
43           $version->increment( 2 );
44
45           print "$version\n";                 # prints '1.2.5'
46
47           # Increment the version (second component) which sets all
48           # components to the right of it to zero.
49           $version->inc_version;
50
51           print "$version\n";                 # prints '1.3.0'
52
53           # Increment the revision (main version number)
54           $version->inc_revision;
55
56           print "$version\n";                 # prints '2.0.0'
57
58           # Increment the alpha number
59           $version->inc_alpha;
60
61           print "$version\n";                 # prints '2.0.0_001'
62

DESCRIPTION

64       Perl::Version provides a simple interface for parsing, manipulating and
65       formatting Perl version strings.
66
67       Unlike version.pm (which concentrates on parsing and comparing version
68       strings) Perl::Version is designed for cases where you'd like to parse
69       a version, modify it and get back the modified version formatted like
70       the original.
71
72       For example:
73
74           my $version = Perl::Version->new( '1.2.3' );
75           $version->inc_version;
76           print "$version\n";
77
78       prints
79
80           1.3.0
81
82       whereas
83
84           my $version = Perl::Version->new( 'v1.02.03' );
85           $version->inc_version;
86           print "$version\n";
87
88       prints
89
90           v1.03.00
91
92       Both are representations of the same version and they'd compare equal
93       but their formatting is different.
94
95       Perl::Version tries hard to guess and recreate the format of the
96       original version and in most cases it succeeds. In rare cases the
97       formatting is ambiguous. Consider
98
99           1.10.03
100
101       Do you suppose that second component '10' is zero padded like the third
102       component? Perl::Version will assume that it is:
103
104           my $version = Perl::Version->new( '1.10.03' );
105           $version->inc_revision;
106           print "$version\n";
107
108       will print
109
110           2.00.00
111
112       If all of the components after the first are the same length (two
113       characters in this case) and any of them begins with a zero
114       Perl::Version will assume that they're all zero padded to the same
115       length.
116
117       The first component and any alpha suffix are handled separately. In
118       each case if either of them starts with a zero they will be zero padded
119       to the same length when stringifying the version.
120
121   Version Formats
122       Perl::Version supports a few different version string formats.
123
124        1, 1.2
125           Versions that look like a number. If you pass a numeric value its
126           string equivalent will be parsed:
127
128               my $version = Perl::Version->new( 1.2 );
129               print "$version\n";
130
131           prints
132
133               1.2
134
135           In fact there is no special treatment for versions that resemble
136           decimal numbers. This is worthy of comment only because it differs
137           from version.pm which treats actual numbers used as versions as a
138           special case and performs various transformations on the stored
139           version.
140
141        1.2.3, 1.2.3.4
142           Simple versions with three or more components.
143
144        v1.2.3
145           Versions with a leading 'v'.
146
147        5.008006
148           Fielded numeric versions. You'll likely have seen this in relation
149           to versions of Perl itself. If a version string has a single
150           decimal point and the part after the point is three more more
151           digits long components are extracted from each group of three
152           digits in the fractional part.
153
154           For example
155
156               my $version = Perl::Version->new( 1.002003004005006 );
157               print $version->normal;
158
159           prints
160
161               v1.2.3.4.5.6
162
163       vstring
164           Perls later than 5.8.1 support vstring format. A vstring looks like
165           a number with more than one decimal point and (optionally) a
166           leading 'v'. The 'v' is mandatory for vstrings containing fewer
167           than two decimal points.
168
169           Perl::Version will successfully parse vstrings
170
171               my $version = Perl::Version->new( v1.2 );
172               print "$version\n";
173
174           prints
175
176               v1.2
177
178           Note that stringifying a Perl::Version constructed from a vstring
179           will result in a regular string. Because it has no way of knowing
180           whether the vstring constant had a 'v' prefix it always generates
181           one when stringifying back to a version string.
182
183       CVS version
184           A common idiom for users of CVS is to use keyword replacement to
185           generate a version automatically like this:
186
187               $VERSION = version->new( qw$Revision: 2.7 $ );
188
189           Perl::Version does the right thing with such versions so that
190
191               my $version = Perl::Version->new( qw$Revision: 2.7 $ );
192               $version->inc_revision;
193               print "$version\n";
194
195           prints
196
197               Revision: 3.0
198
199       Real Numbers
200
201       Real numbers are stringified before parsing. This has two implications:
202       trailing zeros after the decimal point will be lost and any underscore
203       characters in the number are discarded.
204
205       Perl allows underscores anywhere in numeric constants as an aid to
206       formatting. These are discarded when Perl converts the number into its
207       internal format. This means that
208
209           # Numeric version
210           print Perl::Version->new( 1.001_001 )->stringify;
211
212       prints
213
214           1.001001
215
216       but
217
218           # String version
219           print Perl::Version->new( '1.001_001' )->stringify;
220
221       prints
222
223           1.001_001
224
225       as expected.
226
227       In general you should probably avoid versions expressed either as
228       decimal numbers or vstrings. The safest option is to pass a regular
229       string to Perl::Version->new().
230
231       Alpha Versions
232
233       By convention if a version string has suffix that consists of an
234       underscore followed by one or more digits it represents an alpha or
235       developer release. CPAN treats modules with such version strings
236       specially to reflect their alpha status.
237
238       This alpha notation is one reason why using decimal numbers as versions
239       is a bad idea. Underscore is a valid character in numeric constants
240       which is discarded by Perl when a program's source is parsed so any
241       intended alpha suffix will become part of the version number.
242
243       To be considered alpha a version must have a non-zero alpha component
244       like this
245
246           3.0.4_001
247
248       Generally the alpha component will be formatted with leading zeros but
249       this is not a requirement.
250
251   Component Naming
252       A version number consists of a series of components. By Perl convention
253       the first three components are named 'revision', 'version' and
254       'subversion':
255
256           $ perl -V
257           Summary of my perl5 (revision 5 version 8 subversion 6) configuration:
258
259           (etc)
260
261       Perl::Version follows that convention. Any component may be accessed by
262       passing a number from 0 to N-1 to the component or increment but for
263       convenience the first three components are aliased as revision, version
264       and subversion.
265
266           $version->increment( 0 );
267
268       is the same as
269
270           $version->inc_revision;
271
272       and
273
274           my $subv = $version->subversion;
275
276       is the same as
277
278           my $subv = $version->component( 2 );
279
280       The alpha component is named 'alpha'.
281
282   Comparison with version.pm
283       If you're familiar with version.pm you'll notice that there's a certain
284       amount of overlap between what it does and this module. I originally
285       created this module as a mutable subclass of version.pm but the
286       requirement to be able to reformat a modified version to match the
287       formatting of the original didn't sit well with version.pm's internals.
288
289       As a result this module is not dependent or based on version.pm.
290

INTERFACE

292       "new"
293           Create a new Perl::Version by parsing a version string. As
294           discussed above a number of different version formats are
295           supported. Along with the value of the version formatting
296           information is captured so that the version can be modified and the
297           updated value retrieved in the same format as the original.
298
299               my @version = (
300                   '1.3.0',    'v1.03.00',     '1.10.03', '2.00.00',
301                   '1.2',      'v1.2.3.4.5.6', 'v1.2',    'Revision: 3.0',
302                   '1.001001', '1.001_001',    '3.0.4_001',
303               );
304
305               for my $v ( @version ) {
306                   my $version = Perl::Version->new( $v );
307                   $version->inc_version;
308                   print "$version\n";
309               }
310
311           prints
312
313               1.4.0
314               v1.04.00
315               1.11.00
316               2.01.00
317               1.3
318               v1.3.0.0.0.0
319               v1.3
320               Revision: 3.1
321               1.002000
322               1.002
323               3.1.0
324
325           In each case the incremented version is formatted in the same way
326           as the original.
327
328           If no arguments are passed an empty version intialised to 'v0' will
329           be constructed.
330
331           In order to support CVS version syntax
332
333               my $version = Perl::Version->new( qw$Revision: 2.7 $ );
334
335           "new" may be passed an array in which case it concatenates all of
336           its arguments with spaces before parsing the result.
337
338           If the string can't be parsed as a version "new" will croak with a
339           suitable error. See DIAGNOSTICS for more information.
340
341   Accessors
342       "component"
343           Set or get one of the components of a version.
344
345               # Set the subversion
346               $version->component( 2, 17 );
347
348               # Get the revision
349               my $rev = $version->component( 0 );
350
351           Instead of a component number you may pass a name: 'revision',
352           'version', 'subversion' or 'alpha':
353
354               my $rev = $version->component( 'revision' );
355
356       "components"
357           Get or set all of the components of a version.
358
359               # Set the number of components
360               $version->components( 4 );
361
362               # Get the number of components
363               my $parts = $version->components;
364
365               # Get the individual components as an array
366               my @parts = $version->components;
367
368               # Set the components from an array
369               $version->components( [ 5, 9, 2 ] );
370
371           Hmm. That's a lot of interface for one subroutine. Sorry about
372           that.
373
374       "revision"
375           Alias for component( 0 ). Gets or sets the revision component.
376
377       "version"
378           Alias for component( 1 ). Gets or sets the version component.
379
380       "subversion"
381           Alias for component( 2 ). Gets or sets the subversion component.
382
383       "alpha"
384           Get or set the alpha component of a version. Returns 0 for versions
385           with no alpha.
386
387               # Set alpha
388               $version->alpha( 12 );
389
390               # Get alpha
391               my $alp = $version->alpha;
392
393       "is_alpha"
394           Return true if a version has a non-zero alpha component.
395
396       "set"
397           Set the version to match another version preserving the formatting
398           of this version.
399
400               $version->set( $other_version );
401
402           You may also set the version from a literal string:
403
404               $version->set( '1.2.3' );
405
406           The version will be updated to the value of the version string but
407           will retain its current formatting.
408
409   Incrementing
410       "increment"
411           Increment a component of a version.
412
413               my $version = Perl::Version->new( '3.1.4' );
414               $version->increment( 1 );
415               print "$version\n";
416
417           prints
418
419               3.2.0
420
421           Components to the right of the incremented component will be set to
422           zero as will any alpha component.
423
424           As an alternative to passing a component number one of the
425           predefined component names 'revision', 'version', 'subversion' or
426           'alpha' may be passed.
427
428       "inc_alpha"
429           Increment a version's alpha component.
430
431       "inc_revision"
432           Increment a version's revision component.
433
434       "inc_subversion"
435           Increment a version's subversion component.
436
437       "inc_version"
438           Increment a version's version component.
439
440   Formatting
441       "normal"
442           Return a normalised representation of a version.
443
444               my $version = Perl::Version->new( '5.008007_01' );
445               print $version->normal, "\n";
446
447           prints
448
449               v5.8.7_001
450
451       "numify"
452           Return a numeric representation of a version. The numeric form is
453           most frequently used for versions of Perl itself.
454
455               my $version = Perl::Version->new( '5.8.7_1' );
456               print $version->normal, "\n";
457
458           prints
459
460               5.008007_001
461
462       "stringify"
463           Return the version formatted as closely as possible to the version
464           from which it was initialised.
465
466               my $version = Perl::Version->new( '5.008007_01' );
467               $version->inc_alpha;
468               print $version->stringify, "\n";
469
470           prints
471
472               5.008007_02
473
474           and
475
476               my $version = Perl::Version->new( '5.8.7_1' );
477               $version->inc_alpha;
478               print $version->stringify, "\n";
479
480           prints
481
482               5.8.7_2
483
484   Comparison
485       "vcmp"
486           Perform 'spaceship' comparison between two version and return -1, 0
487           or 1 depending on their ordering. Comparisons are semantically
488           correct so that
489
490               my $v1 = Perl::Version->new( '1.002001' );
491               my $v2 = Perl::Version->new( '1.1.3' );
492
493               print ($v1->vcmp( $v2 ) > 0 ? 'yes' : 'no'), "\n";
494
495           prints
496
497               yes
498
499   Overloaded Operators
500       "<=>" and "cmp"
501           The "<=>" and "cmp" operators are overloaded (by the vcmp method)
502           so that comparisions between versions work as expected. This means
503           that the other numeric and string comparison operators also work as
504           expected.
505
506               my $v1 = Perl::Version->new( '1.002001' );
507               my $v2 = Perl::Version->new( '1.1.3' );
508
509               print "OK!\n" if $v1 > $v2;
510
511           prints
512
513               OK!
514
515       "" (stringification)
516           Perl::Version objects are converted to strings by calling the
517           stringify method. This usually results in formatting close to that
518           of the original version string.
519
520   Constants
521       "REGEX"
522           An unanchored regular expression that matches any of the version
523           formats supported by Perl::Version. Three captures get the prefix
524           part, the main body of the version and any alpha suffix
525           respectively.
526
527               my $version = 'v1.2.3.4_5';
528               my ($prefix, $main, $suffix) = ($version =~ Perl::Version::REGEX);
529               print "$prefix\n$main\n$suffix\n";
530
531           prints
532
533               v
534               1.2.3.4
535               _5
536
537       "MATCH"
538           An anchored regular expression that matches a correctly formatted
539           version string. Five captures get any leading whitespace, the
540           prefix part, the main body of the version, any alpha suffix and any
541           trailing spaces respectively.
542
543               my $version = '  v1.2.3.4_5  ';
544               my ($before, $prefix, $main, $suffix, $after)
545                            = ($version =~ Perl::Version::MATCH);
546               print "|$before|$prefix|$main|$suffix|$after|\n";
547
548           prints
549
550               | |v|1.2.3.4|_5| |
551

DIAGNOSTICS

553   Error messages
554       "Illegal version string: %s"
555           The version string supplied to "new" can't be parsed as a valid
556           version. Valid versions match this regex:
557
558               qr/ ( (?i: Revision: \s+ ) | v | )
559                     ( \d+ (?: [.] \d+)* )
560                     ( (?: _ \d+ )? ) /x;
561
562       "new must be called as a class or object method"
563           "new" can't be called as a normal subroutine. Use
564
565               $version_object->new( '1.2.3' );
566
567           or
568
569               Perl::Version->new( '1.2.3' );
570
571           instead of
572
573               Perl::Version::new( '1.2.3' );
574
575       "Unknown component name: %s"
576           You've attempted to access a component by name using a name that
577           isn't recognised. Valid component names are 'revision', 'version',
578           'subversion' and 'alpha'. Case is not significant.
579
580       "Can't compare with %s"
581           You've tried to compare a Perl::Version with something other than a
582           version string, a number or another Perl::Version.
583
584       "Can't set the number of components to 0"
585           Versions must have at least one component.
586
587       "You must specify a component number"
588           You've called component or increment without specifying the number
589           (or name) of the component to access.
590
591       "Component %s is out of range 0..%s"
592           You've attempted to increment a component of a version but you've
593           specified a component that doesn't exist within the version:
594
595               # Fails
596               my $version = Perl::Version->new( '1.4' );
597               $version->increment( 2 );
598
599           Slightly confusingly you'll see this message even if you specified
600           the component number implicitly by using one of the named
601           convenience accessors.
602

CONFIGURATION AND ENVIRONMENT

604       Perl::Version requires no configuration files or environment variables.
605

DEPENDENCIES

607       No non-core modules.
608

INCOMPATIBILITIES

610       None reported.
611

BUGS AND LIMITATIONS

613       No bugs have been reported.
614
615       Please report any bugs or feature requests to
616       "bug-perl-version@rt.cpan.org", or through the web interface at
617       <http://rt.cpan.org>.
618

AUTHOR

620       Andy Armstrong "<andy@hexten.net>"
621
622       Hans Dieter Pearcey "<hdp@cpan.org>"
623

LICENCE AND COPYRIGHT

625       Copyright (c) 2007, Andy Armstrong "<andy@hexten.net>". All rights
626       reserved.
627
628       This module is free software; you can redistribute it and/or modify it
629       under the same terms as Perl itself. See perlartistic.
630

DISCLAIMER OF WARRANTY

632       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
633       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
634       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
635       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
636       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
637       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
638       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
639       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
640       NECESSARY SERVICING, REPAIR, OR CORRECTION.
641
642       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
643       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
644       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
645       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
646       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
647       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
648       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
649       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
650       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
651       DAMAGES.
652
653
654
655perl v5.12.0                      2009-03-07                  Perl::Version(3)