X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fversion.pod;h=dee652dbedf76052904dd8d6e4ce591f60dd9b4a;hb=ad91da88822a061453a454578ec2246dd493ffdd;hp=a8742033fe5c1cbd6080bbac0b243df4e0cf8e08;hpb=34ba6322b644154d55680c95808981776852ae24;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/version.pod b/lib/version.pod index a874203..dee652d 100644 --- a/lib/version.pod +++ b/lib/version.pod @@ -21,7 +21,7 @@ version - Perl extension for Version Objects =head1 DESCRIPTION -Overloaded version objects for all versions of Perl. This module +Overloaded version objects for all modern versions of Perl. This module implements all of the features of version objects which will be part of Perl 5.10.0. @@ -74,6 +74,54 @@ 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; + +=over 4 + +=item Numeric 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 Extended 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 numeric version +in your code, even for those versions of Perl which support the extended +version. + +=back + =head2 What IS a version For the purposes of this module, a version "number" is a sequence of @@ -110,10 +158,11 @@ 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 + $v2 = version->new("1.2.3"); # v1.2.3 In specific, version numbers initialized as L will -stringify in Numeric form. Version numbers initialized as L +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 @@ -129,11 +178,11 @@ 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.200 v1.200.0 - $v = version->new( 1.02); # 1.020 v1.20.0 + $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.002300 v1.2.300 - $v = version->new( 1.00203); # 1.002030 v1.2.30 + $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 @@ -161,7 +210,7 @@ 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("v1.2.3"); # v1.2.3 $v = qv("1.2.3"); # v1.2.3 $v = qv("1.20"); # v1.20.0 @@ -185,22 +234,24 @@ is quoted. For example Module::Example was released to CPAN with the following sequence of $VERSION's: # $VERSION Stringified - 0.01 0.010 - 0.02 0.020 - 0.02_01 0.02_0100 - 0.02_02 0.02_0200 - 0.03 0.030 + 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. -As you can see, the version object created from the values in the first -column may contain a trailing 0, but will otherwise be both mathematically -equivalent and sorts alpha-numerically as would be expected. +The stringified form of numeric versions will always be the same string +that was used to initialize the version object. =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. +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 @@ -236,9 +287,15 @@ object, either as a class method: 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(); -and in each case, $v1 and $v2 will be identical. +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 @@ -261,6 +318,19 @@ 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: @@ -317,25 +387,25 @@ trailing zeros to preserve the correct version value. =item * Stringification -In order to mirror as much as possible the existing behavior of ordinary -$VERSION scalars, the stringification operation will display differently, -depending on whether the version was initialized as a L -or L. +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. -What this means in practice is that if the normal CPAN and Camel rules are -followed ($VERSION is a floating point number with no more than 3 decimal -points), the stringified output will be exactly the same as the numified -output. There will be no visible difference, although the internal -representation will be different, and the L will -function using the internal coding. +For example: -If a version object is initialized using a L form, then -the stringified form will be the L. The $obj->normal -operation can always be used to produce the L, even if the -version was originally a L. + 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 - print $ver->stringify; # prints v1.2.3.4 - print $nver->stringify; # prints 1.002 +See also L, as this also returns the stringified form +when used as a class method. =back @@ -451,13 +521,26 @@ leading 'v' character (also bare). For example: $vs1 = 1.2.3; # encoded as \1\2\3 $vs2 = v1.2; # encoded as \1\2 -However, the use of v-strings to initialize version objects with this -module is only possible with Perl 5.8.1 or better (which contain special -code to enable it). Their use 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. +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. + +If you insist on using bare v-strings with Perl > 5.6.0, be aware of the +following limitations: + +1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses, +based on some characteristics of v-strings. You B use a three part +version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful. +2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl +core to be magical, which means that the version.pm code can automatically +determine whether the v-string encoding was used. + +3) In all cases, a version created using v-strings will have a stringified +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 @@ -494,14 +577,9 @@ obeys the relationship 12.03 < $alphaver < 12.04 Alpha versions with a single decimal point will be treated exactly as if -they were L, for parsing purposes. The stringification for -alpha versions with a single decimal point may seem surprising, since any -trailing zeros will visible. For example, the above $alphaver will print as - - 12.03_0100 - -which is mathematically equivalent and ASCII sorts exactly the same as -without the trailing zeros. +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. Alpha versions with more than a single decimal point will be treated exactly as if they were L, and will display without any @@ -510,13 +588,15 @@ trailing (or leading) zeros, in the L form. For example, $newver = version->new("12.3.1_1"); print $newver; # v12.3.1_1 +=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 numified form, -and the warning message generated includes both the numified and normal -forms (for clarity). +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: @@ -533,20 +613,29 @@ For example: print $Bar::VERSION; # prints 1.003005 - eval "use CGI 10"; # some far future release - print $@; # prints "CGI version 10 (10.0.0) required..." + 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 numeric 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. +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 numified form. Technically, the -$module->VERSION function returns a string (PV) that can be converted to a -number following the normal Perl rules, when used in a numeric context. +will also exclusively return the stringified form. See L +for more details. =head1 SUBCLASSING @@ -570,14 +659,10 @@ derived class: See also L on CPAN for an alternate representation of version strings. -B the L operator is not a class method and will not be inherited -in the same way as the other methods. L will always return an object of -type L and not an object in the derived class. If you need to -have L return an object in your derived class, add something like this: - - *::qv = sub { return bless version::qv(shift), __PACKAGE__ }; - -as seen in the test file F. +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