[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  version - Perl extension for Version Objects
   4  
   5  =head1 SYNOPSIS
   6  
   7    use version;
   8    $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
   9    print $version;         # v12.2.1
  10    print $version->numify;     # 12.002001
  11    if ( $version gt "12.2" )    # true
  12  
  13    $alphaver = version->new("1.02_03"); # must be quoted!
  14    print $alphaver;        # 1.02_0300
  15    print $alphaver->is_alpha();  # true
  16    
  17    $ver = qv("1.2.0");           # v1.2.0
  18  
  19    $perlver = version->new(5.005_03); # must not be quoted!
  20    print $perlver;        # 5.005030
  21  
  22  =head1 DESCRIPTION
  23  
  24  Overloaded version objects for all modern versions of Perl.  This module
  25  implements all of the features of version objects which will be part
  26  of Perl 5.10.0.
  27  
  28  =head2 BEST PRACTICES
  29  
  30  If you intend for your module to be used by different releases of Perl,
  31  and/or for your $VERSION scalar to mean what you think it means, there 
  32  are a few simple rules to follow:
  33  
  34  =over 4
  35  
  36  =item * Be consistent
  37  
  38  Whichever of the two types of version objects that you choose to employ, 
  39  you should stick to either L<Numeric Versions> or L<Extended Versions>
  40  and not mix them together.  While this is I<possible>, it is very 
  41  confusing to the average user.
  42  
  43  If you intend to use L<Extended Versions>, you are strongly encouraged 
  44  to use the L<qv()> operator with a quoted term, e.g.:
  45  
  46    use version; our $VERSION = qv("1.2.3");
  47  
  48  on a single line as above. 
  49  
  50  At the very least, decide on which of the several ways to initialize 
  51  your version objects you prefer and stick with it.  It is also best to 
  52  be explicit about what value you intend to assign your version object 
  53  and to not rely on hidden behavior of the parser. 
  54  
  55  =item * Be careful
  56  
  57  If you are using Module::Build or ExtUtils::MakeMaker, so that you can
  58  release your module to CPAN, you have to recognize that neither of those
  59  programs completely handles version objects natively (yet).  If you use
  60  version objects with Module::Build, you should add an explicit dependency
  61  to the release of version.pm in your Build.PL:
  62  
  63    my $builder = Module::Build->new(
  64       ...
  65       requires => {
  66           ... ,
  67           'version'    => 0.50,
  68       ...,
  69       },
  70       ...
  71    );
  72  
  73  and it should Just Work(TM).  Module::Build will [hopefully soon] 
  74  include full support for version objects; there are no current plans 
  75  to patch ExtUtils::MakeMaker to support version objects.
  76  
  77  =back
  78  
  79  =head2 Using modules that use version.pm
  80  
  81  As much as possible, the version.pm module remains compatible with all
  82  current code.  However, if your module is using a module that has defined
  83  C<$VERSION> using the version class, there are a couple of things to be
  84  aware of.  For purposes of discussion, we will assume that we have the
  85  following module installed:
  86  
  87    package Example;
  88    use version;  $VERSION = qv('1.2.2');
  89    ...module code here...
  90    1;
  91  
  92  =over 4
  93  
  94  =item Numeric versions always work
  95  
  96  Code of the form:
  97  
  98    use Example 1.002003;
  99  
 100  will always work correctly.  The C<use> will perform an automatic
 101  C<$VERSION> comparison using the floating point number given as the first
 102  term after the module name (e.g. above 1.002.003).  In this case, the
 103  installed module is too old for the requested line, so you would see an
 104  error like:
 105  
 106    Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
 107  
 108  =item Extended version work sometimes
 109  
 110  With Perl >= 5.6.2, you can also use a line like this:
 111  
 112    use Example 1.2.3;
 113  
 114  and it will again work (i.e. give the error message as above), even with
 115  releases of Perl which do not normally support v-strings (see L<What about
 116  v-strings> below).  This has to do with that fact that C<use> only checks
 117  to see if the second term I<looks like a number> and passes that to the
 118  replacement L<UNIVERSAL::VERSION>.  This is not true in Perl 5.005_04,
 119  however, so you are B<strongly encouraged> to always use a numeric version
 120  in your code, even for those versions of Perl which support the extended
 121  version.
 122  
 123  =back
 124  
 125  =head2 What IS a version
 126  
 127  For the purposes of this module, a version "number" is a sequence of
 128  positive integer values separated by one or more decimal points and 
 129  optionally a single underscore.  This corresponds to what Perl itself 
 130  uses for a version, as well as extending the "version as number" that 
 131  is discussed in the various editions of the Camel book.
 132  
 133  There are actually two distinct kinds of version objects:
 134  
 135  =over 4
 136  
 137  =item * Numeric Versions
 138  
 139  Any initial parameter which "looks like a number", see L<Numeric
 140  Versions>.  This also covers versions with a single decimal point and
 141  a single embedded underscore, see L<Numeric Alpha Versions>, even though
 142  these must be quoted to preserve the underscore formatting.
 143  
 144  =item * Extended Versions
 145  
 146  Any initial parameter which contains more than one decimal point
 147  and an optional embedded underscore, see L<Extended Versions>.  This 
 148  is what is commonly used in most open source software as the "external"
 149  version (the one used as part of the tag or tarfile name).  The use
 150  of the exported L<qv()> function also produces this kind of version
 151  object.
 152  
 153  =back
 154  
 155  Both of these methods will produce similar version objects, in that
 156  the default stringification will yield the version L<Normal Form> only 
 157  if required:
 158  
 159    $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
 160    $v  = version->new(1.002003);  # 1.002003
 161    $v2 = version->new("1.2.3");   # v1.2.3
 162  
 163  In specific, version numbers initialized as L<Numeric Versions> will
 164  stringify as they were originally created (i.e. the same string that was
 165  passed to C<new()>.  Version numbers initialized as L<Extended Versions>
 166  will be stringified as L<Normal Form>.
 167  
 168  =head2 Numeric Versions
 169  
 170  These correspond to historical versions of Perl itself prior to 5.6.0,
 171  as well as all other modules which follow the Camel rules for the
 172  $VERSION scalar.  A numeric version is initialized with what looks like
 173  a floating point number.  Leading zeros B<are> significant and trailing
 174  zeros are implied so that a minimum of three places is maintained
 175  between subversions.  What this means is that any subversion (digits
 176  to the right of the decimal place) that contains less than three digits
 177  will have trailing zeros added to make up the difference, but only for
 178  purposes of comparison with other version objects.  For example:
 179  
 180                                     # Prints     Equivalent to  
 181    $v = version->new(      1.2);    # 1.2        v1.200.0
 182    $v = version->new(     1.02);    # 1.02       v1.20.0
 183    $v = version->new(    1.002);    # 1.002      v1.2.0
 184    $v = version->new(   1.0023);    # 1.0023     v1.2.300
 185    $v = version->new(  1.00203);    # 1.00203    v1.2.30
 186    $v = version->new( 1.002003);    # 1.002003   v1.2.3
 187  
 188  All of the preceding examples are true whether or not the input value is 
 189  quoted.  The important feature is that the input value contains only a 
 190  single decimal.  See also L<Alpha Versions> for how to handle 
 191  
 192  IMPORTANT NOTE: As shown above, if your numeric version contains more 
 193  than 3 significant digits after the decimal place, it will be split on 
 194  each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need 
 195  to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.  
 196  Any trailing zeros are ignored for mathematical comparison purposes.
 197  
 198  =head2 Extended Versions
 199  
 200  These are the newest form of versions, and correspond to Perl's own
 201  version style beginning with 5.6.0.  Starting with Perl 5.10.0,
 202  and most likely Perl 6, this is likely to be the preferred form.  This
 203  method normally requires that the input parameter be quoted, although 
 204  Perl's after 5.8.1 can use v-strings as a special form of quoting, but
 205  this is highly discouraged.
 206  
 207  Unlike L<Numeric Versions>, Extended Versions have more than
 208  a single decimal point, e.g.:
 209  
 210                                     # Prints
 211    $v = version->new( "v1.200");    # v1.200.0
 212    $v = version->new("v1.20.0");    # v1.20.0
 213    $v = qv("v1.2.3");               # v1.2.3
 214    $v = qv("1.2.3");                # v1.2.3
 215    $v = qv("1.20");                 # v1.20.0
 216  
 217  In general, Extended Versions permit the greatest amount of freedom
 218  to specify a version, whereas Numeric Versions enforce a certain
 219  uniformity.  See also L<New Operator> for an additional method of
 220  initializing version objects.
 221  
 222  Just like L<Numeric Versions>, Extended Versions can be used as 
 223  L<Alpha Versions>.
 224  
 225  =head2 Numeric Alpha Versions
 226  
 227  The one time that a numeric version must be quoted is when a alpha form is
 228  used with an otherwise numeric version (i.e. a single decimal point).  This
 229  is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
 230  versions for automatic updating purposes.  Since some developers have used
 231  only two significant decimal places for their non-alpha releases, the
 232  version object will automatically take that into account if the initializer
 233  is quoted.  For example Module::Example was released to CPAN with the
 234  following sequence of $VERSION's:
 235  
 236    # $VERSION    Stringified
 237    0.01          0.01
 238    0.02          0.02
 239    0.02_01       0.02_01
 240    0.02_02       0.02_02
 241    0.03          0.03
 242    etc.
 243  
 244  The stringified form of numeric versions will always be the same string
 245  that was used to initialize the version object.
 246  
 247  =head2 Object Methods
 248  
 249  Overloading has been used with version objects to provide a natural
 250  interface for their use.  All mathematical operations are forbidden,
 251  since they don't make any sense for base version objects.  Consequently,
 252  there is no overloaded numification available.  If you want to use a
 253  version object in a numeric context for some reason, see the L<numify>
 254  object method.
 255  
 256  =over 4
 257  
 258  =item * New Operator
 259  
 260  Like all OO interfaces, the new() operator is used to initialize
 261  version objects.  One way to increment versions when programming is to
 262  use the CVS variable $Revision, which is automatically incremented by
 263  CVS every time the file is committed to the repository.
 264  
 265  In order to facilitate this feature, the following
 266  code can be employed:
 267  
 268    $VERSION = version->new(qw$Revision: 2.7 $);
 269  
 270  and the version object will be created as if the following code
 271  were used:
 272  
 273    $VERSION = version->new("v2.7");
 274  
 275  In other words, the version will be automatically parsed out of the
 276  string, and it will be quoted to preserve the meaning CVS normally
 277  carries for versions.  The CVS $Revision$ increments differently from
 278  numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
 279  it were a L<Extended Version>.
 280  
 281  A new version object can be created as a copy of an existing version
 282  object, either as a class method:
 283  
 284    $v1 = version->new(12.3);
 285    $v2 = version->new($v1);
 286  
 287  or as an object method:
 288  
 289    $v1 = version->new(12.3);
 290    $v2 = $v1->new(12.3);
 291  
 292  and in each case, $v1 and $v2 will be identical.  NOTE: if you create
 293  a new object using an existing object like this:
 294  
 295    $v2 = $v1->new();
 296  
 297  the new object B<will not> be a clone of the existing object.  In the
 298  example case, $v2 will be an empty object of the same type as $v1.
 299  
 300  =back
 301  
 302  =over 4
 303  
 304  =item * qv()
 305  
 306  An alternate way to create a new version object is through the exported
 307  qv() sub.  This is not strictly like other q? operators (like qq, qw),
 308  in that the only delimiters supported are parentheses (or spaces).  It is
 309  the best way to initialize a short version without triggering the floating
 310  point interpretation.  For example:
 311  
 312    $v1 = qv(1.2);         # 1.2.0
 313    $v2 = qv("1.2");       # also 1.2.0
 314  
 315  As you can see, either a bare number or a quoted string can usually 
 316  be used interchangably, except in the case of a trailing zero, which
 317  must be quoted to be converted properly.  For this reason, it is strongly
 318  recommended that all initializers to qv() be quoted strings instead of
 319  bare numbers.
 320  
 321  To prevent the C<qv()> function from being exported to the caller's namespace,
 322  either use version with a null parameter:
 323  
 324    use version ();
 325  
 326  or just require version, like this:
 327  
 328    require version;
 329  
 330  Both methods will prevent the import() method from firing and exporting the
 331  C<qv()> sub.  This is true of subclasses of version as well, see
 332  L<SUBCLASSING> for details.
 333  
 334  =back
 335  
 336  For the subsequent examples, the following three objects will be used:
 337  
 338    $ver   = version->new("1.2.3.4"); # see "Quoting" below
 339    $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
 340    $nver  = version->new(1.002);     # see "Numeric Versions" above
 341  
 342  =over 4
 343  
 344  =item * Normal Form
 345  
 346  For any version object which is initialized with multiple decimal
 347  places (either quoted or if possible v-string), or initialized using
 348  the L<qv()> operator, the stringified representation is returned in
 349  a normalized or reduced form (no extraneous zeros), and with a leading 'v':
 350  
 351    print $ver->normal;         # prints as v1.2.3.4
 352    print $ver->stringify;      # ditto
 353    print $ver;                 # ditto
 354    print $nver->normal;        # prints as v1.2.0
 355    print $nver->stringify;     # prints as 1.002, see "Stringification" 
 356  
 357  In order to preserve the meaning of the processed version, the 
 358  normalized representation will always contain at least three sub terms.
 359  In other words, the following is guaranteed to always be true:
 360  
 361    my $newver = version->new($ver->stringify);
 362    if ($newver eq $ver ) # always true
 363      {...}
 364  
 365  =back
 366  
 367  =over 4
 368  
 369  =item * Numification
 370  
 371  Although all mathematical operations on version objects are forbidden
 372  by default, it is possible to retrieve a number which corresponds 
 373  to the version object through the use of the $obj->numify
 374  method.  For formatting purposes, when displaying a number which
 375  corresponds a version object, all sub versions are assumed to have
 376  three decimal places.  So for example:
 377  
 378    print $ver->numify;         # prints 1.002003004
 379    print $nver->numify;        # prints 1.002
 380  
 381  Unlike the stringification operator, there is never any need to append
 382  trailing zeros to preserve the correct version value.
 383  
 384  =back
 385  
 386  =over 4
 387  
 388  =item * Stringification
 389  
 390  The default stringification for version objects returns exactly the same
 391  string as was used to create it, whether you used C<new()> or C<qv()>,
 392  with one exception.  The sole exception is if the object was created using
 393  C<qv()> and the initializer did not have two decimal places or a leading
 394  'v' (both optional), then the stringified form will have a leading 'v'
 395  prepended, in order to support round-trip processing.
 396  
 397  For example:
 398  
 399    Initialized as          Stringifies to
 400    ==============          ==============
 401    version->new("1.2")       1.2
 402    version->new("v1.2")     v1.2
 403    qv("1.2.3")               1.2.3
 404    qv("v1.3.5")             v1.3.5
 405    qv("1.2")                v1.2   ### exceptional case 
 406  
 407  See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
 408  when used as a class method.
 409  
 410  =back
 411  
 412  =over 4
 413  
 414  =item * Comparison operators
 415  
 416  Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
 417  terms (upgrading to a version object automatically).  Perl automatically
 418  generates all of the other comparison operators based on those two.
 419  In addition to the obvious equalities listed below, appending a single
 420  trailing 0 term does not change the value of a version for comparison
 421  purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
 422  
 423  For example, the following relations hold:
 424  
 425    As Number        As String           Truth Value
 426    -------------    ----------------    -----------
 427    $ver >  1.0      $ver gt "1.0"       true
 428    $ver <  2.5      $ver lt             true
 429    $ver != 1.3      $ver ne "1.3"       true
 430    $ver == 1.2      $ver eq "1.2"       false
 431    $ver == 1.2.3.4  $ver eq "1.2.3.4"   see discussion below
 432  
 433  It is probably best to chose either the numeric notation or the string
 434  notation and stick with it, to reduce confusion.  Perl6 version objects
 435  B<may> only support numeric comparisons.  See also L<Quoting>.
 436  
 437  WARNING: Comparing version with unequal numbers of decimal points (whether
 438  explicitly or implicitly initialized), may yield unexpected results at
 439  first glance.  For example, the following inequalities hold:
 440  
 441    version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
 442    version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
 443  
 444  For this reason, it is best to use either exclusively L<Numeric Versions> or
 445  L<Extended Versions> with multiple decimal points.
 446  
 447  =back
 448  
 449  =over 4
 450  
 451  =item * Logical Operators 
 452  
 453  If you need to test whether a version object
 454  has been initialized, you can simply test it directly:
 455  
 456    $vobj = version->new($something);
 457    if ( $vobj )   # true only if $something was non-blank
 458  
 459  You can also test whether a version object is an L<Alpha version>, for
 460  example to prevent the use of some feature not present in the main
 461  release:
 462  
 463    $vobj = version->new("1.2_3"); # MUST QUOTE
 464    ...later...
 465    if ( $vobj->is_alpha )       # True
 466  
 467  =back
 468  
 469  =head2 Quoting
 470  
 471  Because of the nature of the Perl parsing and tokenizing routines,
 472  certain initialization values B<must> be quoted in order to correctly
 473  parse as the intended version, especially when using the L<qv()> operator.
 474  In all cases, a floating point number passed to version->new() will be
 475  identically converted whether or not the value itself is quoted.  This is
 476  not true for L<qv()>, however, when trailing zeros would be stripped on
 477  an unquoted input, which would result in a very different version object.
 478  
 479  In addition, in order to be compatible with earlier Perl version styles,
 480  any use of versions of the form 5.006001 will be translated as v5.6.1.  
 481  In other words, a version with a single decimal point will be parsed as
 482  implicitly having three digits between subversions, but only for internal
 483  comparison purposes.
 484  
 485  The complicating factor is that in bare numbers (i.e. unquoted), the
 486  underscore is a legal numeric character and is automatically stripped
 487  by the Perl tokenizer before the version code is called.  However, if
 488  a number containing one or more decimals and an underscore is quoted, i.e.
 489  not bare, that is considered a L<Alpha Version> and the underscore is
 490  significant.
 491  
 492  If you use a mathematic formula that resolves to a floating point number,
 493  you are dependent on Perl's conversion routines to yield the version you
 494  expect.  You are pretty safe by dividing by a power of 10, for example,
 495  but other operations are not likely to be what you intend.  For example:
 496  
 497    $VERSION = version->new((qw$Revision: 1.4)[1]/10);
 498    print $VERSION;          # yields 0.14
 499    $V2 = version->new(100/9); # Integer overflow in decimal number
 500    print $V2;               # yields something like 11.111.111.100
 501  
 502  Perl 5.8.1 and beyond will be able to automatically quote v-strings but
 503  that is not possible in earlier versions of Perl.  In other words:
 504  
 505    $version = version->new("v2.5.4");  # legal in all versions of Perl
 506    $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
 507  
 508  =head2 What about v-strings?
 509  
 510  Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
 511  of bytes was introduced, called v-strings.  They were intended to be an
 512  easy way to enter, for example, Unicode strings (which contain two bytes
 513  per character).  Some programs have used them to encode printer control
 514  characters (e.g. CRLF).  They were also intended to be used for $VERSION,
 515  but their use as such has been problematic from the start.
 516  
 517  There are two ways to enter v-strings: a bare number with two or more
 518  decimal points, or a bare number with one or more decimal points and a 
 519  leading 'v' character (also bare).  For example:
 520  
 521    $vs1 = 1.2.3; # encoded as \1\2\3
 522    $vs2 = v1.2;  # encoded as \1\2 
 523  
 524  However, the use of bare v-strings to initialize version objects is
 525  B<strongly> discouraged in all circumstances (especially the leading 
 526  'v' style), since the meaning will change depending on which Perl you 
 527  are running.  It is better to directly use L<"Extended Versions"> to 
 528  ensure the proper interpretation.
 529  
 530  If you insist on using bare v-strings with Perl > 5.6.0, be aware of the 
 531  following limitations:
 532  
 533  1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses, 
 534  based on some characteristics of v-strings.  You B<must> use a three part
 535  version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
 536  
 537  2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
 538  core to be magical, which means that the version.pm code can automatically
 539  determine whether the v-string encoding was used.
 540  
 541  3) In all cases, a version created using v-strings will have a stringified
 542  form that has a leading 'v' character, for the simple reason that sometimes
 543  it is impossible to tell whether one was present initially.
 544  
 545  =head2 Types of Versions Objects
 546  
 547  There are two types of Version Objects:
 548  
 549  =over 4
 550  
 551  =item * Ordinary versions
 552  
 553  These are the versions that normal modules will use.  Can contain as
 554  many subversions as required.  In particular, those using RCS/CVS can
 555  use the following:
 556  
 557    $VERSION = version->new(qw$Revision: 2.7 $);
 558  
 559  and the current RCS Revision for that file will be inserted
 560  automatically.  If the file has been moved to a branch, the Revision
 561  will have three or more elements; otherwise, it will have only two.
 562  This allows you to automatically increment your module version by
 563  using the Revision number from the primary file in a distribution, see
 564  L<ExtUtils::MakeMaker/"VERSION_FROM">.
 565  
 566  =item * Alpha Versions
 567  
 568  For module authors using CPAN, the convention has been to note
 569  unstable releases with an underscore in the version string, see
 570  L<CPAN>.  Alpha releases will test as being newer than the more recent
 571  stable release, and less than the next stable release.  For example:
 572  
 573    $alphaver = version->new("12.03_01"); # must be quoted
 574  
 575  obeys the relationship
 576  
 577    12.03 < $alphaver < 12.04
 578  
 579  Alpha versions with a single decimal point will be treated exactly as if
 580  they were L<Numeric Versions>, for parsing and output purposes.  The
 581  underscore will be output when an alpha version is stringified, in the same
 582  place as it was when input.
 583  
 584  Alpha versions with more than a single decimal point will be treated 
 585  exactly as if they were L<Extended Versions>, and will display without any
 586  trailing (or leading) zeros, in the L<Version Normal> form.  For example,
 587  
 588    $newver = version->new("12.3.1_1");
 589    print $newver; # v12.3.1_1
 590  
 591  =back
 592  
 593  =head2 Replacement UNIVERSAL::VERSION
 594  
 595  In addition to the version objects, this modules also replaces the core
 596  UNIVERSAL::VERSION function with one that uses version objects for its
 597  comparisons.  The return from this operator is always the stringified form,
 598  but the warning message generated includes either the stringified form or
 599  the normal form, depending on how it was called.
 600  
 601  For example:
 602  
 603    package Foo;
 604    $VERSION = 1.2;
 605  
 606    package Bar;
 607    $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
 608  
 609    package main;
 610    use version;
 611  
 612    print $Foo::VERSION; # prints 1.2
 613  
 614    print $Bar::VERSION; # prints 1.003005
 615  
 616    eval "use foo 10";
 617    print $@; # prints "foo version 10 required..."
 618    eval "use foo 1.3.5; # work in Perl 5.6.1 or better
 619    print $@; # prints "foo version 1.3.5 required..."
 620  
 621    eval "use bar 1.3.6";
 622    print $@; # prints "bar version 1.3.6 required..."
 623    eval "use bar 1.004"; # note numeric version
 624    print $@; # prints "bar version 1.004 required..."
 625  
 626  
 627  IMPORTANT NOTE: This may mean that code which searches for a specific
 628  string (to determine whether a given module is available) may need to be
 629  changed.  It is always better to use the built-in comparison implicit in
 630  C<use> or C<require>, rather than manually poking at C<class->VERSION>
 631  and then doing a comparison yourself.
 632  
 633  The replacement UNIVERSAL::VERSION, when used as a function, like this:
 634  
 635    print $module->VERSION;
 636  
 637  will also exclusively return the stringified form.  See L<Stringification>
 638  for more details.
 639  
 640  =head1 SUBCLASSING
 641  
 642  This module is specifically designed and tested to be easily subclassed.
 643  In practice, you only need to override the methods you want to change, but
 644  you have to take some care when overriding new() (since that is where all
 645  of the parsing takes place).  For example, this is a perfect acceptable
 646  derived class:
 647  
 648    package myversion;
 649    use base version;
 650    sub new { 
 651        my($self,$n)=@_;
 652        my $obj;
 653        # perform any special input handling here
 654        $obj = $self->SUPER::new($n);
 655        # and/or add additional hash elements here
 656        return $obj;
 657    }
 658  
 659  See also L<version::AlphaBeta> on CPAN for an alternate representation of
 660  version strings.
 661  
 662  B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
 663  function exported into the caller's namespace, a subclass of version will 
 664  inherit an import() function which will perform the correct magic on behalf
 665  of the subclass.
 666  
 667  =head1 EXPORT
 668  
 669  qv - Extended Version initialization operator
 670  
 671  =head1 AUTHOR
 672  
 673  John Peacock E<lt>jpeacock@cpan.orgE<gt>
 674  
 675  =head1 SEE ALSO
 676  
 677  L<perl>.
 678  
 679  =cut