From: John Peacock Date: Mon, 27 Jul 2009 22:21:12 +0000 (-0400) Subject: Final release of version-0.77 for inclusion in 5.10.1 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=692a467c73edbe4bbd38beb2374d1bc7d6cec77d;p=p5sagit%2Fp5-mst-13.2.git Final release of version-0.77 for inclusion in 5.10.1 --- diff --git a/lib/version.pod b/lib/version.pod index 7f85ecb..090b596 100644 --- a/lib/version.pod +++ b/lib/version.pod @@ -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 or L -and not mix them together. While this is I, it is very -confusing to the average user. - -If you intend to use L, you are strongly encouraged -to use the L 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 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 below). This has to do with that fact that C only checks -to see if the second term I and passes that to the -replacement L. This is not true in Perl 5.005_04, -however, so you are B 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. This also covers versions with a single decimal point and -a single embedded underscore, see L, 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. 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 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 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 will -stringify as they were originally created (i.e. the same string that was -passed to C. Version numbers initialized as L -will be stringified as L. - -=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 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 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, 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 for an additional method of -initializing version objects. +See L for further information. -Just like L, Extended Versions can be used as -L. +=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 -object method. - -=over 4 +B: 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. - -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 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 a dotted-decimal version -=over 4 + use version 0.77; our $VERSION = version->declare("v1.2.3"); -=item * qv() +The C method always creates dotted-decimal version objects. When +used in a module, you B 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 or +L 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: 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 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 sub. This is true of subclasses of version as well, see -L 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 instead of declare. See the L +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 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 operator, the stringified representation is returned in -a normalized or reduced form (no extraneous zeros), and with a leading 'v': +=head2 How to C 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 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 or C, -with one exception. The sole exception is if the object was created using -C 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 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, as this also returns the stringified form -when used as a class method. +Version objects overload the C and C<< E=E >> 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 operator on a version without a -leading 'v' B with only a single decimal place, the stringified output -will have a leading 'v', to preserve the sense. See the L 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 and L 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. 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 operator will turn "v1.0" -into the equivalent string "1.000000". Forcing the outer version object -to L form will display the mathematically equivalent "v1.0.0". - -As the example in L 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 and C=E> 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 only support numeric comparisons. See also L. +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 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 or -L 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, 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 be quoted in order to correctly -parse as the intended version, especially when using the L 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, 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 and the underscore is -significant. +parse as the intended version, especially when using the L or +L methods. While you do not have to quote decimal numbers when +creating version objects, it is always safe to quote B 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 will be be exactly what comes B 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 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 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. - -=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. 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.) 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, 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, and will display without any -trailing (or leading) zeros, in the L 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 or C, rather than manually poking at CVERSION> -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 -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 on CPAN for an alternate representation of -version strings. - -B Although the L 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 Ejpeacock@cpan.orgE =head1 SEE ALSO +L. + L. =cut diff --git a/lib/version.t b/lib/version.t index 580ad1e..8067f1a 100644 --- a/lib/version.t +++ b/lib/version.t @@ -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 index 0000000..5ff365e --- /dev/null +++ b/lib/version/Internals.pod @@ -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 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. This +also includes versions with a single decimal point and a single embedded +underscore, see L, 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. 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 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 will +stringify as they were originally created (i.e. the same string that was +passed to C. Version numbers initialized as L +will be stringified as L. + +=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 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 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, 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 for an additional method of +initializing version objects. + +Just like L, Dotted-Decimal Versions can be used as +L. + +=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 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 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. + +=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. + +=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 or C, rather than manually poking at CVERSION> +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 +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 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 below). This has to do with that fact that C only checks +to see if the second term I and passes that to the +replacement L. This is not true in Perl 5.005_04, +however, so you are B 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 +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. + +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 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 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 sub. This is true of subclasses of version as well, see +L 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 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 or C, +with one exception. The sole exception is if the object was created using +C 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, 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 operator on a version without a +leading 'v' B with only a single decimal place, the stringified output +will have a leading 'v', to preserve the sense. See the L operator +for more details. + +IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by +manually applying L and L 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 operator will turn "v1.0" +into the equivalent string "1.000000". Forcing the outer version object +to L form will display the mathematically equivalent "v1.0.0". + +As the example in L 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 and C=E> 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 only support Decimal comparisons. See also L. + +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 or +L 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, 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 be quoted in order to correctly +parse as the intended version, especially when using the L 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, 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 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 on CPAN for an alternate representation of +version strings. + +B Although the L 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 Ejpeacock@cpan.orgE + +=head1 SEE ALSO + +L. + +=cut