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 compare version objects
 175
 176 Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators.  Perl
 177 automatically generates all of the other comparison operators based on those
 178 two so all the normal logical comparisons will work.
 179
 180   if ( version->parse($v1) == version->parse($v2) ) {
 181     # do stuff
 182   }
 183
 184 If a version object is compared against a non-version object, the non-object
 185 term will be converted to a version object using C<parse()>.  This may give
 186 surprising results:
 187
 188   $v1 = version->parse("v0.95.0");
 189   $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0
 190
 191 Always comparing to a version object will help avoid surprises:
 192
 193   $bool = $v1 < version->parse("v0.96.0"); # TRUE
 194
 195 =head1 VERSION OBJECT DETAILS
 196
 197 =head2 Equivalence between Decimal and Dotted-Decimal Versions
 198
 199 When Perl 5.6.0 was released, the decision was made to provide a
 200 transformation between the old-style decimal versions and new-style
 201 dotted-decimal versions:
 202
 203   5.6.0    == 5.006000
 204   5.005_04 == 5.5.40
 205
 206 The floating point number is taken and split first on the single decimal
 207 place, then each group of three digits to the right of the decimal makes up
 208 the next digit, and so on until the number of significant digits is exhausted,
 209 B<plus> enough trailing zeros to reach the next multiple of three.
 210
 211 This was the method that version.pm adopted as well.  Some examples may be
 212 helpful:
 213
 214                             equivalent
 215   decimal    zero-padded    dotted-decimal
 216   -------    -----------    --------------
 217   1.2        1.200          v1.200.0
 218   1.02       1.020          v1.20.0
 219   1.002      1.002          v1.2.0
 220   1.0023     1.002300       v1.2.300
 221   1.00203    1.002030       v1.2.30
 222   1.002003   1.002003       v1.2.3
 223
 224 =head2 Quoting rules
 225
 226 Because of the nature of the Perl parsing and tokenizing routines,
 227 certain initialization values B<must> be quoted in order to correctly
 228 parse as the intended version, especially when using the L<declare> or
 229 L<qv> methods.  While you do not have to quote decimal numbers when
 230 creating version objects, it is always safe to quote B<all> initial values
 231 when using version.pm methods, as this will ensure that what you type is
 232 what is used.
 233
 234 Additionally, if you quote your initializer, then the quoted value that goes
 235 B<in> will be be exactly what comes B<out> when your $VERSION is printed
 236 (stringified).  If you do not quote your value, Perl's normal numeric handling
 237 comes into play and you may not get back what you were expecting.
 238
 239 If you use a mathematic formula that resolves to a floating point number,
 240 you are dependent on Perl's conversion routines to yield the version you
 241 expect.  You are pretty safe by dividing by a power of 10, for example,
 242 but other operations are not likely to be what you intend.  For example:
 243
 244   $VERSION = version->new((qw$Revision: 1.4)[1]/10);
 245   print $VERSION;          # yields 0.14
 246   $V2 = version->new(100/9); # Integer overflow in decimal number
 247   print $V2;               # yields something like 11.111.111.100
 248
 249 Perl 5.8.1 and beyond are able to automatically quote v-strings but
 250 that is not possible in earlier versions of Perl.  In other words:
 251
 252   $version = version->new("v2.5.4");  # legal in all versions of Perl
 253   $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
 254
 255 =head2 What about v-strings?
 256
 257 There are two ways to enter v-strings: a bare number with two or more
 258 decimal points, or a bare number with one or more decimal points and a
 259 leading 'v' character (also bare).  For example:
 260
 261   $vs1 = 1.2.3; # encoded as \1\2\3
 262   $vs2 = v1.2;  # encoded as \1\2
 263
 264 However, the use of bare v-strings to initialize version objects is
 265 B<strongly> discouraged in all circumstances.  Also, bare
 266 v-strings are not completely supported in any version of Perl prior to
 267 5.8.1.
 268
 269 If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
 270 following limitations:
 271
 272 1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses,
 273 based on some characteristics of v-strings.  You B<must> use a three part
 274 version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
 275
 276 2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
 277 core to be magical, which means that the version.pm code can automatically
 278 determine whether the v-string encoding was used.
 279
 280 3) In all cases, a version created using v-strings will have a stringified
 281 form that has a leading 'v' character, for the simple reason that sometimes
 282 it is impossible to tell whether one was present initially.
 283
 284 =head2 Alpha versions
 285
 286 For module authors using CPAN, the convention has been to note unstable
 287 releases with an underscore in the version string. (See L<CPAN>.)  version.pm
 288 follows this convention and alpha releases will test as being newer than the
 289 more recent stable release, and less than the next stable release.  For
 290 dotted-decimal versions, only the last element may be separated by an
 291 underscore:
 292
 293   # Declaring
 294   use version 0.77; our $VERSION = version->declare("v1.2_3");
 295
 296   # Parsing
 297   $v1 = version->parse("v1.2_3");
 298   $v1 = version->parse("1.002_003");
 299
 300 =head1 OBJECT METHODS
 301
 302 =head2 is_alpha()
 303
 304 True if and only if the version object was created with a underscore, e.g.
 305
 306   version->parse('1.002_03')->is_alpha;  # TRUE
 307   version->declare('1.2.3_4')->is_alpha; # TRUE
 308
 309 =head2 is_qv()
 310
 311 True only if the version object is a dotted-decimal version, e.g.
 312
 313   version->parse('v1.2.0')->is_qv;        # TRUE
 314   version->declare('v1.2')->is_qv;       # TRUE
 315   qv('1.2')->is_qv;                      # TRUE
 316   version->parse('1.2')->is_qv;          # FALSE
 317
 318 =head2 normal()
 319
 320 Returns a string with a standard 'normalized' dotted-decimal form with a
 321 leading-v and at least 3 components.
 322
 323  version->declare('v1.2')->normal;  # v1.2.0
 324  version->parse('1.2')->normal;     # v1.200.0
 325
 326 =head2 numify()
 327
 328 Returns a value representing the object in a pure decimal form without
 329 trailing zeroes.
 330
 331  version->declare('v1.2')->numify;  # 1.002
 332  version->parse('1.2')->numify;     # 1.2
 333
 334 =head2 stringify()
 335
 336 Returns a string that is as close to the original representation as possible.
 337 If the original representation was a numeric literal, it will be returned the
 338 way perl would normally represent it in a string.  This method is used whenever
 339 a version object is interpolated into a string.
 340
 341  version->declare('v1.2')->stringify;    # v1.2
 342  version->parse('1.200')->stringify;     # 1.200
 343  version->parse(1.02_30)->stringify;     # 1.023
 344
 345 =head1 EXPORTED FUNCTIONS
 346
 347 =head2 qv()
 348
 349 This function is no longer recommended for use, but is maintained for
 350 compatibility with existing code.  If you do not want to have it exported
 351 to your namespace, use this form:
 352
 353   use version 0.77 ();
 354
 355 =head1 AUTHOR
 356
 357 John Peacock E<lt>jpeacock@cpan.orgE<gt>
 358
 359 =head1 SEE ALSO
 360
 361 L<version::Internal>.
 362
 363 L<perl>.
 364
 365 =cut