Final release of version-0.77 for inclusion in 5.10.1
authorJohn Peacock <john.peacock@havurah-software.org>
Mon, 27 Jul 2009 22:21:12 +0000 (18:21 -0400)
committerDavid Mitchell <davem@iabyn.com>
Mon, 27 Jul 2009 22:28:27 +0000 (23:28 +0100)
lib/version.pod
lib/version.t
lib/version/Internals.pod [new file with mode: 0644]

index 7f85ecb..090b596 100644 (file)
@@ -4,519 +4,237 @@ version - Perl extension for Version Objects
 
 =head1 SYNOPSIS
 
-  use version;
-  $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
-  print $version;              # v12.2.1
-  print $version->numify;      # 12.002001
-  if ( $version gt "12.2" )    # true
+  # Parsing version strings (decimal or dotted-decimal)
 
-  $alphaver = version->new("1.02_03"); # must be quoted!
-  print $alphaver;             # 1.02_0300
-  print $alphaver->is_alpha();  # true
-  
-  $ver = qv("1.2.0");           # v1.2.0
+  use version 0.77; # get latest bug-fixes and API
+  $ver = version->parse($string)
 
-  $perlver = version->new(5.005_03); # must not be quoted!
-  print $perlver;              # 5.005030
+  # Declaring a dotted-decimal $VERSION (keep on one line!)
 
-=head1 DESCRIPTION
-
-Overloaded version objects for all modern versions of Perl.  This module
-implements all of the features of version objects which are part
-of Perl 5.10.0.  All previous releases (i.e. before 0.74) are deprecated
-and should not be used due to incompatible API changes.  If you 'use
-version' in your code, you are strongly urged to set a minimum, e.g. 
-
-  use version 0.74; # to remain compatible with Perl v5.10.0
-
-=head2 BEST PRACTICES
-
-If you intend for your module to be used by different releases of Perl,
-and/or for your $VERSION scalar to mean what you think it means, there 
-are a few simple rules to follow:
-
-=over 4
-
-=item * Be consistent
-
-Whichever of the two types of version objects that you choose to employ, 
-you should stick to either L<Numeric Versions> or L<Extended Versions>
-and not mix them together.  While this is I<possible>, it is very 
-confusing to the average user.
-
-If you intend to use L<Extended Versions>, you are strongly encouraged 
-to use the L<qv()> operator with a quoted term, e.g.:
-
-  use version; our $VERSION = qv("1.2.3");
-
-on a single line as above. 
-
-At the very least, decide on which of the several ways to initialize 
-your version objects you prefer and stick with it.  It is also best to 
-be explicit about what value you intend to assign your version object 
-and to not rely on hidden behavior of the parser. 
-
-=item * Be careful
-
-If you are using Module::Build or ExtUtils::MakeMaker, so that you can
-release your module to CPAN, you have to recognize that neither of those
-programs completely handles version objects natively (yet).  If you use
-version objects with Module::Build, you should add an explicit dependency
-to the release of version.pm in your Build.PL:
-
-  my $builder = Module::Build->new(
-     ...
-     requires => {
-         ... ,
-         'version'    => 0.50,
-        ...,
-     },
-     ...
-  );
-
-and it should Just Work(TM).  Module::Build will [hopefully soon] 
-include full support for version objects; there are no current plans 
-to patch ExtUtils::MakeMaker to support version objects.
-
-=back
-
-=head2 Using modules that use version.pm
-
-As much as possible, the version.pm module remains compatible with all
-current code.  However, if your module is using a module that has defined
-C<$VERSION> using the version class, there are a couple of things to be
-aware of.  For purposes of discussion, we will assume that we have the
-following module installed:
-
-  package Example;
-  use version;  $VERSION = qv('1.2.2');
-  ...module code here...
-  1;
+  use version 0.77; our $VERSION = version->declare("v1.2.3"); # formal
+  use version 0.77; our $VERSION = qv("v1.2.3");               # shorthand
+  use version 0.77; our $VERSION = qv("v1.2_3");               # alpha
 
-=over 4
+  # Declaring an old-style decimal $VERSION (use quotes!)
 
-=item Numeric versions always work
+  use version 0.77; our $VERSION = version->parse("1.0203");   # formal
+  use version 0.77; our $VERSION = version->parse("1.02_03");  # alpha
 
-Code of the form:
+  # Comparing mixed version styles (decimals, dotted-decimals, objects)
 
-  use Example 1.002003;
-
-will always work correctly.  The C<use> will perform an automatic
-C<$VERSION> comparison using the floating point number given as the first
-term after the module name (e.g. above 1.002.003).  In this case, the
-installed module is too old for the requested line, so you would see an
-error like:
-
-  Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
-
-=item Extended version work sometimes
+  if ( version->parse($v1) == version->parse($v2) ) {
+    # do stuff
+  }
 
-With Perl >= 5.6.2, you can also use a line like this:
+  # Sorting mixed version styles
 
-  use Example 1.2.3;
+  @ordered = sort { version->parse($a) <=> version->parse($b) } @list;
 
-and it will again work (i.e. give the error message as above), even with
-releases of Perl which do not normally support v-strings (see L<What about
-v-strings> below).  This has to do with that fact that C<use> only checks
-to see if the second term I<looks like a number> and passes that to the
-replacement L<UNIVERSAL::VERSION>.  This is not true in Perl 5.005_04,
-however, so you are B<strongly encouraged> to always use a numeric version
-in your code, even for those versions of Perl which support the extended
-version.
+=head1 DESCRIPTION
 
-=back
+Version objects were added to Perl in 5.10.  This module implements version
+objects for older version of Perl and provides the version object API for all
+versions of Perl.  All previous releases before 0.74 are deprecated and should
+not be used due to incompatible API changes.  Version 0.77 introduces the new
+'parse' and 'declare' methods to standardize usage.  You are strongly urged to
+set 0.77 as a minimum in your code, e.g. 
 
-=head2 What IS a version
+  use version 0.77; # even for Perl v.5.10.0
 
-For the purposes of this module, a version "number" is a sequence of
-positive integer values separated by one or more decimal points and 
-optionally a single underscore.  This corresponds to what Perl itself 
-uses for a version, as well as extending the "version as number" that 
-is discussed in the various editions of the Camel book.
+=head1 TYPES OF VERSION OBJECTS
 
-There are actually two distinct kinds of version objects:
+There are two different types of version objects, corresponding to the two
+different styles of versions in use:
 
-=over 4
+=over 2
 
-=item * Numeric Versions
+=item Decimal Versions
 
-Any initial parameter which "looks like a number", see L<Numeric
-Versions>.  This also covers versions with a single decimal point and
-a single embedded underscore, see L<Numeric Alpha Versions>, even though
-these must be quoted to preserve the underscore formatting.
+The classic floating-point number $VERSION.  The advantage to this style is
+that you don't need to do anything special, just type a number (without
+quotes) into your source file.
 
-=item * Extended Versions
+=item Dotted Decimal Versions
 
-Any initial parameter which contains more than one decimal point
-and an optional embedded underscore, see L<Extended Versions>.  This 
-is what is commonly used in most open source software as the "external"
-version (the one used as part of the tag or tarfile name).  The use
-of the exported L<qv()> function also produces this kind of version
-object.
+The more modern form of version assignment, with 3 (or potentially more)
+integers seperated by decimal points (e.g. v1.2.3).  This is the form that
+Perl itself has used since 5.6.0 was released.  The leading "v" is now 
+strongly recommended for clarity, and will throw a warning in a future
+release if omitted.
 
 =back
 
-Both of these methods will produce similar version objects, in that
-the default stringification will yield the version L<Normal Form> only 
-if required:
-
-  $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
-  $v  = version->new(1.002003);  # 1.002003
-  $v2 = version->new("1.2.3");   # v1.2.3
-
-In specific, version numbers initialized as L<Numeric Versions> will
-stringify as they were originally created (i.e. the same string that was
-passed to C<new()>.  Version numbers initialized as L<Extended Versions>
-will be stringified as L<Normal Form>.
-
-=head2 Numeric Versions
-
-These correspond to historical versions of Perl itself prior to 5.6.0,
-as well as all other modules which follow the Camel rules for the
-$VERSION scalar.  A numeric version is initialized with what looks like
-a floating point number.  Leading zeros B<are> significant and trailing
-zeros are implied so that a minimum of three places is maintained
-between subversions.  What this means is that any subversion (digits
-to the right of the decimal place) that contains less than three digits
-will have trailing zeros added to make up the difference, but only for
-purposes of comparison with other version objects.  For example:
-
-                                   # Prints     Equivalent to  
-  $v = version->new(      1.2);    # 1.2        v1.200.0
-  $v = version->new(     1.02);    # 1.02       v1.20.0
-  $v = version->new(    1.002);    # 1.002      v1.2.0
-  $v = version->new(   1.0023);    # 1.0023     v1.2.300
-  $v = version->new(  1.00203);    # 1.00203    v1.2.30
-  $v = version->new( 1.002003);    # 1.002003   v1.2.3
-
-All of the preceding examples are true whether or not the input value is 
-quoted.  The important feature is that the input value contains only a 
-single decimal.  See also L<Alpha Versions> for how to handle 
-
-IMPORTANT NOTE: As shown above, if your numeric version contains more 
-than 3 significant digits after the decimal place, it will be split on 
-each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need 
-to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.  
-Any trailing zeros are ignored for mathematical comparison purposes.
-
-=head2 Extended Versions
-
-These are the newest form of versions, and correspond to Perl's own
-version style beginning with 5.6.0.  Starting with Perl 5.10.0,
-and most likely Perl 6, this is likely to be the preferred form.  This
-method normally requires that the input parameter be quoted, although 
-Perl's after 5.8.1 can use v-strings as a special form of quoting, but
-this is highly discouraged.
-
-Unlike L<Numeric Versions>, Extended Versions have more than
-a single decimal point, e.g.:
-
-                                   # Prints
-  $v = version->new( "v1.200");    # v1.200.0
-  $v = version->new("v1.20.0");    # v1.20.0
-  $v = qv("v1.2.3");               # v1.2.3
-  $v = qv("1.2.3");                # v1.2.3
-  $v = qv("1.20");                 # v1.20.0
-
-In general, Extended Versions permit the greatest amount of freedom
-to specify a version, whereas Numeric Versions enforce a certain
-uniformity.  See also L<New Operator> for an additional method of
-initializing version objects.
+See L<VERSION OBJECT DETAILS> for further information.
 
-Just like L<Numeric Versions>, Extended Versions can be used as 
-L<Alpha Versions>.
+=head1 DECLARING VERSIONS
 
-=head2 Numeric Alpha Versions
+If you have a module that uses a decimal $VERSION (floating point), and you
+do not intend to ever change that, this module is not for you.  There is
+nothing that version.pm gains you over a simple $VERSION assignment:
 
-The one time that a numeric version must be quoted is when a alpha form is
-used with an otherwise numeric version (i.e. a single decimal point).  This
-is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
-versions for automatic updating purposes.  Since some developers have used
-only two significant decimal places for their non-alpha releases, the
-version object will automatically take that into account if the initializer
-is quoted.  For example Module::Example was released to CPAN with the
-following sequence of $VERSION's:
+  our $VERSION = 1.02;
 
-  # $VERSION    Stringified
-  0.01          0.01
-  0.02          0.02
-  0.02_01       0.02_01
-  0.02_02       0.02_02
-  0.03          0.03
-  etc.
+Since Perl v5.10.0 includes the version.pm comparison logic anyways, 
+you don't need to do anything at all.
 
-The stringified form of numeric versions will always be the same string
-that was used to initialize the version object.
+=head2 How to convert a module from decimal to dotted-decimal
 
-=head2 Object Methods
+If you have used a decimal $VERSION in the past and wish to switch to a
+dotted-decimal $VERSION, then you need to make a one-time conversion to
+the new format. 
 
-Overloading has been used with version objects to provide a natural
-interface for their use.  All mathematical operations are forbidden,
-since they don't make any sense for base version objects.  Consequently,
-there is no overloaded numification available.  If you want to use a
-version object in a numeric context for some reason, see the L<numify>
-object method.
-
-=over 4
+B<Important Note>: you must ensure that your new $VERSION is numerically
+greater than your current decimal $VERSION; this is not always obvious. First,
+convert your old decimal version (e.g. 1.02) to a normalized dotted-decimal
+form:
 
-=item * New Operator
-
-Like all OO interfaces, the new() operator is used to initialize
-version objects.  One way to increment versions when programming is to
-use the CVS variable $Revision, which is automatically incremented by
-CVS every time the file is committed to the repository.
-
-In order to facilitate this feature, the following
-code can be employed:
+  $ perl -Mversion -e 'print version->parse("1.02")->normal'
+  v1.20.0
 
-  $VERSION = version->new(qw$Revision: 2.7 $);
+Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0).
 
-and the version object will be created as if the following code
-were used:
-
-  $VERSION = version->new("v2.7");
-
-In other words, the version will be automatically parsed out of the
-string, and it will be quoted to preserve the meaning CVS normally
-carries for versions.  The CVS $Revision$ increments differently from
-numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
-it were a L<Extended Version>.
-
-A new version object can be created as a copy of an existing version
-object, either as a class method:
-
-  $v1 = version->new(12.3);
-  $v2 = version->new($v1);
-
-or as an object method:
-
-  $v1 = version->new(12.3);
-  $v2 = $v1->new(12.3);
-
-and in each case, $v1 and $v2 will be identical.  NOTE: if you create
-a new object using an existing object like this:
-
-  $v2 = $v1->new();
-
-the new object B<will not> be a clone of the existing object.  In the
-example case, $v2 will be an empty object of the same type as $v1.
-
-=back
+=head2 How to C<declare()> a dotted-decimal version
 
-=over 4
+  use version 0.77; our $VERSION = version->declare("v1.2.3");
 
-=item * qv()
+The C<declare()> method always creates dotted-decimal version objects.  When
+used in a module, you B<must> put it on the same line as "use version" to
+ensure that $VERSION is read correctly by PAUSE and installer tools.  You
+should also add 'version' to the 'configure_requires' section of your
+module metadata file.  See instructions in L<ExtUtils::MakeMaker> or
+L<Module::Build> for details.
 
-An alternate way to create a new version object is through the exported
-qv() sub.  This is not strictly like other q? operators (like qq, qw),
-in that the only delimiters supported are parentheses (or spaces).  It is
-the best way to initialize a short version without triggering the floating
-point interpretation.  For example:
+B<Important Note>: Even if you pass in what looks like a decimal number
+("1.2"), a dotted-decimal will be created ("v1.200.0"). To avoid confusion
+or unintentional errors on older Perls, follow these guidelines:
 
-  $v1 = qv(1.2);         # 1.2.0
-  $v2 = qv("1.2");       # also 1.2.0
+=over 2
 
-As you can see, either a bare number or a quoted string can usually 
-be used interchangably, except in the case of a trailing zero, which
-must be quoted to be converted properly.  For this reason, it is strongly
-recommended that all initializers to qv() be quoted strings instead of
-bare numbers.
+=item *
 
-To prevent the C<qv()> function from being exported to the caller's namespace,
-either use version with a null parameter:
+Always use a dotted-decimal with (at least) three components
 
-  use version ();
+=item *
 
-or just require version, like this:
+Always use a leading-v
 
-  require version;
+=item *
 
-Both methods will prevent the import() method from firing and exporting the
-C<qv()> sub.  This is true of subclasses of version as well, see
-L<SUBCLASSING> for details.
+Always quote the version
 
 =back
 
-For the subsequent examples, the following three objects will be used:
+If you really insist on using version.pm with an ordinary decimal version,
+use C<parse()> instead of declare.  See the L<PARSING AND COMPARING VERSIONS>
+for details.
 
-  $ver   = version->new("1.2.3.4"); # see "Quoting" below
-  $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
-  $nver  = version->new(1.002);     # see "Numeric Versions" above
+See also L<VERSION OBJECT DETAILS> for more on version number conversion,
+quoting, calculated version numbers and declaring developer or "alpha" version
+numbers.
 
-=over 4
+=head1 PARSING AND COMPARING VERSIONS
 
-=item * Normal Form
+If you need to compare version numbers, but can't be sure whether they are
+expressed as numbers, strings, v-strings or version objects,  then you can
+use version.pm to parse them all into objects for comparison.
 
-For any version object which is initialized with multiple decimal
-places (either quoted or if possible v-string), or initialized using
-the L<qv()> operator, the stringified representation is returned in
-a normalized or reduced form (no extraneous zeros), and with a leading 'v':
+=head2 How to C<parse()> a version
 
-  print $ver->normal;         # prints as v1.2.3.4
-  print $ver->stringify;      # ditto
-  print $ver;                 # ditto
-  print $nver->normal;        # prints as v1.2.0
-  print $nver->stringify;     # prints as 1.002, see "Stringification" 
+The C<parse()> method takes in anything that might be a version and returns
+a corresponding version object, doing any necessary conversion along the way.
 
-In order to preserve the meaning of the processed version, the 
-normalized representation will always contain at least three sub terms.
-In other words, the following is guaranteed to always be true:
+=over 2
 
-  my $newver = version->new($ver->stringify);
-  if ($newver eq $ver ) # always true
-    {...}
+=item *
 
-=back
-
-=over 4
-
-=item * Numification
+Dotted-decimal: bare v-strings (v1.2.3) and strings with more than one
+decimal point and a leading 'v' ("v1.2.3"); NOTE you can technically use a
+v-string or strings with a leading-v and only one decimal point (v1.2 or
+"v1.2"), but you will confuse both yourself and others.
 
-Although all mathematical operations on version objects are forbidden
-by default, it is possible to retrieve a number which corresponds 
-to the version object through the use of the $obj->numify
-method.  For formatting purposes, when displaying a number which
-corresponds a version object, all sub versions are assumed to have
-three decimal places.  So for example:
+=item *
 
-  print $ver->numify;         # prints 1.002003004
-  print $nver->numify;        # prints 1.002
-
-Unlike the stringification operator, there is never any need to append
-trailing zeros to preserve the correct version value.
+Decimal: regular decimal numbers (literal or in a string)
 
 =back
 
-=over 4
-
-=item * Stringification
+Some examples:
 
-The default stringification for version objects returns exactly the same
-string as was used to create it, whether you used C<new()> or C<qv()>,
-with one exception.  The sole exception is if the object was created using
-C<qv()> and the initializer did not have two decimal places or a leading
-'v' (both optional), then the stringified form will have a leading 'v'
-prepended, in order to support round-trip processing.
+  $variable   version->parse($variable)
+  ---------   -------------------------
+  1.23        v1.230.0
+  "1.23"      v1.230.0
+  v1.23       v1.23.0
+  "v1.23"     v1.23.0
+  "1.2.3"     v1.2.3
+  "v1.2.3"    v1.2.3
 
-For example:
+See L<VERSION OBJECT DETAILS> for more on version number conversion.
 
-  Initialized as          Stringifies to
-  ==============          ==============
-  version->new("1.2")       1.2
-  version->new("v1.2")     v1.2
-  qv("1.2.3")               1.2.3
-  qv("v1.3.5")             v1.3.5
-  qv("1.2")                v1.2   ### exceptional case 
+=head2 How to compare version objects
 
-See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
-when used as a class method.
+Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators.  Perl
+automatically generates all of the other comparison operators based on those
+two so all the normal logical comparisons will work.
 
-IMPORTANT NOTE: There is one exceptional cases shown in the above table
-where the "initializer" is not stringwise equivalent to the stringified
-representation.  If you use the C<qv()> operator on a version without a
-leading 'v' B<and> with only a single decimal place, the stringified output
-will have a leading 'v', to preserve the sense.  See the L<qv()> operator
-for more details.
+  if ( version->parse($v1) == version->parse($v2) ) {
+    # do stuff
+  }
 
-IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
-manually applying L<numify()> and L<normal()> will sometimes yield
+If a version object is compared against a non-version object, the non-object
+term will be converted to a version object using C<parse()>.  This may give
 surprising results:
 
-  print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
+  $v1 = version->parse("v0.95.0");
+  $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0
 
-The reason for this is that the L<numify()> operator will turn "v1.0"
-into the equivalent string "1.000000".  Forcing the outer version object
-to L<normal()> form will display the mathematically equivalent "v1.0.0".
-
-As the example in L<new()> shows, you can always create a copy of an
-existing version object with the same value by the very compact:
-
-  $v2 = $v1->new($v1);
-
-and be assured that both C<$v1> and C<$v2> will be completely equivalent,
-down to the same internal representation as well as stringification.
-
-=back
+Always comparing to a version object will help avoid surprises:
 
-=over 4
+  $bool = $v1 < version->parse("v0.96.0"); # TRUE
 
-=item * Comparison operators
+=head1 VERSION OBJECT DETAILS
 
-Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
-terms (upgrading to a version object automatically).  Perl automatically
-generates all of the other comparison operators based on those two.
-In addition to the obvious equalities listed below, appending a single
-trailing 0 term does not change the value of a version for comparison
-purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
+=head2 Equivalence between Decimal and Dotted-Decimal Versions
 
-For example, the following relations hold:
+When Perl 5.6.0 was released, the decision was made to provide a
+transformation between the old-style decimal versions and new-style
+dotted-decimal versions:
 
-  As Number        As String           Truth Value
-  -------------    ----------------    -----------
-  $ver >  1.0      $ver gt "1.0"       true
-  $ver <  2.5      $ver lt             true
-  $ver != 1.3      $ver ne "1.3"       true
-  $ver == 1.2      $ver eq "1.2"       false
-  $ver == 1.2.3.4  $ver eq "1.2.3.4"   see discussion below
+  5.6.0    == 5.006000
+  5.005_04 == 5.5.40
 
-It is probably best to chose either the numeric notation or the string
-notation and stick with it, to reduce confusion.  Perl6 version objects
-B<may> only support numeric comparisons.  See also L<Quoting>.
+The floating point number is taken and split first on the single decimal
+place, then each group of three digits to the right of the decimal makes up
+the next digit, and so on until the number of significant digits is exhausted,
+B<plus> enough trailing zeros to reach the next multiple of three.
 
-WARNING: Comparing version with unequal numbers of decimal points (whether
-explicitly or implicitly initialized), may yield unexpected results at
-first glance.  For example, the following inequalities hold:
+This was the method that version.pm adopted as well.  Some examples may be
+helpful:
 
-  version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
-  version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
+                            equivalent
+  decimal    zero-padded    dotted-decimal
+  -------    -----------    --------------
+  1.2        1.200          v1.200.0
+  1.02       1.020          v1.20.0
+  1.002      1.002          v1.2.0
+  1.0023     1.002300       v1.2.300
+  1.00203    1.002030       v1.2.30
+  1.002003   1.002003       v1.2.3
 
-For this reason, it is best to use either exclusively L<Numeric Versions> or
-L<Extended Versions> with multiple decimal points.
-
-=back
-
-=over 4
-
-=item * Logical Operators 
-
-If you need to test whether a version object
-has been initialized, you can simply test it directly:
-
-  $vobj = version->new($something);
-  if ( $vobj )   # true only if $something was non-blank
-
-You can also test whether a version object is an L<Alpha version>, for
-example to prevent the use of some feature not present in the main
-release:
-
-  $vobj = version->new("1.2_3"); # MUST QUOTE
-  ...later...
-  if ( $vobj->is_alpha )       # True
-
-=back
-
-=head2 Quoting
+=head2 Quoting rules
 
 Because of the nature of the Perl parsing and tokenizing routines,
 certain initialization values B<must> be quoted in order to correctly
-parse as the intended version, especially when using the L<qv()> operator.
-In all cases, a floating point number passed to version->new() will be
-identically converted whether or not the value itself is quoted.  This is
-not true for L<qv()>, however, when trailing zeros would be stripped on
-an unquoted input, which would result in a very different version object.
-
-In addition, in order to be compatible with earlier Perl version styles,
-any use of versions of the form 5.006001 will be translated as v5.6.1.  
-In other words, a version with a single decimal point will be parsed as
-implicitly having three digits between subversions, but only for internal
-comparison purposes.
-
-The complicating factor is that in bare numbers (i.e. unquoted), the
-underscore is a legal numeric character and is automatically stripped
-by the Perl tokenizer before the version code is called.  However, if
-a number containing one or more decimals and an underscore is quoted, i.e.
-not bare, that is considered a L<Alpha Version> and the underscore is
-significant.
+parse as the intended version, especially when using the L<declare> or
+L<qv> methods.  While you do not have to quote decimal numbers when
+creating version objects, it is always safe to quote B<all> initial values
+when using version.pm methods, as this will ensure that what you type is
+what is used.
+
+Additionally, if you quote your initializer, then the quoted value that goes
+B<in> will be be exactly what comes B<out> when your $VERSION is printed
+(stringified).  If you do not quote your value, Perl's normal numeric handling
+comes into play and you may not get back what you were expecting.
 
 If you use a mathematic formula that resolves to a floating point number,
 you are dependent on Perl's conversion routines to yield the version you
@@ -528,7 +246,7 @@ but other operations are not likely to be what you intend.  For example:
   $V2 = version->new(100/9); # Integer overflow in decimal number
   print $V2;               # yields something like 11.111.111.100
 
-Perl 5.8.1 and beyond will be able to automatically quote v-strings but
+Perl 5.8.1 and beyond are able to automatically quote v-strings but
 that is not possible in earlier versions of Perl.  In other words:
 
   $version = version->new("v2.5.4");  # legal in all versions of Perl
@@ -536,13 +254,6 @@ that is not possible in earlier versions of Perl.  In other words:
 
 =head2 What about v-strings?
 
-Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
-of bytes was introduced, called v-strings.  They were intended to be an
-easy way to enter, for example, Unicode strings (which contain two bytes
-per character).  Some programs have used them to encode printer control
-characters (e.g. CRLF).  They were also intended to be used for $VERSION,
-but their use as such has been problematic from the start.
-
 There are two ways to enter v-strings: a bare number with two or more
 decimal points, or a bare number with one or more decimal points and a 
 leading 'v' character (also bare).  For example:
@@ -551,10 +262,9 @@ leading 'v' character (also bare).  For example:
   $vs2 = v1.2;  # encoded as \1\2 
 
 However, the use of bare v-strings to initialize version objects is
-B<strongly> discouraged in all circumstances (especially the leading 
-'v' style), since the meaning will change depending on which Perl you 
-are running.  It is better to directly use L<"Extended Versions"> to 
-ensure the proper interpretation.
+B<strongly> discouraged in all circumstances.  Also, bare
+v-strings are not completely supported in any version of Perl prior to
+5.8.1.
 
 If you insist on using bare v-strings with Perl > 5.6.0, be aware of the 
 following limitations:
@@ -571,131 +281,76 @@ determine whether the v-string encoding was used.
 form that has a leading 'v' character, for the simple reason that sometimes
 it is impossible to tell whether one was present initially.
 
-=head2 Types of Versions Objects
-
-There are two types of Version Objects:
-
-=over 4
-
-=item * Ordinary versions
-
-These are the versions that normal modules will use.  Can contain as
-many subversions as required.  In particular, those using RCS/CVS can
-use the following:
-
-  $VERSION = version->new(qw$Revision: 2.7 $);
-
-and the current RCS Revision for that file will be inserted
-automatically.  If the file has been moved to a branch, the Revision
-will have three or more elements; otherwise, it will have only two.
-This allows you to automatically increment your module version by
-using the Revision number from the primary file in a distribution, see
-L<ExtUtils::MakeMaker/"VERSION_FROM">.
-
-=item * Alpha Versions
+=head2 Alpha versions
 
-For module authors using CPAN, the convention has been to note
-unstable releases with an underscore in the version string, see
-L<CPAN>.  Alpha releases will test as being newer than the more recent
-stable release, and less than the next stable release.  For example:
+For module authors using CPAN, the convention has been to note unstable
+releases with an underscore in the version string. (See L<CPAN>.)  version.pm
+follows this convention and alpha releases will test as being newer than the
+more recent stable release, and less than the next stable release.  For
+dotted-decimal versions, only the last element may be separated by an
+underscore:
 
-  $alphaver = version->new("12.03_01"); # must be quoted
+  # Declaring
+  use version 0.77; our $VERSION = version->declare("v1.2_3");
 
-obeys the relationship
+  # Parsing
+  $v1 = version->parse("v1.2_3");
+  $v1 = version->parse("1.002_003");
 
-  12.03 < $alphaver < 12.04
+=head1 OBJECT METHODS
 
-Alpha versions with a single decimal point will be treated exactly as if
-they were L<Numeric Versions>, for parsing and output purposes.  The
-underscore will be output when an alpha version is stringified, in the same
-place as it was when input.
+=head2 is_alpha()
 
-Alpha versions with more than a single decimal point will be treated 
-exactly as if they were L<Extended Versions>, and will display without any
-trailing (or leading) zeros, in the L<Version Normal> form.  For example,
+True if and only if the version object was created with a underscore, e.g.
 
-  $newver = version->new("12.3.1_1");
-  print $newver; # v12.3.1_1
+  version->parse('1.002_03')->is_alpha;  # TRUE
+  version->declare('1.2.3_4')->is_alpha; # TRUE
 
-=back
-
-=head2 Replacement UNIVERSAL::VERSION
-
-In addition to the version objects, this modules also replaces the core
-UNIVERSAL::VERSION function with one that uses version objects for its
-comparisons.  The return from this operator is always the stringified form,
-but the warning message generated includes either the stringified form or
-the normal form, depending on how it was called.
-
-For example:
-
-  package Foo;
-  $VERSION = 1.2;
+=head2 is_qv()
 
-  package Bar;
-  $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
+True only if the version object is a dotted-decimal version, e.g.
 
-  package main;
-  use version;
+  version->parse('v1.2.0')->is_qv;        # TRUE
+  version->declare('v1.2')->is_qv;       # TRUE
+  qv('1.2')->is_qv;                      # TRUE
+  version->parse('1.2')->is_qv;          # FALSE
 
-  print $Foo::VERSION; # prints 1.2
+=head2 normal()
 
-  print $Bar::VERSION; # prints 1.003005
+Returns a string with a standard 'normalized' dotted-decimal form with a
+leading-v and at least 3 components.
 
-  eval "use foo 10";
-  print $@; # prints "foo version 10 required..."
-  eval "use foo 1.3.5; # work in Perl 5.6.1 or better
-  print $@; # prints "foo version 1.3.5 required..."
+ version->declare('v1.2')->normal;  # v1.2.0
+ version->parse('1.2')->normal;     # v1.200.0
 
-  eval "use bar 1.3.6";
-  print $@; # prints "bar version 1.3.6 required..."
-  eval "use bar 1.004"; # note numeric version
-  print $@; # prints "bar version 1.004 required..."
+=head2 numify()
 
+Returns a value representing the object in a pure decimal form without
+trailing zeroes.
 
-IMPORTANT NOTE: This may mean that code which searches for a specific
-string (to determine whether a given module is available) may need to be
-changed.  It is always better to use the built-in comparison implicit in
-C<use> or C<require>, rather than manually poking at C<class->VERSION>
-and then doing a comparison yourself.
+ version->declare('v1.2')->numify;  # 1.002
+ version->parse('1.2')->numify;     # 1.2
 
-The replacement UNIVERSAL::VERSION, when used as a function, like this:
+=head2 stringify()
 
-  print $module->VERSION;
+Returns a string that is as close to the original representation as possible.
+If the original representation was a numeric literal, it will be returned the
+way perl would normally represent it in a string.  This method is used whenever
+a version object is interpolated into a string.
 
-will also exclusively return the stringified form.  See L<Stringification>
-for more details.
+ version->declare('v1.2')->stringify;    # v1.2
+ version->parse('1.200')->stringify;     # 1.200
+ version->parse(1.02_30)->stringify;     # 1.023
 
-=head1 SUBCLASSING
+=head1 EXPORTED FUNCTIONS
 
-This module is specifically designed and tested to be easily subclassed.
-In practice, you only need to override the methods you want to change, but
-you have to take some care when overriding new() (since that is where all
-of the parsing takes place).  For example, this is a perfect acceptable
-derived class:
+=head2 qv()
 
-  package myversion;
-  use base version;
-  sub new { 
-      my($self,$n)=@_;
-      my $obj;
-      # perform any special input handling here
-      $obj = $self->SUPER::new($n);
-      # and/or add additional hash elements here
-      return $obj;
-  }
-
-See also L<version::AlphaBeta> on CPAN for an alternate representation of
-version strings.
-
-B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
-function exported into the caller's namespace, a subclass of version will 
-inherit an import() function which will perform the correct magic on behalf
-of the subclass.
+This function is no longer recommended for use, but is maintained for
+compatibility with existing code.  If you do not want to have it exported
+to your namespace, use this form:
 
-=head1 EXPORT
-
-qv - Extended Version initialization operator
+  use version 0.77 ();
 
 =head1 AUTHOR
 
@@ -703,6 +358,8 @@ John Peacock E<lt>jpeacock@cpan.orgE<gt>
 
 =head1 SEE ALSO
 
+L<version::Internal>.
+
 L<perl>.
 
 =cut
index 580ad1e..8067f1a 100644 (file)
@@ -100,6 +100,8 @@ like($@, qr/Invalid version object/,
 sub BaseTests {
 
     my ($CLASS, $method, $qv_declare) = @_;
+    my $warning;
+    local $SIG{__WARN__} = sub { $warning = $_[0] };
     
     # Insert your test code below, the Test module is use()ed here so read
     # its man page ( perldoc Test ) for help writing this test script.
@@ -124,8 +126,9 @@ sub BaseTests {
     is ( "$version" , "5.005" , '5.005 eq "5.005"' );
     $version = $CLASS->$method("5.006.001");
     is ( "$version" , "5.006.001" , '5.006.001 eq v5.6.1' );
-    $version = $CLASS->$method("1.2.3_4");
-    is ( "$version" , "1.2.3_4" , 'alpha version 1.2.3_4 eq v1.2.3_4' );
+    unlike ($warning, qr/v-string without leading 'v' deprecated/, 'No leading v');
+    $version = $CLASS->$method("v1.2.3_4");
+    is ( "$version" , "v1.2.3_4" , 'alpha version 1.2.3_4 eq v1.2.3_4' );
     
     # test illegal formats
     diag "test illegal formats" unless $ENV{PERL_CORE};
@@ -141,7 +144,7 @@ sub BaseTests {
     like($@, qr/alpha without decimal/,
        "Invalid version format (alpha without decimal)");
     
-    # for this first test, just upgrade the warn() to die()
+    # for this test, upgrade the warn() to die()
     eval {
        local $SIG{__WARN__} = sub { die $_[0] };
        $version = $CLASS->$method("1.2b3");
@@ -154,8 +157,6 @@ sub BaseTests {
 
     # from here on out capture the warning and test independently
     {
-    my $warning;
-    local $SIG{__WARN__} = sub { $warning = $_[0] };
     $version = $CLASS->$method("99 and 44/100 pure");
 
     like($warning, qr/$warnregex/,
@@ -227,7 +228,7 @@ sub BaseTests {
     
     $version = $CLASS->$method("1.2.4");
     diag "numeric tests with alpha-style non-objects"
-       if $Verbose;
+       unless $ENV{PERL_CORE};
     ok ( $version > $new_version, '$version > $new_version' );
     ok ( $new_version < $version, '$new_version < $version' );
     ok ( $version != $new_version, '$version != $new_version' );
@@ -251,7 +252,7 @@ sub BaseTests {
     $version = $CLASS->$method("1.2.3.4");
     $new_version = $CLASS->$method("1.2.3_4");
     diag "tests with alpha-style objects with same subversion"
-       if $Verbose;
+       unless $ENV{PERL_CORE};
     ok ( $version > $new_version, '$version > $new_version' );
     ok ( $new_version < $version, '$new_version < $version' );
     ok ( $version != $new_version, '$version != $new_version' );
diff --git a/lib/version/Internals.pod b/lib/version/Internals.pod
new file mode 100644 (file)
index 0000000..5ff365e
--- /dev/null
@@ -0,0 +1,608 @@
+=head1 NAME
+
+version::Internal - Perl extension for Version Objects
+
+=head1 DESCRIPTION
+
+Overloaded version objects for all modern versions of Perl.  This documents
+the internal data representation and underlying code for version.pm.  See
+L<version.pod> for daily usage.  This document is only useful for users
+writing a subclass of version.pm or interested in the gory details.
+
+=head1 What IS a version
+
+For the purposes of this module, a version "number" is a sequence of
+positive integer values separated by one or more decimal points and 
+optionally a single underscore.  This corresponds to what Perl itself 
+uses for a version, as well as extending the "version as number" that 
+is discussed in the various editions of the Camel book.
+
+There are actually two distinct kinds of version objects:
+
+=over 4
+
+=item * Decimal Versions
+
+Any version which "looks like a number", see L<Decimal Versions>.  This
+also includes versions with a single decimal point and a single embedded
+underscore, see L<Decimal Alpha Versions>, even though these must be quoted
+to preserve the underscore formatting.
+
+=item * Dotted-Decimal Versions
+
+Also referred to as "Dotted-Integer", these contains more than one decimal
+point and may have an optional embedded underscore, see L<Dotted-Decimal
+Versions>.  This is what is commonly used in most open source software as
+the "external" version (the one used as part of the tag or tarfile name).
+A leading 'v' character is now required and will warn if it missing.
+
+=back
+
+Both of these methods will produce similar version objects, in that
+the default stringification will yield the version L<Normal Form> only 
+if required:
+
+  $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
+  $v  = version->new(1.002003);  # 1.002003
+  $v2 = version->new("v1.2.3");  # v1.2.3
+
+In specific, version numbers initialized as L<Decimal Versions> will
+stringify as they were originally created (i.e. the same string that was
+passed to C<new()>.  Version numbers initialized as L<Dotted-Decimal Versions>
+will be stringified as L<Normal Form>.
+
+=head2 Decimal Versions
+
+These correspond to historical versions of Perl itself prior to 5.6.0,
+as well as all other modules which follow the Camel rules for the
+$VERSION scalar.  A Decimal version is initialized with what looks like
+a floating point number.  Leading zeros B<are> significant and trailing
+zeros are implied so that a minimum of three places is maintained
+between subversions.  What this means is that any subversion (digits
+to the right of the decimal place) that contains less than three digits
+will have trailing zeros added to make up the difference, but only for
+purposes of comparison with other version objects.  For example:
+
+                                   # Prints     Equivalent to  
+  $v = version->new(      1.2);    # 1.2        v1.200.0
+  $v = version->new(     1.02);    # 1.02       v1.20.0
+  $v = version->new(    1.002);    # 1.002      v1.2.0
+  $v = version->new(   1.0023);    # 1.0023     v1.2.300
+  $v = version->new(  1.00203);    # 1.00203    v1.2.30
+  $v = version->new( 1.002003);    # 1.002003   v1.2.3
+
+All of the preceding examples are true whether or not the input value is 
+quoted.  The important feature is that the input value contains only a 
+single decimal.  See also L<Alpha Versions> for how to handle 
+
+IMPORTANT NOTE: As shown above, if your Decimal version contains more 
+than 3 significant digits after the decimal place, it will be split on 
+each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need 
+to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.  
+Any trailing zeros are ignored for mathematical comparison purposes.
+
+=head2 Dotted-Decimal Versions
+
+These are the newest form of versions, and correspond to Perl's own
+version style beginning with 5.6.0.  Starting with Perl 5.10.0,
+and most likely Perl 6, this is likely to be the preferred form.  This
+method normally requires that the input parameter be quoted, although 
+Perl's after 5.8.1 can use v-strings as a special form of quoting, but
+this is highly discouraged.
+
+Unlike L<Decimal Versions>, Dotted-Decimal Versions have more than
+a single decimal point, e.g.:
+
+                                   # Prints
+  $v = version->new( "v1.200");    # v1.200.0
+  $v = version->new("v1.20.0");    # v1.20.0
+  $v = qv("v1.2.3");               # v1.2.3
+  $v = qv("1.2.3");                # v1.2.3
+  $v = qv("1.20");                 # v1.20.0
+
+In general, Dotted-Decimal Versions permit the greatest amount of freedom
+to specify a version, whereas Decimal Versions enforce a certain
+uniformity.  See also L<New Operator> for an additional method of
+initializing version objects.
+
+Just like L<Decimal Versions>, Dotted-Decimal Versions can be used as 
+L<Alpha Versions>.
+
+=head2 Decimal Alpha Versions
+
+The one time that a Decimal version must be quoted is when a alpha form is
+used with an otherwise Decimal version (i.e. a single decimal point).  This
+is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
+versions for automatic updating purposes.  Since some developers have used
+only two significant decimal places for their non-alpha releases, the
+version object will automatically take that into account if the initializer
+is quoted.  For example Module::Example was released to CPAN with the
+following sequence of $VERSION's:
+
+  # $VERSION    Stringified
+  0.01          0.01
+  0.02          0.02
+  0.02_01       0.02_01
+  0.02_02       0.02_02
+  0.03          0.03
+  etc.
+
+The stringified form of Decimal versions will always be the same string
+that was used to initialize the version object.
+
+=head1 High level design
+
+=head2 version objects
+
+version.pm provides an overloaded version object that is designed to both 
+encapsulate the author's intended $VERSION assignment as well as make it
+completely natural to use those objects as if they were numbers (e.g. for
+comparisons).  To do this, a version object contains both the original 
+representation as typed by the author, as well as a parsed representation
+to ease comparisons.  Version objects employ L<overload> methods to
+simplify code that needs to compare, print, etc the objects.
+
+The internal structure of version objects is a blessed hash with several
+components:
+
+    bless( {
+      'original' => 'v1.2.3_4',
+      'alpha' => 1,
+      'qv' => 1,
+      'version' => [
+       1,
+       2,
+       3,
+       4
+      ]
+    }, 'version' );
+
+=over 4
+
+=item original
+
+A faithful representation of the value used to initialize this version
+object.  The only time this will not be precisely the same characters
+that exist in the source file is if a short dotted-decimal version like
+v1.2 was used (in which case it will contain 'v1.2').  This form is
+B<STRONGLY> discouraged, in that it will confuse you and your users.
+
+=item qv
+
+A boolean that denotes whether this is a decimal or dotted-decimal version.
+See L<is_qv>.
+
+=item alpha
+
+A boolean that denotes whether this is an alpha version.  NOTE: that the
+underscore can can only appear in the last position.  See L<is_alpha>.
+
+=item version
+
+An array of non-negative integers that is used for comparison purposes with
+other version objects.
+
+=back
+
+=head2 Replacement UNIVERSAL::VERSION
+
+In addition to the version objects, this modules also replaces the core
+UNIVERSAL::VERSION function with one that uses version objects for its
+comparisons.  The return from this operator is always the stringified form
+as a simple scalar (i.e. not an object), but the warning message generated
+includes either the stringified form or the normal form, depending on how
+it was called.
+
+For example:
+
+  package Foo;
+  $VERSION = 1.2;
+
+  package Bar;
+  $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted)
+
+  package main;
+  use version;
+
+  print $Foo::VERSION; # prints 1.2
+
+  print $Bar::VERSION; # prints 1.003005
+
+  eval "use foo 10";
+  print $@; # prints "foo version 10 required..."
+  eval "use foo 1.3.5; # work in Perl 5.6.1 or better
+  print $@; # prints "foo version 1.3.5 required..."
+
+  eval "use bar 1.3.6";
+  print $@; # prints "bar version 1.3.6 required..."
+  eval "use bar 1.004"; # note Decimal version
+  print $@; # prints "bar version 1.004 required..."
+
+
+IMPORTANT NOTE: This may mean that code which searches for a specific
+string (to determine whether a given module is available) may need to be
+changed.  It is always better to use the built-in comparison implicit in
+C<use> or C<require>, rather than manually poking at C<class->VERSION>
+and then doing a comparison yourself.
+
+The replacement UNIVERSAL::VERSION, when used as a function, like this:
+
+  print $module->VERSION;
+
+will also exclusively return the stringified form.  See L<Stringification>
+for more details.
+
+=head1 Usage question
+
+=head2 Using modules that use version.pm
+
+As much as possible, the version.pm module remains compatible with all
+current code.  However, if your module is using a module that has defined
+C<$VERSION> using the version class, there are a couple of things to be
+aware of.  For purposes of discussion, we will assume that we have the
+following module installed:
+
+  package Example;
+  use version;  $VERSION = qv('1.2.2');
+  ...module code here...
+  1;
+
+=over 4
+
+=item Decimal versions always work
+
+Code of the form:
+
+  use Example 1.002003;
+
+will always work correctly.  The C<use> will perform an automatic
+C<$VERSION> comparison using the floating point number given as the first
+term after the module name (e.g. above 1.002.003).  In this case, the
+installed module is too old for the requested line, so you would see an
+error like:
+
+  Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
+
+=item Dotted-Decimal version work sometimes
+
+With Perl >= 5.6.2, you can also use a line like this:
+
+  use Example 1.2.3;
+
+and it will again work (i.e. give the error message as above), even with
+releases of Perl which do not normally support v-strings (see L<What about
+v-strings> below).  This has to do with that fact that C<use> only checks
+to see if the second term I<looks like a number> and passes that to the
+replacement L<UNIVERSAL::VERSION>.  This is not true in Perl 5.005_04,
+however, so you are B<strongly encouraged> to always use a Decimal version
+in your code, even for those versions of Perl which support the Dotted-Decimal
+version.
+
+=back
+
+=head2 Object Methods
+
+Overloading has been used with version objects to provide a natural
+interface for their use.  All mathematical operations are forbidden,
+since they don't make any sense for base version objects.  Consequently,
+there is no overloaded numification available.  If you want to use a
+version object in a Decimal context for some reason, see the L<numify>
+object method.
+
+=over 4
+
+=item * New Operator
+
+Like all OO interfaces, the new() operator is used to initialize
+version objects.  One way to increment versions when programming is to
+use the CVS variable $Revision, which is automatically incremented by
+CVS every time the file is committed to the repository.
+
+In order to facilitate this feature, the following
+code can be employed:
+
+  $VERSION = version->new(qw$Revision: 2.7 $);
+
+and the version object will be created as if the following code
+were used:
+
+  $VERSION = version->new("v2.7");
+
+In other words, the version will be automatically parsed out of the
+string, and it will be quoted to preserve the meaning CVS normally
+carries for versions.  The CVS $Revision$ increments differently from
+Decimal versions (i.e. 1.10 follows 1.9), so it must be handled as if
+it were a L<Dotted-Decimal Version>.
+
+A new version object can be created as a copy of an existing version
+object, either as a class method:
+
+  $v1 = version->new(12.3);
+  $v2 = version->new($v1);
+
+or as an object method:
+
+  $v1 = version->new(12.3);
+  $v2 = $v1->new(12.3);
+
+and in each case, $v1 and $v2 will be identical.  NOTE: if you create
+a new object using an existing object like this:
+
+  $v2 = $v1->new();
+
+the new object B<will not> be a clone of the existing object.  In the
+example case, $v2 will be an empty object of the same type as $v1.
+
+=back
+
+=over 4
+
+=item * qv()
+
+An alternate way to create a new version object is through the exported
+qv() sub.  This is not strictly like other q? operators (like qq, qw),
+in that the only delimiters supported are parentheses (or spaces).  It is
+the best way to initialize a short version without triggering the floating
+point interpretation.  For example:
+
+  $v1 = qv(1.2);         # v1.2.0
+  $v2 = qv("1.2");       # also v1.2.0
+
+As you can see, either a bare number or a quoted string can usually 
+be used interchangably, except in the case of a trailing zero, which
+must be quoted to be converted properly.  For this reason, it is strongly
+recommended that all initializers to qv() be quoted strings instead of
+bare numbers.
+
+To prevent the C<qv()> function from being exported to the caller's namespace,
+either use version with a null parameter:
+
+  use version ();
+
+or just require version, like this:
+
+  require version;
+
+Both methods will prevent the import() method from firing and exporting the
+C<qv()> sub.  This is true of subclasses of version as well, see
+L<SUBCLASSING> for details.
+
+=back
+
+For the subsequent examples, the following three objects will be used:
+
+  $ver   = version->new("1.2.3.4"); # see "Quoting" below
+  $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
+  $nver  = version->new(1.002);     # see "Decimal Versions" above
+
+=over 4
+
+=item * Normal Form
+
+For any version object which is initialized with multiple decimal
+places (either quoted or if possible v-string), or initialized using
+the L<qv()> operator, the stringified representation is returned in
+a normalized or reduced form (no extraneous zeros), and with a leading 'v':
+
+  print $ver->normal;         # prints as v1.2.3.4
+  print $ver->stringify;      # ditto
+  print $ver;                 # ditto
+  print $nver->normal;        # prints as v1.2.0
+  print $nver->stringify;     # prints as 1.002, see "Stringification" 
+
+In order to preserve the meaning of the processed version, the 
+normalized representation will always contain at least three sub terms.
+In other words, the following is guaranteed to always be true:
+
+  my $newver = version->new($ver->stringify);
+  if ($newver eq $ver ) # always true
+    {...}
+
+=back
+
+=over 4
+
+=item * Numification
+
+Although all mathematical operations on version objects are forbidden
+by default, it is possible to retrieve a number which corresponds 
+to the version object through the use of the $obj->numify
+method.  For formatting purposes, when displaying a number which
+corresponds a version object, all sub versions are assumed to have
+three decimal places.  So for example:
+
+  print $ver->numify;         # prints 1.002003004
+  print $nver->numify;        # prints 1.002
+
+Unlike the stringification operator, there is never any need to append
+trailing zeros to preserve the correct version value.
+
+=back
+
+=over 4
+
+=item * Stringification
+
+The default stringification for version objects returns exactly the same
+string as was used to create it, whether you used C<new()> or C<qv()>,
+with one exception.  The sole exception is if the object was created using
+C<qv()> and the initializer did not have two decimal places or a leading
+'v' (both optional), then the stringified form will have a leading 'v'
+prepended, in order to support round-trip processing.
+
+For example:
+
+  Initialized as          Stringifies to
+  ==============          ==============
+  version->new("1.2")       1.2
+  version->new("v1.2")     v1.2
+  qv("1.2.3")               1.2.3
+  qv("v1.3.5")             v1.3.5
+  qv("1.2")                v1.2   ### exceptional case 
+
+See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
+when used as a class method.
+
+IMPORTANT NOTE: There is one exceptional cases shown in the above table
+where the "initializer" is not stringwise equivalent to the stringified
+representation.  If you use the C<qv()> operator on a version without a
+leading 'v' B<and> with only a single decimal place, the stringified output
+will have a leading 'v', to preserve the sense.  See the L<qv()> operator
+for more details.
+
+IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
+manually applying L<numify()> and L<normal()> will sometimes yield
+surprising results:
+
+  print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
+
+The reason for this is that the L<numify()> operator will turn "v1.0"
+into the equivalent string "1.000000".  Forcing the outer version object
+to L<normal()> form will display the mathematically equivalent "v1.0.0".
+
+As the example in L<new()> shows, you can always create a copy of an
+existing version object with the same value by the very compact:
+
+  $v2 = $v1->new($v1);
+
+and be assured that both C<$v1> and C<$v2> will be completely equivalent,
+down to the same internal representation as well as stringification.
+
+=back
+
+=over 4
+
+=item * Comparison operators
+
+Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
+terms (upgrading to a version object automatically).  Perl automatically
+generates all of the other comparison operators based on those two.
+In addition to the obvious equalities listed below, appending a single
+trailing 0 term does not change the value of a version for comparison
+purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
+
+For example, the following relations hold:
+
+  As Number        As String           Truth Value
+  -------------    ----------------    -----------
+  $ver >  1.0      $ver gt "1.0"       true
+  $ver <  2.5      $ver lt             true
+  $ver != 1.3      $ver ne "1.3"       true
+  $ver == 1.2      $ver eq "1.2"       false
+  $ver == 1.2.3.4  $ver eq "1.2.3.4"   see discussion below
+
+It is probably best to chose either the Decimal notation or the string
+notation and stick with it, to reduce confusion.  Perl6 version objects
+B<may> only support Decimal comparisons.  See also L<Quoting>.
+
+WARNING: Comparing version with unequal numbers of decimal points (whether
+explicitly or implicitly initialized), may yield unexpected results at
+first glance.  For example, the following inequalities hold:
+
+  version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
+  version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
+
+For this reason, it is best to use either exclusively L<Decimal Versions> or
+L<Dotted-Decimal Versions> with multiple decimal points.
+
+=back
+
+=over 4
+
+=item * Logical Operators 
+
+If you need to test whether a version object
+has been initialized, you can simply test it directly:
+
+  $vobj = version->new($something);
+  if ( $vobj )   # true only if $something was non-blank
+
+You can also test whether a version object is an L<Alpha version>, for
+example to prevent the use of some feature not present in the main
+release:
+
+  $vobj = version->new("1.2_3"); # MUST QUOTE
+  ...later...
+  if ( $vobj->is_alpha )       # True
+
+=back
+
+=head2 Quoting
+
+Because of the nature of the Perl parsing and tokenizing routines,
+certain initialization values B<must> be quoted in order to correctly
+parse as the intended version, especially when using the L<qv()> operator.
+In all cases, a floating point number passed to version->new() will be
+identically converted whether or not the value itself is quoted.  This is
+not true for L<qv()>, however, when trailing zeros would be stripped on
+an unquoted input, which would result in a very different version object.
+
+In addition, in order to be compatible with earlier Perl version styles,
+any use of versions of the form 5.006001 will be translated as v5.6.1.  
+In other words, a version with a single decimal point will be parsed as
+implicitly having three digits between subversions, but only for internal
+comparison purposes.
+
+The complicating factor is that in bare numbers (i.e. unquoted), the
+underscore is a legal Decimal character and is automatically stripped
+by the Perl tokenizer before the version code is called.  However, if
+a number containing one or more decimals and an underscore is quoted, i.e.
+not bare, that is considered a L<Alpha Version> and the underscore is
+significant.
+
+If you use a mathematic formula that resolves to a floating point number,
+you are dependent on Perl's conversion routines to yield the version you
+expect.  You are pretty safe by dividing by a power of 10, for example,
+but other operations are not likely to be what you intend.  For example:
+
+  $VERSION = version->new((qw$Revision: 1.4)[1]/10);
+  print $VERSION;          # yields 0.14
+  $V2 = version->new(100/9); # Integer overflow in decimal number
+  print $V2;               # yields something like 11.111.111.100
+
+Perl 5.8.1 and beyond will be able to automatically quote v-strings but
+that is not possible in earlier versions of Perl.  In other words:
+
+  $version = version->new("v2.5.4");  # legal in all versions of Perl
+  $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
+
+=head1 SUBCLASSING
+
+This module is specifically designed and tested to be easily subclassed.
+In practice, you only need to override the methods you want to change, but
+you have to take some care when overriding new() (since that is where all
+of the parsing takes place).  For example, this is a perfect acceptable
+derived class:
+
+  package myversion;
+  use base version;
+  sub new { 
+      my($self,$n)=@_;
+      my $obj;
+      # perform any special input handling here
+      $obj = $self->SUPER::new($n);
+      # and/or add additional hash elements here
+      return $obj;
+  }
+
+See also L<version::AlphaBeta> on CPAN for an alternate representation of
+version strings.
+
+B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
+function exported into the caller's namespace, a subclass of version will 
+inherit an import() function which will perform the correct magic on behalf
+of the subclass.
+
+=head1 EXPORT
+
+qv - Dotted-Decimal Version initialization operator
+
+=head1 AUTHOR
+
+John Peacock E<lt>jpeacock@cpan.orgE<gt>
+
+=head1 SEE ALSO
+
+L<perl>.
+
+=cut