lib/version.pm

   1 #!/usr/local/bin/perl -w
   2 package version;
   3
   4 use 5.005_03;
   5 use strict;
   6
   7 require DynaLoader;
   8 use vars qw(@ISA $VERSION $CLASS);
   9
  10 @ISA = qw(DynaLoader);
  11
  12 $VERSION = (qw$Revision: 2.3 $)[1]/10;
  13
  14 $CLASS = 'version';
  15
  16 local $^W; # shut up the 'redefined' warning for UNIVERSAL::VERSION
  17 bootstrap version if $] < 5.009;
  18
  19 # Preloaded methods go here.
  20
  21 1;
  22 __END__
  23
  24 =head1 NAME
  25
  26 version - Perl extension for Version Objects
  27
  28 =head1 SYNOPSIS
  29
  30   use version;
  31   $version = new version "12.2.1"; # must be quoted!
  32   print $version;               # 12.2.1
  33   print $version->numify;       # 12.002001
  34   if ( $version > 12.2 )        # true
  35
  36   $vstring = new version qw(v1.2); # must be quoted!
  37   print $vstring;               # 1.2
  38
  39   $betaver = new version "1.2_3"; # must be quoted!
  40   print $betaver;               # 1.2_3
  41
  42   $perlver = new version "5.005_03"; # must be quoted!
  43   print $perlver;               # 5.5.30
  44
  45 =head1 DESCRIPTION
  46
  47 Overloaded version objects for all versions of Perl.  This module
  48 implements all of the features of version objects which will be part
  49 of Perl 5.10.0 except automatic v-string handling.  See L<"Quoting">.
  50
  51 =head2 What IS a version
  52
  53 For the purposes of this module, a version "number" is a sequence of
  54 positive integral values separated by decimal points and optionally a
  55 single underscore.  This corresponds to what Perl itself uses for a
  56 version, as well as extending the "version as number" that is discussed
  57 in the various editions of the Camel book.
  58
  59 However, in order to be compatible with earlier Perl version styles,
  60 any use of versions of the form 5.006001 will be translated as 5.6.1,
  61 In other words, a version with a single decimal place will be parsed
  62 as implicitly having three places between subversion.
  63
  64 Any value passed to the new() operator will be parsed only so far as it
  65 contains a numeric, decimal, or underscore character.  So, for example:
  66
  67   $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0
  68   $v2 = new version "something"; # $v2 == "" and $v2->numify == 0
  69
  70 NOTE: it is strongly recommended that version objects only be created
  71 with numeric values based on the different types of versions in this
  72 documentation, see L<"Types of Versions Objects">.  That way, there is
  73 no confusion about what constitutes the version.
  74
  75 =head2 Object Methods
  76
  77 Overloading has been used with version objects to provide a natural
  78 interface for their use.  All mathematical operations are forbidden,
  79 since they don't make any sense for versions.  For the subsequent
  80 examples, the following two objects will be used:
  81
  82   $ver  = new version "1.2.3"; # see "Quoting" below
  83   $beta = new version "1.2_3"; # see "Beta versions" below
  84
  85 =item * Stringification - Any time a version object is used as a string,
  86 a stringified representation is returned in reduced form (no extraneous
  87 zeros):
  88
  89   print $ver->stringify;      # prints 1.2.3
  90   print $ver;                 # same thing
  91
  92 =item * Numification - although all mathematical operations on version
  93 objects are forbidden by default, it is possible to retrieve a number
  94 which roughly corresponds to the version object through the use of the
  95 $obj->numify method.  For formatting purposes, when displaying a number
  96 which corresponds a version object, all sub versions are assumed to have
  97 three decimal places.  So for example:
  98
  99   print $ver->numify;         # prints 1.002003
 100
 101 =item * Comparison operators - Both cmp and <=> operators perform the
 102 same comparison between terms (upgrading to a version object
 103 automatically).  Perl automatically generates all of the other comparison
 104 operators based on those two.  For example, the following relations hold:
 105
 106   As Number       As String       Truth Value
 107   ---------       ------------    -----------
 108   $ver >  1.0     $ver gt "1.0"      true
 109   $ver <  2.5     $ver lt            true
 110   $ver != 1.3     $ver ne "1.3"      true
 111   $ver == 1.2     $ver eq "1.2"      false
 112   $ver == 1.2.3   $ver eq "1.2.3"    see discussion below
 113   $ver == v1.2.3  $ver eq "v1.2.3"   ditto
 114
 115 In versions of Perl prior to the 5.9.0 development releases, it is not
 116 permitted to use bare v-strings in either form, due to the nature of Perl's
 117 parsing operation.  After that version (and in the stable 5.10.0 release),
 118 v-strings can be used with version objects without problem, see L<"Quoting">
 119 for more discussion of this topic.  In the case of the last two lines of
 120 the table above, only the string comparison will be true; the numerical
 121 comparison will test false.  However, you can do this:
 122
 123   $ver == "1.2.3" or $ver == "v1.2.3"   # both true
 124
 125 even though you are doing a "numeric" comparison with a "string" value.
 126 It is probably best to chose either the numeric notation or the string
 127 notation and stick with it, to reduce confusion.  See also L<"Quoting">.
 128
 129 =head2 Quoting
 130
 131 Because of the nature of the Perl parsing and tokenizing routines,
 132 you should always quote the parameter to the new() operator/method.  The
 133 exact notation is vitally important to correctly determine the version
 134 that is requested.  You don't B<have> to quote the version parameter,
 135 but you should be aware of what Perl is likely to do in those cases.
 136
 137 If you use a mathematic formula that resolves to a floating point number,
 138 you are dependent on Perl's conversion routines to yield the version you
 139 expect.  You are pretty safe by dividing by a power of 10, for example,
 140 but other operations are not likely to be what you intend.  For example:
 141
 142   $VERSION = new version (qw$Revision: 1.4)[1]/10;
 143   print $VERSION;          # yields 0.14
 144   $V2 = new version 100/9; # Integer overflow in decimal number
 145   print $V2;               # yields 11_1285418553
 146
 147 You B<can> use a bare number, if you only have a major and minor version,
 148 since this should never in practice yield a floating point notation
 149 error.  For example:
 150
 151   $VERSION = new version  10.2;  # almost certainly ok
 152   $VERSION = new version "10.2"; # guaranteed ok
 153
 154 Perl 5.9.0 and beyond will be able to automatically quote v-strings
 155 (which may become the recommended notation), but that is not possible in
 156 earlier versions of Perl.  In other words:
 157
 158   $version = new version "v2.5.4";  # legal in all versions of Perl
 159   $newvers = new version v2.5.4;    # legal only in Perl > 5.9.0
 160
 161
 162 =head2 Types of Versions Objects
 163
 164 There are three basic types of Version Objects:
 165
 166 =item * Ordinary versions - These are the versions that normal
 167 modules will use.  Can contain as many subversions as required.
 168 In particular, those using RCS/CVS can use one of the following:
 169
 170   $VERSION = new version (qw$Revision: 2.3 $)[1]; # all Perls
 171   $VERSION = new version qw$Revision: 2.3 $[1];   # Perl >= 5.6.0
 172
 173 and the current RCS Revision for that file will be inserted
 174 automatically.  If the file has been moved to a branch, the
 175 Revision will have three or more elements; otherwise, it will
 176 have only two.  This allows you to automatically increment
 177 your module version by using the Revision number from the primary
 178 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
 179
 180 =item * Beta versions - For module authors using CPAN, the
 181 convention has been to note unstable releases with an underscore
 182 in the version string, see L<CPAN>.  Beta releases will test as being
 183 newer than the more recent stable release, and less than the next
 184 stable release.  For example:
 185
 186   $betaver = new version "12.3_1"; # must quote
 187
 188 obeys the relationship
 189
 190   12.3 < $betaver < 12.4
 191
 192 As a matter of fact, if is also true that
 193
 194   12.3.0 < $betaver < 12.3.1
 195
 196 where the subversion is identical but the beta release is less than
 197 the non-beta release.
 198
 199 =item * Perl-style versions - an exceptional case is versions that
 200 were only used by Perl releases prior to 5.6.0.  If a version
 201 string contains an underscore immediately followed by a zero followed
 202 by a non-zero number, the version is processed according to the rules
 203 described in L<perldelta/Improved Perl version numbering system>
 204 released with Perl 5.6.0.  As an example:
 205
 206   $perlver = new version "5.005_03";
 207
 208 is interpreted, not as a beta release, but as the version 5.5.30,  NOTE
 209 that the major and minor versions are unchanged but the subversion is
 210 multiplied by 10, since the above was implicitly read as 5.005.030.
 211 There are modules currently on CPAN which may fall under of this rule, so
 212 module authors are urged to pay close attention to what version they are
 213 specifying.
 214
 215 =head2 Replacement UNIVERSAL::VERSION
 216
 217 In addition to the version objects, this modules also replaces the core
 218 UNIVERSAL::VERSION function with one that uses version objects for its
 219 comparisons.  So, for example, with all existing versions of Perl,
 220 something like the following pseudocode would fail:
 221
 222         package vertest;
 223         $VERSION = 0.45;
 224
 225         package main;
 226         use vertest 0.5;
 227
 228 even though those versions are meant to be read as 0.045 and 0.005
 229 respectively.  The UNIVERSAL::VERSION replacement function included
 230 with this module changes that behavior so that it will B<not> fail.
 231
 232 =head1 EXPORT
 233
 234 None by default.
 235
 236 =head1 AUTHOR
 237
 238 John Peacock E<lt>jpeacock@rowman.comE<gt>
 239
 240 =head1 SEE ALSO
 241
 242 L<perl>.
 243
 244 =cut