Commit | Line | Data |
---|---|---|
cb5772bb RGS |
1 | =head1 NAME |
2 | ||
3 | version - Perl extension for Version Objects | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
692a467c | 7 | # Parsing version strings (decimal or dotted-decimal) |
cb5772bb | 8 | |
692a467c JP |
9 | use version 0.77; # get latest bug-fixes and API |
10 | $ver = version->parse($string) | |
cb5772bb | 11 | |
692a467c | 12 | # Declaring a dotted-decimal $VERSION (keep on one line!) |
cb5772bb | 13 | |
692a467c JP |
14 | use version 0.77; our $VERSION = version->declare("v1.2.3"); # formal |
15 | use version 0.77; our $VERSION = qv("v1.2.3"); # shorthand | |
16 | use version 0.77; our $VERSION = qv("v1.2_3"); # alpha | |
317f7c8a | 17 | |
692a467c | 18 | # Declaring an old-style decimal $VERSION (use quotes!) |
317f7c8a | 19 | |
6369c739 | 20 | our $VERSION = "1.0203"; # recommended |
692a467c JP |
21 | use version 0.77; our $VERSION = version->parse("1.0203"); # formal |
22 | use version 0.77; our $VERSION = version->parse("1.02_03"); # alpha | |
317f7c8a | 23 | |
692a467c | 24 | # Comparing mixed version styles (decimals, dotted-decimals, objects) |
317f7c8a | 25 | |
692a467c JP |
26 | if ( version->parse($v1) == version->parse($v2) ) { |
27 | # do stuff | |
28 | } | |
317f7c8a | 29 | |
692a467c | 30 | # Sorting mixed version styles |
317f7c8a | 31 | |
692a467c | 32 | @ordered = sort { version->parse($a) <=> version->parse($b) } @list; |
317f7c8a | 33 | |
692a467c | 34 | =head1 DESCRIPTION |
317f7c8a | 35 | |
692a467c JP |
36 | Version objects were added to Perl in 5.10. This module implements version |
37 | objects for older version of Perl and provides the version object API for all | |
38 | versions of Perl. All previous releases before 0.74 are deprecated and should | |
39 | not be used due to incompatible API changes. Version 0.77 introduces the new | |
40 | 'parse' and 'declare' methods to standardize usage. You are strongly urged to | |
61a0cb1c | 41 | set 0.77 as a minimum in your code, e.g. |
317f7c8a | 42 | |
692a467c | 43 | use version 0.77; # even for Perl v.5.10.0 |
cb5772bb | 44 | |
692a467c | 45 | =head1 TYPES OF VERSION OBJECTS |
cb5772bb | 46 | |
692a467c JP |
47 | There are two different types of version objects, corresponding to the two |
48 | different styles of versions in use: | |
cb5772bb | 49 | |
692a467c | 50 | =over 2 |
cb5772bb | 51 | |
692a467c | 52 | =item Decimal Versions |
cb5772bb | 53 | |
692a467c | 54 | The classic floating-point number $VERSION. The advantage to this style is |
6369c739 DG |
55 | that you don't need to do anything special, just type a number into your |
56 | source file. Quoting is recommended, as it ensures that trailing zeroes | |
57 | ("1.50") are preserved in any warnings or other output. | |
cb5772bb | 58 | |
692a467c | 59 | =item Dotted Decimal Versions |
cb5772bb | 60 | |
692a467c | 61 | The more modern form of version assignment, with 3 (or potentially more) |
a8fb8d79 | 62 | integers separated by decimal points (e.g. v1.2.3). This is the form that |
61a0cb1c | 63 | Perl itself has used since 5.6.0 was released. The leading "v" is now |
692a467c JP |
64 | strongly recommended for clarity, and will throw a warning in a future |
65 | release if omitted. | |
cb5772bb RGS |
66 | |
67 | =back | |
68 | ||
692a467c | 69 | =head1 DECLARING VERSIONS |
43eaf59d | 70 | |
692a467c JP |
71 | If you have a module that uses a decimal $VERSION (floating point), and you |
72 | do not intend to ever change that, this module is not for you. There is | |
73 | nothing that version.pm gains you over a simple $VERSION assignment: | |
cb5772bb | 74 | |
6369c739 | 75 | our $VERSION = "1.02"; |
cb5772bb | 76 | |
61a0cb1c | 77 | Since Perl v5.10.0 includes the version.pm comparison logic anyways, |
692a467c | 78 | you don't need to do anything at all. |
cb5772bb | 79 | |
692a467c | 80 | =head2 How to convert a module from decimal to dotted-decimal |
cb5772bb | 81 | |
692a467c JP |
82 | If you have used a decimal $VERSION in the past and wish to switch to a |
83 | dotted-decimal $VERSION, then you need to make a one-time conversion to | |
61a0cb1c | 84 | the new format. |
cb5772bb | 85 | |
692a467c JP |
86 | B<Important Note>: you must ensure that your new $VERSION is numerically |
87 | greater than your current decimal $VERSION; this is not always obvious. First, | |
88 | convert your old decimal version (e.g. 1.02) to a normalized dotted-decimal | |
89 | form: | |
cb5772bb | 90 | |
692a467c JP |
91 | $ perl -Mversion -e 'print version->parse("1.02")->normal' |
92 | v1.20.0 | |
cb5772bb | 93 | |
692a467c | 94 | Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0). |
cb5772bb | 95 | |
692a467c | 96 | =head2 How to C<declare()> a dotted-decimal version |
cb5772bb | 97 | |
692a467c | 98 | use version 0.77; our $VERSION = version->declare("v1.2.3"); |
cb5772bb | 99 | |
692a467c JP |
100 | The C<declare()> method always creates dotted-decimal version objects. When |
101 | used in a module, you B<must> put it on the same line as "use version" to | |
102 | ensure that $VERSION is read correctly by PAUSE and installer tools. You | |
103 | should also add 'version' to the 'configure_requires' section of your | |
104 | module metadata file. See instructions in L<ExtUtils::MakeMaker> or | |
105 | L<Module::Build> for details. | |
cb5772bb | 106 | |
692a467c JP |
107 | B<Important Note>: Even if you pass in what looks like a decimal number |
108 | ("1.2"), a dotted-decimal will be created ("v1.200.0"). To avoid confusion | |
109 | or unintentional errors on older Perls, follow these guidelines: | |
cb5772bb | 110 | |
692a467c | 111 | =over 2 |
cb5772bb | 112 | |
692a467c | 113 | =item * |
cb5772bb | 114 | |
692a467c | 115 | Always use a dotted-decimal with (at least) three components |
92dcf8ce | 116 | |
692a467c | 117 | =item * |
92dcf8ce | 118 | |
692a467c | 119 | Always use a leading-v |
92dcf8ce | 120 | |
692a467c | 121 | =item * |
92dcf8ce | 122 | |
692a467c | 123 | Always quote the version |
92dcf8ce | 124 | |
cb5772bb RGS |
125 | =back |
126 | ||
692a467c JP |
127 | If you really insist on using version.pm with an ordinary decimal version, |
128 | use C<parse()> instead of declare. See the L<PARSING AND COMPARING VERSIONS> | |
129 | for details. | |
cb5772bb | 130 | |
6369c739 | 131 | See also L<version::Internals> for more on version number conversion, |
692a467c JP |
132 | quoting, calculated version numbers and declaring developer or "alpha" version |
133 | numbers. | |
cb5772bb | 134 | |
692a467c | 135 | =head1 PARSING AND COMPARING VERSIONS |
cb5772bb | 136 | |
692a467c | 137 | If you need to compare version numbers, but can't be sure whether they are |
6369c739 | 138 | expressed as numbers, strings, v-strings or version objects, then you should |
692a467c | 139 | use version.pm to parse them all into objects for comparison. |
cb5772bb | 140 | |
692a467c | 141 | =head2 How to C<parse()> a version |
cb5772bb | 142 | |
692a467c JP |
143 | The C<parse()> method takes in anything that might be a version and returns |
144 | a corresponding version object, doing any necessary conversion along the way. | |
cb5772bb | 145 | |
692a467c | 146 | =over 2 |
cb5772bb | 147 | |
692a467c | 148 | =item * |
cb5772bb | 149 | |
692a467c JP |
150 | Dotted-decimal: bare v-strings (v1.2.3) and strings with more than one |
151 | decimal point and a leading 'v' ("v1.2.3"); NOTE you can technically use a | |
152 | v-string or strings with a leading-v and only one decimal point (v1.2 or | |
153 | "v1.2"), but you will confuse both yourself and others. | |
cb5772bb | 154 | |
692a467c | 155 | =item * |
cb5772bb | 156 | |
692a467c | 157 | Decimal: regular decimal numbers (literal or in a string) |
cb5772bb RGS |
158 | |
159 | =back | |
160 | ||
692a467c | 161 | Some examples: |
cb5772bb | 162 | |
692a467c JP |
163 | $variable version->parse($variable) |
164 | --------- ------------------------- | |
165 | 1.23 v1.230.0 | |
166 | "1.23" v1.230.0 | |
167 | v1.23 v1.23.0 | |
168 | "v1.23" v1.23.0 | |
169 | "1.2.3" v1.2.3 | |
170 | "v1.2.3" v1.2.3 | |
cb5772bb | 171 | |
6369c739 | 172 | See L<version::Internals> for more on version number conversion. |
cb5772bb | 173 | |
42bd538f | 174 | =head2 How to check for a legal version string |
61a0cb1c JP |
175 | |
176 | If you do not want to actually create a full blown version object, but | |
177 | would still like to verify that a given string meets the criteria to | |
42bd538f | 178 | be parsed as a version, there are two helper functions that can be |
61a0cb1c JP |
179 | employed directly: |
180 | ||
42bd538f | 181 | =over 4 |
61a0cb1c JP |
182 | |
183 | =item C<is_lax()> | |
184 | ||
6369c739 | 185 | The lax criteria corresponds to what is currently allowed by the |
42bd538f JP |
186 | version parser. All of the following formats are acceptable |
187 | for dotted-decimal formats strings: | |
61a0cb1c | 188 | |
42bd538f JP |
189 | v1.2 |
190 | 1.2345.6 | |
191 | v1.23_4 | |
192 | 1.2345 | |
193 | 1.2345_01 | |
61a0cb1c | 194 | |
42bd538f | 195 | =item C<is_strict()> |
61a0cb1c | 196 | |
42bd538f JP |
197 | If you want to limit youself to a much more narrow definition of what |
198 | a version string constitutes, C<is_strict()> is limited to version | |
199 | strings like the following list: | |
61a0cb1c | 200 | |
42bd538f JP |
201 | v1.234.5 |
202 | 2.3456 | |
61a0cb1c JP |
203 | |
204 | =back | |
205 | ||
42bd538f JP |
206 | See L<version::Internals> for details of the regular expressions |
207 | that define the legal version string forms, as well as how to use | |
6369c739 DG |
208 | those regular expressions in your own code if C<is_lax()> and |
209 | C<is_strict()> are not sufficient for your needs. | |
61a0cb1c | 210 | |
692a467c | 211 | =head2 How to compare version objects |
cb5772bb | 212 | |
a8fb8d79 | 213 | Version objects overload the C<cmp> and C<< <=> >> operators. Perl |
692a467c JP |
214 | automatically generates all of the other comparison operators based on those |
215 | two so all the normal logical comparisons will work. | |
cb5772bb | 216 | |
692a467c JP |
217 | if ( version->parse($v1) == version->parse($v2) ) { |
218 | # do stuff | |
219 | } | |
219bf418 | 220 | |
692a467c JP |
221 | If a version object is compared against a non-version object, the non-object |
222 | term will be converted to a version object using C<parse()>. This may give | |
219bf418 RGS |
223 | surprising results: |
224 | ||
692a467c JP |
225 | $v1 = version->parse("v0.95.0"); |
226 | $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0 | |
219bf418 | 227 | |
692a467c | 228 | Always comparing to a version object will help avoid surprises: |
cb5772bb | 229 | |
692a467c | 230 | $bool = $v1 < version->parse("v0.96.0"); # TRUE |
cb5772bb | 231 | |
6369c739 DG |
232 | Note that "alpha" version objects (where the version string contains |
233 | a trailing underscore segment) compare as less than the equivalent | |
234 | version without an underscore: | |
cb5772bb | 235 | |
6369c739 | 236 | $bool = version->parse("1.23_45") < version->parse("1.2345"); # TRUE |
cb5772bb | 237 | |
6369c739 | 238 | See L<version::Internals> for more details on "alpha" versions. |
cb5772bb | 239 | |
692a467c | 240 | =head1 OBJECT METHODS |
cb5772bb | 241 | |
692a467c | 242 | =head2 is_alpha() |
cb5772bb | 243 | |
692a467c | 244 | True if and only if the version object was created with a underscore, e.g. |
cb5772bb | 245 | |
692a467c JP |
246 | version->parse('1.002_03')->is_alpha; # TRUE |
247 | version->declare('1.2.3_4')->is_alpha; # TRUE | |
cb5772bb | 248 | |
692a467c | 249 | =head2 is_qv() |
cb5772bb | 250 | |
692a467c | 251 | True only if the version object is a dotted-decimal version, e.g. |
cb5772bb | 252 | |
692a467c JP |
253 | version->parse('v1.2.0')->is_qv; # TRUE |
254 | version->declare('v1.2')->is_qv; # TRUE | |
255 | qv('1.2')->is_qv; # TRUE | |
256 | version->parse('1.2')->is_qv; # FALSE | |
cb5772bb | 257 | |
692a467c | 258 | =head2 normal() |
cb5772bb | 259 | |
692a467c JP |
260 | Returns a string with a standard 'normalized' dotted-decimal form with a |
261 | leading-v and at least 3 components. | |
cb5772bb | 262 | |
692a467c JP |
263 | version->declare('v1.2')->normal; # v1.2.0 |
264 | version->parse('1.2')->normal; # v1.200.0 | |
8cb289bd | 265 | |
692a467c | 266 | =head2 numify() |
8cb289bd | 267 | |
692a467c JP |
268 | Returns a value representing the object in a pure decimal form without |
269 | trailing zeroes. | |
cb5772bb | 270 | |
692a467c JP |
271 | version->declare('v1.2')->numify; # 1.002 |
272 | version->parse('1.2')->numify; # 1.2 | |
cb5772bb | 273 | |
692a467c | 274 | =head2 stringify() |
cb5772bb | 275 | |
692a467c JP |
276 | Returns a string that is as close to the original representation as possible. |
277 | If the original representation was a numeric literal, it will be returned the | |
278 | way perl would normally represent it in a string. This method is used whenever | |
279 | a version object is interpolated into a string. | |
cb5772bb | 280 | |
692a467c JP |
281 | version->declare('v1.2')->stringify; # v1.2 |
282 | version->parse('1.200')->stringify; # 1.200 | |
283 | version->parse(1.02_30)->stringify; # 1.023 | |
cb5772bb | 284 | |
692a467c | 285 | =head1 EXPORTED FUNCTIONS |
cb5772bb | 286 | |
692a467c | 287 | =head2 qv() |
cb5772bb | 288 | |
692a467c JP |
289 | This function is no longer recommended for use, but is maintained for |
290 | compatibility with existing code. If you do not want to have it exported | |
291 | to your namespace, use this form: | |
cb5772bb | 292 | |
692a467c | 293 | use version 0.77 (); |
cb5772bb | 294 | |
a525e6d7 DG |
295 | =head2 is_lax() |
296 | ||
297 | (Not exported by default) | |
298 | ||
299 | This function takes a scalar argument and returns a boolean value indicating | |
6369c739 DG |
300 | whether the argument meets the "lax" rules for a version number. Leading and |
301 | trailing spaces are not allowed. | |
a525e6d7 DG |
302 | |
303 | =head2 is_strict() | |
304 | ||
305 | (Not exported by default) | |
306 | ||
307 | This function takes a scalar argument and returns a boolean value indicating | |
6369c739 DG |
308 | whether the argument meets the "strict" rules for a version number. Leading |
309 | and trailing spaces are not allowed. | |
a525e6d7 | 310 | |
cb5772bb RGS |
311 | =head1 AUTHOR |
312 | ||
313 | John Peacock E<lt>jpeacock@cpan.orgE<gt> | |
314 | ||
315 | =head1 SEE ALSO | |
316 | ||
6369c739 | 317 | L<version::Internals>. |
692a467c | 318 | |
cb5772bb RGS |
319 | L<perl>. |
320 | ||
321 | =cut |