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