--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "version::Internals 3"
+.TH version::Internals 3 "2009-10-23" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+version::Internal \- Perl extension for Version Objects
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Overloaded version objects for all modern versions of Perl. This documents
+the internal data representation and underlying code for version.pm. See
+version.pod for daily usage. This document is only useful for users
+writing a subclass of version.pm or interested in the gory details.
+.SH "What IS a version"
+.IX Header "What IS a version"
+For the purposes of this module, a version \*(L"number\*(R" 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 \*(L"version as number\*(R" that
+is discussed in the various editions of the Camel book.
+.PP
+There are actually two distinct kinds of version objects:
+.IP "* Decimal Versions" 4
+.IX Item "Decimal Versions"
+Any version which \*(L"looks like a number\*(R", see \*(L"Decimal Versions\*(R". This
+also includes versions with a single decimal point and a single embedded
+underscore, see \*(L"Decimal Alpha Versions\*(R", even though these must be quoted
+to preserve the underscore formatting.
+.IP "* Dotted-Decimal Versions" 4
+.IX Item "Dotted-Decimal Versions"
+Also referred to as \*(L"Dotted\-Integer\*(R", these contains more than one decimal
+point and may have an optional embedded underscore, see \*(L"Dotted\-Decimal Versions\*(R". This is what is commonly used in most open source software as
+the \*(L"external\*(R" 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.
+.PP
+Both of these methods will produce similar version objects, in that
+the default stringification will yield the version \*(L"Normal Form\*(R" only
+if required:
+.PP
+.Vb 3
+\& $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
+.Ve
+.PP
+In specific, version numbers initialized as \*(L"Decimal Versions\*(R" will
+stringify as they were originally created (i.e. the same string that was
+passed to \f(CW\*(C`new()\*(C'\fR. Version numbers initialized as \*(L"Dotted\-Decimal Versions\*(R"
+will be stringified as \*(L"Normal Form\*(R".
+.Sh "Decimal Versions"
+.IX Subsection "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
+\&\f(CW$VERSION\fR scalar. A Decimal version is initialized with what looks like
+a floating point number. Leading zeros \fBare\fR 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:
+.PP
+.Vb 7
+\& # 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
+.Ve
+.PP
+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\*(R" for how to handle
+.PP
+\&\s-1IMPORTANT\s0 \s-1NOTE:\s0 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.
+.Sh "Dotted-Decimal Versions"
+.IX Subsection "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.
+.PP
+Unlike \*(L"Decimal Versions\*(R", Dotted-Decimal Versions have more than
+a single decimal point, e.g.:
+.PP
+.Vb 6
+\& # 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
+.Ve
+.PP
+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\*(R" for an additional method of
+initializing version objects.
+.PP
+Just like \*(L"Decimal Versions\*(R", Dotted-Decimal Versions can be used as
+\&\*(L"Alpha Versions\*(R".
+.Sh "Decimal Alpha Versions"
+.IX Subsection "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 \s-1CPAN\s0 releases, where \s-1CPAN\s0 or \s-1CPANPLUS\s0 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 \s-1CPAN\s0 with the
+following sequence of \f(CW$VERSION\fR's:
+.PP
+.Vb 7
+\& # $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.
+.Ve
+.PP
+The stringified form of Decimal versions will always be the same string
+that was used to initialize the version object.
+.SH "High level design"
+.IX Header "High level design"
+.Sh "version objects"
+.IX Subsection "version objects"
+version.pm provides an overloaded version object that is designed to both
+encapsulate the author's intended \f(CW$VERSION\fR 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 overload methods to
+simplify code that needs to compare, print, etc the objects.
+.PP
+The internal structure of version objects is a blessed hash with several
+components:
+.PP
+.Vb 11
+\& bless( {
+\& 'original' => 'v1.2.3_4',
+\& 'alpha' => 1,
+\& 'qv' => 1,
+\& 'version' => [
+\& 1,
+\& 2,
+\& 3,
+\& 4
+\& ]
+\& }, 'version' );
+.Ve
+.IP "original" 4
+.IX 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
+\&\fB\s-1STRONGLY\s0\fR discouraged, in that it will confuse you and your users.
+.IP "qv" 4
+.IX Item "qv"
+A boolean that denotes whether this is a decimal or dotted-decimal version.
+See is_qv.
+.IP "alpha" 4
+.IX Item "alpha"
+A boolean that denotes whether this is an alpha version. \s-1NOTE:\s0 that the
+underscore can can only appear in the last position. See is_alpha.
+.IP "version" 4
+.IX Item "version"
+An array of non-negative integers that is used for comparison purposes with
+other version objects.
+.Sh "Replacement \s-1UNIVERSAL::VERSION\s0"
+.IX Subsection "Replacement UNIVERSAL::VERSION"
+In addition to the version objects, this modules also replaces the core
+\&\s-1UNIVERSAL::VERSION\s0 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.
+.PP
+For example:
+.PP
+.Vb 2
+\& package Foo;
+\& $VERSION = 1.2;
+.Ve
+.PP
+.Vb 2
+\& package Bar;
+\& $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted)
+.Ve
+.PP
+.Vb 2
+\& package main;
+\& use version;
+.Ve
+.PP
+.Vb 1
+\& print $Foo::VERSION; # prints 1.2
+.Ve
+.PP
+.Vb 1
+\& print $Bar::VERSION; # prints 1.003005
+.Ve
+.PP
+.Vb 4
+\& 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..."
+.Ve
+.PP
+.Vb 4
+\& 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..."
+.Ve
+.PP
+\&\s-1IMPORTANT\s0 \s-1NOTE:\s0 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
+\&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR, rather than manually poking at \f(CW\*(C`class\-\*(C'\fR\s-1VERSION\s0>
+and then doing a comparison yourself.
+.PP
+The replacement \s-1UNIVERSAL::VERSION\s0, when used as a function, like this:
+.PP
+.Vb 1
+\& print $module\->VERSION;
+.Ve
+.PP
+will also exclusively return the stringified form. See Stringification
+for more details.
+.SH "Usage question"
+.IX Header "Usage question"
+.Sh "Using modules that use version.pm"
+.IX Subsection "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
+\&\f(CW$VERSION\fR 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:
+.PP
+.Vb 4
+\& package Example;
+\& use version; $VERSION = qv('1.2.2');
+\& ...module code here...
+\& 1;
+.Ve
+.IP "Decimal versions always work" 4
+.IX Item "Decimal versions always work"
+Code of the form:
+.Sp
+.Vb 1
+\& use Example 1.002003;
+.Ve
+.Sp
+will always work correctly. The \f(CW\*(C`use\*(C'\fR will perform an automatic
+\&\f(CW$VERSION\fR 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:
+.Sp
+.Vb 1
+\& Example version 1.002003 (v1.2.3) required\-\-this is only version 1.002002 (v1.2.2)...
+.Ve
+.IP "Dotted-Decimal version work sometimes" 4
+.IX Item "Dotted-Decimal version work sometimes"
+With Perl >= 5.6.2, you can also use a line like this:
+.Sp
+.Vb 1
+\& use Example 1.2.3;
+.Ve
+.Sp
+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\*(R" below). This has to do with that fact that \f(CW\*(C`use\*(C'\fR only checks
+to see if the second term \fIlooks like a number\fR and passes that to the
+replacement \s-1UNIVERSAL::VERSION\s0. This is not true in Perl 5.005_04,
+however, so you are \fBstrongly encouraged\fR to always use a Decimal version
+in your code, even for those versions of Perl which support the Dotted-Decimal
+version.
+.Sh "Object Methods"
+.IX Subsection "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 numify
+object method.
+.IP "* New Operator" 4
+.IX Item "New Operator"
+Like all \s-1OO\s0 interfaces, the \fInew()\fR operator is used to initialize
+version objects. One way to increment versions when programming is to
+use the \s-1CVS\s0 variable \f(CW$Revision\fR, which is automatically incremented by
+\&\s-1CVS\s0 every time the file is committed to the repository.
+.Sp
+In order to facilitate this feature, the following
+code can be employed:
+.Sp
+.Vb 1
+\& $VERSION = version\->new(qw$Revision: 2.7 $);
+.Ve
+.Sp
+and the version object will be created as if the following code
+were used:
+.Sp
+.Vb 1
+\& $VERSION = version\->new("v2.7");
+.Ve
+.Sp
+In other words, the version will be automatically parsed out of the
+string, and it will be quoted to preserve the meaning \s-1CVS\s0 normally
+carries for versions. The \s-1CVS\s0 \f(CW$Revision\fR$ 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\*(R".
+.Sp
+A new version object can be created as a copy of an existing version
+object, either as a class method:
+.Sp
+.Vb 2
+\& $v1 = version\->new(12.3);
+\& $v2 = version\->new($v1);
+.Ve
+.Sp
+or as an object method:
+.Sp
+.Vb 2
+\& $v1 = version\->new(12.3);
+\& $v2 = $v1\->new(12.3);
+.Ve
+.Sp
+and in each case, \f(CW$v1\fR and \f(CW$v2\fR will be identical. \s-1NOTE:\s0 if you create
+a new object using an existing object like this:
+.Sp
+.Vb 1
+\& $v2 = $v1\->new();
+.Ve
+.Sp
+the new object \fBwill not\fR be a clone of the existing object. In the
+example case, \f(CW$v2\fR will be an empty object of the same type as \f(CW$v1\fR.
+.IP "* \fIqv()\fR" 4
+.IX Item "qv()"
+An alternate way to create a new version object is through the exported
+\&\fIqv()\fR 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:
+.Sp
+.Vb 2
+\& $v1 = qv(1.2); # v1.2.0
+\& $v2 = qv("1.2"); # also v1.2.0
+.Ve
+.Sp
+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 \fIqv()\fR be quoted strings instead of
+bare numbers.
+.Sp
+To prevent the \f(CW\*(C`qv()\*(C'\fR function from being exported to the caller's namespace,
+either use version with a null parameter:
+.Sp
+.Vb 1
+\& use version ();
+.Ve
+.Sp
+or just require version, like this:
+.Sp
+.Vb 1
+\& require version;
+.Ve
+.Sp
+Both methods will prevent the \fIimport()\fR method from firing and exporting the
+\&\f(CW\*(C`qv()\*(C'\fR sub. This is true of subclasses of version as well, see
+\&\s-1SUBCLASSING\s0 for details.
+.PP
+For the subsequent examples, the following three objects will be used:
+.PP
+.Vb 3
+\& $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
+.Ve
+.IP "* Normal Form" 4
+.IX 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 \fIqv()\fR operator, the stringified representation is returned in
+a normalized or reduced form (no extraneous zeros), and with a leading 'v':
+.Sp
+.Vb 5
+\& 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"
+.Ve
+.Sp
+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:
+.Sp
+.Vb 3
+\& my $newver = version\->new($ver\->stringify);
+\& if ($newver eq $ver ) # always true
+\& {...}
+.Ve
+.IP "* Numification" 4
+.IX 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 \f(CW$obj\fR\->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:
+.Sp
+.Vb 2
+\& print $ver\->numify; # prints 1.002003004
+\& print $nver\->numify; # prints 1.002
+.Ve
+.Sp
+Unlike the stringification operator, there is never any need to append
+trailing zeros to preserve the correct version value.
+.IP "* Stringification" 4
+.IX Item "Stringification"
+The default stringification for version objects returns exactly the same
+string as was used to create it, whether you used \f(CW\*(C`new()\*(C'\fR or \f(CW\*(C`qv()\*(C'\fR,
+with one exception. The sole exception is if the object was created using
+\&\f(CW\*(C`qv()\*(C'\fR 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.
+.Sp
+For example:
+.Sp
+.Vb 7
+\& 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
+.Ve
+.Sp
+See also \s-1UNIVERSAL::VERSION\s0, as this also returns the stringified form
+when used as a class method.
+.Sp
+\&\s-1IMPORTANT\s0 \s-1NOTE:\s0 There is one exceptional cases shown in the above table
+where the \*(L"initializer\*(R" is not stringwise equivalent to the stringified
+representation. If you use the \f(CW\*(C`qv()\*(C'\fR operator on a version without a
+leading 'v' \fBand\fR with only a single decimal place, the stringified output
+will have a leading 'v', to preserve the sense. See the \fIqv()\fR operator
+for more details.
+.Sp
+\&\s-1IMPORTANT\s0 \s-1NOTE\s0 2: Attempting to bypass the normal stringification rules by
+manually applying \fInumify()\fR and \fInormal()\fR will sometimes yield
+surprising results:
+.Sp
+.Vb 1
+\& print version\->new(version\->new("v1.0")\->numify)\->normal; # v1.0.0
+.Ve
+.Sp
+The reason for this is that the \fInumify()\fR operator will turn \*(L"v1.0\*(R"
+into the equivalent string \*(L"1.000000\*(R". Forcing the outer version object
+to \fInormal()\fR form will display the mathematically equivalent \*(L"v1.0.0\*(R".
+.Sp
+As the example in \fInew()\fR shows, you can always create a copy of an
+existing version object with the same value by the very compact:
+.Sp
+.Vb 1
+\& $v2 = $v1\->new($v1);
+.Ve
+.Sp
+and be assured that both \f(CW$v1\fR and \f(CW$v2\fR will be completely equivalent,
+down to the same internal representation as well as stringification.
+.IP "* Comparison operators" 4
+.IX Item "Comparison operators"
+Both \f(CW\*(C`cmp\*(C'\fR and \f(CW\*(C`<=>\*(C'\fR 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 \*(L"v1.2\*(R" and \*(L"1.2.0\*(R" will compare as identical.
+.Sp
+For example, the following relations hold:
+.Sp
+.Vb 7
+\& 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
+.Ve
+.Sp
+It is probably best to chose either the Decimal notation or the string
+notation and stick with it, to reduce confusion. Perl6 version objects
+\&\fBmay\fR only support Decimal comparisons. See also Quoting.
+.Sp
+\&\s-1WARNING:\s0 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:
+.Sp
+.Vb 2
+\& 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
+.Ve
+.Sp
+For this reason, it is best to use either exclusively \*(L"Decimal Versions\*(R" or
+\&\*(L"Dotted\-Decimal Versions\*(R" with multiple decimal points.
+.IP "* Logical Operators" 4
+.IX Item "Logical Operators"
+If you need to test whether a version object
+has been initialized, you can simply test it directly:
+.Sp
+.Vb 2
+\& $vobj = version\->new($something);
+\& if ( $vobj ) # true only if $something was non\-blank
+.Ve
+.Sp
+You can also test whether a version object is an \*(L"Alpha version\*(R", for
+example to prevent the use of some feature not present in the main
+release:
+.Sp
+.Vb 3
+\& $vobj = version\->new("1.2_3"); # MUST QUOTE
+\& ...later...
+\& if ( $vobj\->is_alpha ) # True
+.Ve
+.Sh "Quoting"
+.IX Subsection "Quoting"
+Because of the nature of the Perl parsing and tokenizing routines,
+certain initialization values \fBmust\fR be quoted in order to correctly
+parse as the intended version, especially when using the \fIqv()\fR operator.
+In all cases, a floating point number passed to version\->\fInew()\fR will be
+identically converted whether or not the value itself is quoted. This is
+not true for \fIqv()\fR, however, when trailing zeros would be stripped on
+an unquoted input, which would result in a very different version object.
+.PP
+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.
+.PP
+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\*(R" and the underscore is
+significant.
+.PP
+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:
+.PP
+.Vb 4
+\& $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
+.Ve
+.PP
+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:
+.PP
+.Vb 2
+\& $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
+.Ve
+.SH "SUBCLASSING"
+.IX Header "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 \fInew()\fR (since that is where all
+of the parsing takes place). For example, this is a perfect acceptable
+derived class:
+.PP
+.Vb 10
+\& 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;
+\& }
+.Ve
+.PP
+See also version::AlphaBeta on \s-1CPAN\s0 for an alternate representation of
+version strings.
+.PP
+\&\fB\s-1NOTE:\s0\fR Although the 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 \fIimport()\fR function which will perform the correct magic on behalf
+of the subclass.
+.SH "EXPORT"
+.IX Header "EXPORT"
+qv \- Dotted-Decimal Version initialization operator
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+John Peacock <jpeacock@cpan.org>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perl.
projects / catagits/Gitalist.git / blobdiff