1version(3pm) Perl Programmers Reference Guide version(3pm)
2
6 version - Perl extension for Version Objects
7
9 # Parsing version strings (decimal or dotted-decimal)
10 use version 0.77; # get latest bug-fixes and API
12 $ver = version->parse($string)
13 # Declaring a dotted-decimal $VERSION (keep on one line!)
15 use version 0.77; our $VERSION = version->declare("v1.2.3"); # formal
17 use version 0.77; our $VERSION = qv("v1.2.3"); # shorthand
18 use version 0.77; our $VERSION = qv("v1.2_3"); # alpha
19 # Declaring an old-style decimal $VERSION (use quotes!)
21 use version 0.77; our $VERSION = version->parse("1.0203"); # formal
23 use version 0.77; our $VERSION = version->parse("1.02_03"); # alpha
24 # Comparing mixed version styles (decimals, dotted-decimals, objects)
26 if ( version->parse($v1) == version->parse($v2) ) {
28 # do stuff
29 }
30 # Sorting mixed version styles
32 @ordered = sort { version->parse($a) <=> version->parse($b) } @list;
34
36 Version objects were added to Perl in 5.10. This module implements
37 version objects for older version of Perl and provides the version
38 object API for all versions of Perl. All previous releases before 0.74
39 are deprecated and should not be used due to incompatible API changes.
40 Version 0.77 introduces the new 'parse' and 'declare' methods to
41 standardize usage. You are strongly urged to set 0.77 as a minimum in
42 your code, e.g.
43 use version 0.77; # even for Perl v.5.10.0
45
47 There are two different types of version objects, corresponding to the
48 two different styles of versions in use:
49 Decimal Versions
51 The classic floating-point number $VERSION. The advantage to this
52 style is that you don't need to do anything special, just type a
53 number (without quotes) into your source file.
54 Dotted Decimal Versions
56 The more modern form of version assignment, with 3 (or potentially
57 more) integers seperated by decimal points (e.g. v1.2.3). This is
58 the form that Perl itself has used since 5.6.0 was released. The
59 leading "v" is now strongly recommended for clarity, and will throw a
60 warning in a future release if omitted.
61 See "VERSION OBJECT DETAILS" for further information.
63
65 If you have a module that uses a decimal $VERSION (floating point), and
66 you do not intend to ever change that, this module is not for you.
67 There is nothing that version.pm gains you over a simple $VERSION
68 assignment:
69 our $VERSION = 1.02;
71 Since Perl v5.10.0 includes the version.pm comparison logic anyways,
73 you don't need to do anything at all.
74 How to convert a module from decimal to dotted-decimal
76 If you have used a decimal $VERSION in the past and wish to switch to a
77 dotted-decimal $VERSION, then you need to make a one-time conversion to
78 the new format.
79 Important Note: you must ensure that your new $VERSION is numerically
81 greater than your current decimal $VERSION; this is not always obvious.
82 First, convert your old decimal version (e.g. 1.02) to a normalized
83 dotted-decimal form:
84 $ perl -Mversion -e 'print version->parse("1.02")->normal'
86 v1.20.0
87 Then increment any of the dotted-decimal components (v1.20.1 or
89 v1.21.0).
90 How to "declare()" a dotted-decimal version
92 use version 0.77; our $VERSION = version->declare("v1.2.3");
93 The "declare()" method always creates dotted-decimal version objects.
95 When used in a module, you must put it on the same line as "use
96 version" to ensure that $VERSION is read correctly by PAUSE and
97 installer tools. You should also add 'version' to the
98 'configure_requires' section of your module metadata file. See
99 instructions in ExtUtils::MakeMaker or Module::Build for details.
100 Important Note: Even if you pass in what looks like a decimal number
102 ("1.2"), a dotted-decimal will be created ("v1.200.0"). To avoid
103 confusion or unintentional errors on older Perls, follow these
104 guidelines:
105 · Always use a dotted-decimal with (at least) three components
107 · Always use a leading-v
109 · Always quote the version
111 If you really insist on using version.pm with an ordinary decimal
113 version, use "parse()" instead of declare. See the "PARSING AND
114 COMPARING VERSIONS" for details.
115 See also "VERSION OBJECT DETAILS" for more on version number
117 conversion, quoting, calculated version numbers and declaring developer
118 or "alpha" version numbers.
119
121 If you need to compare version numbers, but can't be sure whether they
122 are expressed as numbers, strings, v-strings or version objects, then
123 you can use version.pm to parse them all into objects for comparison.
124 How to "parse()" a version
126 The "parse()" method takes in anything that might be a version and
127 returns a corresponding version object, doing any necessary conversion
128 along the way.
129 · Dotted-decimal: bare v-strings (v1.2.3) and strings with more than
131 one decimal point and a leading 'v' ("v1.2.3"); NOTE you can
132 technically use a v-string or strings with a leading-v and only one
133 decimal point (v1.2 or "v1.2"), but you will confuse both yourself
134 and others.
135 · Decimal: regular decimal numbers (literal or in a string)
137 Some examples:
139 $variable version->parse($variable)
141 --------- -------------------------
142 1.23 v1.230.0
143 "1.23" v1.230.0
144 v1.23 v1.23.0
145 "v1.23" v1.23.0
146 "1.2.3" v1.2.3
147 "v1.2.3" v1.2.3
148 See "VERSION OBJECT DETAILS" for more on version number conversion.
150 How to compare version objects
152 Version objects overload the "cmp" and "E<lt>=E<gt>" operators. Perl
153 automatically generates all of the other comparison operators based on
154 those two so all the normal logical comparisons will work.
155 if ( version->parse($v1) == version->parse($v2) ) {
157 # do stuff
158 }
159 If a version object is compared against a non-version object, the non-
161 object term will be converted to a version object using "parse()".
162 This may give surprising results:
163 $v1 = version->parse("v0.95.0");
165 $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0
166 Always comparing to a version object will help avoid surprises:
168 $bool = $v1 < version->parse("v0.96.0"); # TRUE
170
172 Equivalence between Decimal and Dotted-Decimal Versions
173 When Perl 5.6.0 was released, the decision was made to provide a
174 transformation between the old-style decimal versions and new-style
175 dotted-decimal versions:
176 5.6.0 == 5.006000
178 5.005_04 == 5.5.40
179 The floating point number is taken and split first on the single
181 decimal place, then each group of three digits to the right of the
182 decimal makes up the next digit, and so on until the number of
183 significant digits is exhausted, plus enough trailing zeros to reach
184 the next multiple of three.
185 This was the method that version.pm adopted as well. Some examples may
187 be helpful:
188 equivalent
190 decimal zero-padded dotted-decimal
191 ------- ----------- --------------
192 1.2 1.200 v1.200.0
193 1.02 1.020 v1.20.0
194 1.002 1.002 v1.2.0
195 1.0023 1.002300 v1.2.300
196 1.00203 1.002030 v1.2.30
197 1.002003 1.002003 v1.2.3
198 Quoting rules
200 Because of the nature of the Perl parsing and tokenizing routines,
201 certain initialization values must be quoted in order to correctly
202 parse as the intended version, especially when using the declare or qv
203 methods. While you do not have to quote decimal numbers when creating
204 version objects, it is always safe to quote all initial values when
205 using version.pm methods, as this will ensure that what you type is
206 what is used.
207 Additionally, if you quote your initializer, then the quoted value that
209 goes in will be be exactly what comes out when your $VERSION is printed
210 (stringified). If you do not quote your value, Perl's normal numeric
211 handling comes into play and you may not get back what you were
212 expecting.
213 If you use a mathematic formula that resolves to a floating point
215 number, you are dependent on Perl's conversion routines to yield the
216 version you expect. You are pretty safe by dividing by a power of 10,
217 for example, but other operations are not likely to be what you intend.
218 For example:
219 $VERSION = version->new((qw$Revision: 1.4)[1]/10);
221 print $VERSION; # yields 0.14
222 $V2 = version->new(100/9); # Integer overflow in decimal number
223 print $V2; # yields something like 11.111.111.100
224 Perl 5.8.1 and beyond are able to automatically quote v-strings but
226 that is not possible in earlier versions of Perl. In other words:
227 $version = version->new("v2.5.4"); # legal in all versions of Perl
229 $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
230 What about v-strings?
232 There are two ways to enter v-strings: a bare number with two or more
233 decimal points, or a bare number with one or more decimal points and a
234 leading 'v' character (also bare). For example:
235 $vs1 = 1.2.3; # encoded as \1\2\3
237 $vs2 = v1.2; # encoded as \1\2
238 However, the use of bare v-strings to initialize version objects is
240 strongly discouraged in all circumstances. Also, bare v-strings are
241 not completely supported in any version of Perl prior to 5.8.1.
242 If you insist on using bare v-strings with Perl > 5.6.0, be aware of
244 the following limitations:
245 1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely
247 guesses, based on some characteristics of v-strings. You must use a
248 three part version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to
249 be successful.
250 2) For Perl releases 5.8.1 and later, v-strings have changed in the
252 Perl core to be magical, which means that the version.pm code can
253 automatically determine whether the v-string encoding was used.
254 3) In all cases, a version created using v-strings will have a
256 stringified form that has a leading 'v' character, for the simple
257 reason that sometimes it is impossible to tell whether one was present
258 initially.
259 Alpha versions
261 For module authors using CPAN, the convention has been to note unstable
262 releases with an underscore in the version string. (See CPAN.)
263 version.pm follows this convention and alpha releases will test as
264 being newer than the more recent stable release, and less than the next
265 stable release. For dotted-decimal versions, only the last element may
266 be separated by an underscore:
267 # Declaring
269 use version 0.77; our $VERSION = version->declare("v1.2_3");
270 # Parsing
272 $v1 = version->parse("v1.2_3");
273 $v1 = version->parse("1.002_003");
274
276 is_alpha()
277 True if and only if the version object was created with a underscore,
278 e.g.
279 version->parse('1.002_03')->is_alpha; # TRUE
281 version->declare('1.2.3_4')->is_alpha; # TRUE
282 is_qv()
284 True only if the version object is a dotted-decimal version, e.g.
285 version->parse('v1.2.0')->is_qv; # TRUE
287 version->declare('v1.2')->is_qv; # TRUE
288 qv('1.2')->is_qv; # TRUE
289 version->parse('1.2')->is_qv; # FALSE
290 normal()
292 Returns a string with a standard 'normalized' dotted-decimal form with
293 a leading-v and at least 3 components.
294 version->declare('v1.2')->normal; # v1.2.0
296 version->parse('1.2')->normal; # v1.200.0
297 numify()
299 Returns a value representing the object in a pure decimal form without
300 trailing zeroes.
301 version->declare('v1.2')->numify; # 1.002
303 version->parse('1.2')->numify; # 1.2
304 stringify()
306 Returns a string that is as close to the original representation as
307 possible. If the original representation was a numeric literal, it
308 will be returned the way perl would normally represent it in a string.
309 This method is used whenever a version object is interpolated into a
310 string.
311 version->declare('v1.2')->stringify; # v1.2
313 version->parse('1.200')->stringify; # 1.200
314 version->parse(1.02_30)->stringify; # 1.023
315
317 qv()
318 This function is no longer recommended for use, but is maintained for
319 compatibility with existing code. If you do not want to have it
320 exported to your namespace, use this form:
321 use version 0.77 ();
323
325 John Peacock <jpeacock@cpan.org>
326
328 version::Internal.
329 perl.
331perl v5.10.1 2009-07-27 version(3pm)