lib/version.pod

   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 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
  17
  18   # Declaring an old-style decimal $VERSION (use quotes!)
  19
  20   use version 0.77; our $VERSION = version->parse("1.0203");   # formal
  21   use version 0.77; our $VERSION = version->parse("1.02_03");  # alpha
  22
  23   # Comparing mixed version styles (decimals, dotted-decimals, objects)
  24
  25   if ( version->parse($v1) == version->parse($v2) ) {
  26     # do stuff
  27   }
  28
  29   # Sorting mixed version styles
  30
  31   @ordered = sort { version->parse($a) <=> version->parse($b) } @list;
  32
  33 =head1 DESCRIPTION
  34
  35 Version objects were added to Perl in 5.10.  This module implements version
  36 objects for older version of Perl and provides the version object API for all
  37 versions of Perl.  All previous releases before 0.74 are deprecated and should
  38 not be used due to incompatible API changes.  Version 0.77 introduces the new
  39 'parse' and 'declare' methods to standardize usage.  You are strongly urged to
  40 set 0.77 as a minimum in your code, e.g.
  41
  42   use version 0.77; # even for Perl v.5.10.0
  43
  44 =head1 TYPES OF VERSION OBJECTS
  45
  46 There are two different types of version objects, corresponding to the two
  47 different styles of versions in use:
  48
  49 =over 2
  50
  51 =item Decimal Versions
  52
  53 The classic floating-point number $VERSION.  The advantage to this style is
  54 that you don't need to do anything special, just type a number (without
  55 quotes) into your source file.
  56
  57 =item Dotted Decimal Versions
  58
  59 The more modern form of version assignment, with 3 (or potentially more)
  60 integers seperated by decimal points (e.g. v1.2.3).  This is the form that
  61 Perl itself has used since 5.6.0 was released.  The leading "v" is now
  62 strongly recommended for clarity, and will throw a warning in a future
  63 release if omitted.
  64
  65 =back
  66
  67 See L<VERSION OBJECT DETAILS> for further information.
  68
  69 =head1 DECLARING VERSIONS
  70
  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:
  74
  75   our $VERSION = 1.02;
  76
  77 Since Perl v5.10.0 includes the version.pm comparison logic anyways,
  78 you don't need to do anything at all.
  79
  80 =head2 How to convert a module from decimal to dotted-decimal
  81
  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
  84 the new format.
  85
  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:
  90
  91   $ perl -Mversion -e 'print version->parse("1.02")->normal'
  92   v1.20.0
  93
  94 Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0).
  95
  96 =head2 How to C<declare()> a dotted-decimal version
  97
  98   use version 0.77; our $VERSION = version->declare("v1.2.3");
  99
 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.
 106
 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:
 110
 111 =over 2
 112
 113 =item *
 114
 115 Always use a dotted-decimal with (at least) three components
 116
 117 =item *
 118
 119 Always use a leading-v
 120
 121 =item *
 122
 123 Always quote the version
 124
 125 =back
 126
 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.
 130
 131 See also L<VERSION OBJECT DETAILS> for more on version number conversion,
 132 quoting, calculated version numbers and declaring developer or "alpha" version
 133 numbers.
 134
 135 =head1 PARSING AND COMPARING VERSIONS
 136
 137 If you need to compare version numbers, but can't be sure whether they are
 138 expressed as numbers, strings, v-strings or version objects,  then you can
 139 use version.pm to parse them all into objects for comparison.
 140
 141 =head2 How to C<parse()> a version
 142
 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.
 145
 146 =over 2
 147
 148 =item *
 149
 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.
 154
 155 =item *
 156
 157 Decimal: regular decimal numbers (literal or in a string)
 158
 159 =back
 160
 161 Some examples:
 162
 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
 171
 172 See L<VERSION OBJECT DETAILS> for more on version number conversion.
 173
 174 =head2 How to check for a version
 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
 178 be parsed as a version, there are now regular expressions included with
 179 the version module and there are two helper functions that can be
 180 employed directly:
 181
 182 =over 2
 183
 184 =item C<is_strict()>
 185
 186 If you want to limit youself to a much more narrow definition of what
 187 a version string constitutes, you can use this function, which limits
 188 legal version strings to the following list:
 189
 190 =over 2
 191
 192 =item v1.234.5
 193
 194 For dotted-decimal versions, requires a leading 'v', three sub-versions
 195 of no more than three digits.  A leading 0 (zero) before the first
 196 sub-version (in the above example, '1') is also prohibited.
 197
 198 =item 2.3456
 199
 200 For standard decimal version, requires an integer portion (no leading
 201 0), a decimal, and one or more digits to the right of the decimal
 202
 203 =back
 204
 205 =item C<is_lax()>
 206
 207 =over 2
 208
 209 =item v1.2
 210 =item 1.2345.6
 211 =item 1.23_4
 212
 213 With the lax criteria, all of the above styles are acceptable for
 214 dotted-decimal formats.  The leading 'v' is optional if two or more
 215 decimals appear.  If only a single decimal is included, then the leading
 216 'v' is required to trigger the dotted-decimal parsing.  A leading zero
 217 is permitted, though not recommended except when quoted, because of the
 218 risk that Perl will treat the number as octal.  A trailing underscore
 219 plus one or more digits denotes an alpha or development release
 220 (and must be quoted to be parsed properly).
 221
 222 =item 1.2345
 223 =item 1.2345_01
 224
 225 For decimal versions, the lax form is nearly identical to the strict
 226 form except that the alpha form is allowed and a leading zero is
 227 permitted.  Just like the lax dotted-decimal version, quoting the
 228 values is required for alpha/development forms to be parsed correctly.
 229
 230 =back
 231
 232 See L<version::Internal> for details of the regular expressions used,
 233 as well as how to use the regular expressions in your own code.
 234
 235 =back
 236
 237 =head2 How to compare version objects
 238
 239 Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators.  Perl
 240 automatically generates all of the other comparison operators based on those
 241 two so all the normal logical comparisons will work.
 242
 243   if ( version->parse($v1) == version->parse($v2) ) {
 244     # do stuff
 245   }
 246
 247 If a version object is compared against a non-version object, the non-object
 248 term will be converted to a version object using C<parse()>.  This may give
 249 surprising results:
 250
 251   $v1 = version->parse("v0.95.0");
 252   $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0
 253
 254 Always comparing to a version object will help avoid surprises:
 255
 256   $bool = $v1 < version->parse("v0.96.0"); # TRUE
 257
 258 =head1 VERSION OBJECT DETAILS
 259
 260 =head2 Equivalence between Decimal and Dotted-Decimal Versions
 261
 262 When Perl 5.6.0 was released, the decision was made to provide a
 263 transformation between the old-style decimal versions and new-style
 264 dotted-decimal versions:
 265
 266   5.6.0    == 5.006000
 267   5.005_04 == 5.5.40
 268
 269 The floating point number is taken and split first on the single decimal
 270 place, then each group of three digits to the right of the decimal makes up
 271 the next digit, and so on until the number of significant digits is exhausted,
 272 B<plus> enough trailing zeros to reach the next multiple of three.
 273
 274 This was the method that version.pm adopted as well.  Some examples may be
 275 helpful:
 276
 277                             equivalent
 278   decimal    zero-padded    dotted-decimal
 279   -------    -----------    --------------
 280   1.2        1.200          v1.200.0
 281   1.02       1.020          v1.20.0
 282   1.002      1.002          v1.2.0
 283   1.0023     1.002300       v1.2.300
 284   1.00203    1.002030       v1.2.30
 285   1.002003   1.002003       v1.2.3
 286
 287 =head2 Quoting rules
 288
 289 Because of the nature of the Perl parsing and tokenizing routines,
 290 certain initialization values B<must> be quoted in order to correctly
 291 parse as the intended version, especially when using the L<declare> or
 292 L<qv> methods.  While you do not have to quote decimal numbers when
 293 creating version objects, it is always safe to quote B<all> initial values
 294 when using version.pm methods, as this will ensure that what you type is
 295 what is used.
 296
 297 Additionally, if you quote your initializer, then the quoted value that goes
 298 B<in> will be be exactly what comes B<out> when your $VERSION is printed
 299 (stringified).  If you do not quote your value, Perl's normal numeric handling
 300 comes into play and you may not get back what you were expecting.
 301
 302 If you use a mathematic formula that resolves to a floating point number,
 303 you are dependent on Perl's conversion routines to yield the version you
 304 expect.  You are pretty safe by dividing by a power of 10, for example,
 305 but other operations are not likely to be what you intend.  For example:
 306
 307   $VERSION = version->new((qw$Revision: 1.4)[1]/10);
 308   print $VERSION;          # yields 0.14
 309   $V2 = version->new(100/9); # Integer overflow in decimal number
 310   print $V2;               # yields something like 11.111.111.100
 311
 312 Perl 5.8.1 and beyond are able to automatically quote v-strings but
 313 that is not possible in earlier versions of Perl.  In other words:
 314
 315   $version = version->new("v2.5.4");  # legal in all versions of Perl
 316   $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
 317
 318 =head2 What about v-strings?
 319
 320 There are two ways to enter v-strings: a bare number with two or more
 321 decimal points, or a bare number with one or more decimal points and a
 322 leading 'v' character (also bare).  For example:
 323
 324   $vs1 = 1.2.3; # encoded as \1\2\3
 325   $vs2 = v1.2;  # encoded as \1\2
 326
 327 However, the use of bare v-strings to initialize version objects is
 328 B<strongly> discouraged in all circumstances.  Also, bare
 329 v-strings are not completely supported in any version of Perl prior to
 330 5.8.1.
 331
 332 If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
 333 following limitations:
 334
 335 1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses,
 336 based on some characteristics of v-strings.  You B<must> use a three part
 337 version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
 338
 339 2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
 340 core to be magical, which means that the version.pm code can automatically
 341 determine whether the v-string encoding was used.
 342
 343 3) In all cases, a version created using v-strings will have a stringified
 344 form that has a leading 'v' character, for the simple reason that sometimes
 345 it is impossible to tell whether one was present initially.
 346
 347 =head2 Alpha versions
 348
 349 For module authors using CPAN, the convention has been to note unstable
 350 releases with an underscore in the version string. (See L<CPAN>.)  version.pm
 351 follows this convention and alpha releases will test as being newer than the
 352 more recent stable release, and less than the next stable release.  For
 353 dotted-decimal versions, only the last element may be separated by an
 354 underscore:
 355
 356   # Declaring
 357   use version 0.77; our $VERSION = version->declare("v1.2_3");
 358
 359   # Parsing
 360   $v1 = version->parse("v1.2_3");
 361   $v1 = version->parse("1.002_003");
 362
 363 =head1 OBJECT METHODS
 364
 365 =head2 is_alpha()
 366
 367 True if and only if the version object was created with a underscore, e.g.
 368
 369   version->parse('1.002_03')->is_alpha;  # TRUE
 370   version->declare('1.2.3_4')->is_alpha; # TRUE
 371
 372 =head2 is_qv()
 373
 374 True only if the version object is a dotted-decimal version, e.g.
 375
 376   version->parse('v1.2.0')->is_qv;        # TRUE
 377   version->declare('v1.2')->is_qv;       # TRUE
 378   qv('1.2')->is_qv;                      # TRUE
 379   version->parse('1.2')->is_qv;          # FALSE
 380
 381 =head2 normal()
 382
 383 Returns a string with a standard 'normalized' dotted-decimal form with a
 384 leading-v and at least 3 components.
 385
 386  version->declare('v1.2')->normal;  # v1.2.0
 387  version->parse('1.2')->normal;     # v1.200.0
 388
 389 =head2 numify()
 390
 391 Returns a value representing the object in a pure decimal form without
 392 trailing zeroes.
 393
 394  version->declare('v1.2')->numify;  # 1.002
 395  version->parse('1.2')->numify;     # 1.2
 396
 397 =head2 stringify()
 398
 399 Returns a string that is as close to the original representation as possible.
 400 If the original representation was a numeric literal, it will be returned the
 401 way perl would normally represent it in a string.  This method is used whenever
 402 a version object is interpolated into a string.
 403
 404  version->declare('v1.2')->stringify;    # v1.2
 405  version->parse('1.200')->stringify;     # 1.200
 406  version->parse(1.02_30)->stringify;     # 1.023
 407
 408 =head1 EXPORTED FUNCTIONS
 409
 410 =head2 qv()
 411
 412 This function is no longer recommended for use, but is maintained for
 413 compatibility with existing code.  If you do not want to have it exported
 414 to your namespace, use this form:
 415
 416   use version 0.77 ();
 417
 418 =head1 AUTHOR
 419
 420 John Peacock E<lt>jpeacock@cpan.orgE<gt>
 421
 422 =head1 SEE ALSO
 423
 424 L<version::Internal>.
 425
 426 L<perl>.
 427
 428 =cut