.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dpkg::Version 3perl"
.TH Dpkg::Version 3perl "2023-05-11" "1.21.22" "libdpkg-perl"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dpkg::Version \- handling and comparing dpkg\-style version numbers
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Dpkg::Version module provides pure-Perl routines to compare
dpkg-style version numbers (as used in Debian packages) and also
an object oriented interface overriding perl operators
to do the right thing when you compare Dpkg::Version object between
them.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$v = Dpkg::Version\->new($version, %opts)" 4
.el .IP "\f(CW$v\fR = Dpkg::Version\->new($version, \f(CW%opts\fR)" 4
.IX Item "$v = Dpkg::Version->new($version, %opts)"
Create a new Dpkg::Version object corresponding to the version indicated in
the string (scalar) \f(CW$version\fR. By default it will accepts any string
and consider it as a valid version. If you pass the option \*(L"check => 1\*(R",
it will return undef if the version is invalid (see version_check for
details).
.Sp
You can always call \f(CW$v\fR\->\fBis_valid()\fR later on to verify that the version is
valid.
.IP "boolean evaluation" 4
.IX Item "boolean evaluation"
When the Dpkg::Version object is used in a boolean evaluation (for example
in \*(L"if ($v)\*(R" or \*(L"$v ? \e\*(R"$v\e\*(L" : 'default'\*(R") it returns true if the version
stored is valid ($v\->\fBis_valid()\fR) and false otherwise.
.Sp
\&\fBNotice\fR: Between dpkg 1.15.7.2 and 1.19.1 this overload used to return
\&\f(CW$v\fR\->\fBas_string()\fR if \f(CW$v\fR\->\fBis_valid()\fR, a breaking change in behavior that caused
\&\*(L"0\*(R" versions to be evaluated as false. To catch any possibly intended code
that relied on those semantics, this overload will emit a warning with
category \*(L"Dpkg::Version::semantic_change::overload::bool\*(R" until dpkg 1.20.x.
Once fixed, or for already valid code the warning can be quiesced with
.Sp
.Vb 2
\&  no if $Dpkg::Version::VERSION ge \*(Aq1.02\*(Aq,
\&     warnings => qw(Dpkg::Version::semantic_change::overload::bool);
.Ve
.Sp
added after the \f(CW\*(C`use Dpkg::Version\*(C'\fR.
.ie n .IP "$v\->\fBis_valid()\fR" 4
.el .IP "\f(CW$v\fR\->\fBis_valid()\fR" 4
.IX Item "$v->is_valid()"
Returns true if the version is valid, false otherwise.
.ie n .IP "$v\->\fBepoch()\fR, $v\->\fBversion()\fR, $v\->\fBrevision()\fR" 4
.el .IP "\f(CW$v\fR\->\fBepoch()\fR, \f(CW$v\fR\->\fBversion()\fR, \f(CW$v\fR\->\fBrevision()\fR" 4
.IX Item "$v->epoch(), $v->version(), $v->revision()"
Returns the corresponding part of the full version string.
.ie n .IP "$v\->\fBis_native()\fR" 4
.el .IP "\f(CW$v\fR\->\fBis_native()\fR" 4
.IX Item "$v->is_native()"
Returns true if the version is native, false if it has a revision.
.ie n .IP "$v1 <=> $v2, $v1 < $v2, $v1 <= $v2, $v1 > $v2, $v1 >= $v2" 4
.el .IP "\f(CW$v1\fR <=> \f(CW$v2\fR, \f(CW$v1\fR < \f(CW$v2\fR, \f(CW$v1\fR <= \f(CW$v2\fR, \f(CW$v1\fR > \f(CW$v2\fR, \f(CW$v1\fR >= \f(CW$v2\fR" 4
.IX Item "$v1 <=> $v2, $v1 < $v2, $v1 <= $v2, $v1 > $v2, $v1 >= $v2"
Numerical comparison of various versions numbers. One of the two operands
needs to be a Dpkg::Version, the other one can be anything provided that
its string representation is a version number.
.ie n .IP """$v"", $v\->\fBas_string()\fR, $v\->as_string(%options)" 4
.el .IP "``$v'', \f(CW$v\fR\->\fBas_string()\fR, \f(CW$v\fR\->as_string(%options)" 4
.IX Item "$v, $v->as_string(), $v->as_string(%options)"
Accepts an optional option hash reference, affecting the string conversion.
.Sp
Options:
.RS 4
.IP "omit_epoch (defaults to 0)" 8
.IX Item "omit_epoch (defaults to 0)"
Omit the epoch, if present, in the output string.
.IP "omit_revision (defaults to 0)" 8
.IX Item "omit_revision (defaults to 0)"
Omit the revision, if present, in the output string.
.RE
.RS 4
.Sp
Returns the string representation of the version number.
.RE
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
All the functions are exported by default.
.ie n .IP "version_compare($a, $b)" 4
.el .IP "version_compare($a, \f(CW$b\fR)" 4
.IX Item "version_compare($a, $b)"
Returns \-1 if \f(CW$a\fR is earlier than \f(CW$b\fR, 0 if they are equal and 1 if \f(CW$a\fR
is later than \f(CW$b\fR.
.Sp
If \f(CW$a\fR or \f(CW$b\fR are not valid version numbers, it dies with an error.
.ie n .IP "version_compare_relation($a, $rel, $b)" 4
.el .IP "version_compare_relation($a, \f(CW$rel\fR, \f(CW$b\fR)" 4
.IX Item "version_compare_relation($a, $rel, $b)"
Returns the result (0 or 1) of the given comparison operation. This
function is implemented on top of \fBversion_compare()\fR.
.Sp
Allowed values for \f(CW$rel\fR are the exported constants \s-1REL_GT, REL_GE,
REL_EQ, REL_LE, REL_LT.\s0 Use \fBversion_normalize_relation()\fR if you
have an input string containing the operator.
.ie n .IP "$rel = version_normalize_relation($rel_string)" 4
.el .IP "\f(CW$rel\fR = version_normalize_relation($rel_string)" 4
.IX Item "$rel = version_normalize_relation($rel_string)"
Returns the normalized constant of the relation \f(CW$rel\fR (a value
among \s-1REL_GT, REL_GE, REL_EQ, REL_LE\s0 and \s-1REL_LT\s0). Supported
relations names in input are: \*(L"gt\*(R", \*(L"ge\*(R", \*(L"eq\*(R", \*(L"le\*(R", \*(L"lt\*(R", \*(L">>\*(R", \*(L">=\*(R",
\&\*(L"=\*(R", \*(L"<=\*(R", \*(L"<<\*(R". \*(L">\*(R" and \*(L"<\*(R" are also supported but should not be used as
they are obsolete aliases of \*(L">=\*(R" and \*(L"<=\*(R".
.ie n .IP "version_compare_string($a, $b)" 4
.el .IP "version_compare_string($a, \f(CW$b\fR)" 4
.IX Item "version_compare_string($a, $b)"
String comparison function used for comparing non-numerical parts of version
numbers. Returns \-1 if \f(CW$a\fR is earlier than \f(CW$b\fR, 0 if they are equal and 1 if \f(CW$a\fR
is later than \f(CW$b\fR.
.Sp
The \*(L"~\*(R" character always sort lower than anything else. Digits sort lower
than non-digits. Among remaining characters alphabetic characters (A\-Z, a\-z)
sort lower than the other ones. Within each range, the \s-1ASCII\s0 decimal value
of the character is used to sort between characters.
.ie n .IP "version_compare_part($a, $b)" 4
.el .IP "version_compare_part($a, \f(CW$b\fR)" 4
.IX Item "version_compare_part($a, $b)"
Compare two corresponding sub-parts of a version number (either upstream
version or debian revision).
.Sp
Each parameter is split by \fBversion_split_digits()\fR and resulting items
are compared together. As soon as a difference happens, it returns \-1 if
\&\f(CW$a\fR is earlier than \f(CW$b\fR, 0 if they are equal and 1 if \f(CW$a\fR is later than \f(CW$b\fR.
.ie n .IP "@items = version_split_digits($version)" 4
.el .IP "\f(CW@items\fR = version_split_digits($version)" 4
.IX Item "@items = version_split_digits($version)"
Splits a string in items that are each entirely composed either
of digits or of non-digits. For instance for \*(L"1.024~beta1+svn234\*(R" it would
return (\*(L"1\*(R", \*(L".\*(R", \*(L"024\*(R", \*(L"~beta\*(R", \*(L"1\*(R", \*(L"+svn\*(R", \*(L"234\*(R").
.ie n .IP "($ok, $msg) = version_check($version)" 4
.el .IP "($ok, \f(CW$msg\fR) = version_check($version)" 4
.IX Item "($ok, $msg) = version_check($version)"
.PD 0
.ie n .IP "$ok = version_check($version)" 4
.el .IP "\f(CW$ok\fR = version_check($version)" 4
.IX Item "$ok = version_check($version)"
.PD
Checks the validity of \f(CW$version\fR as a version number. Returns 1 in \f(CW$ok\fR
if the version is valid, 0 otherwise. In the latter case, \f(CW$msg\fR
contains a description of the problem with the \f(CW$version\fR scalar.
.SH "CHANGES"
.IX Header "CHANGES"
.SS "Version 1.03 (dpkg 1.20.0)"
.IX Subsection "Version 1.03 (dpkg 1.20.0)"
Remove deprecation warning from semantic change in 1.02.
.SS "Version 1.02 (dpkg 1.19.1)"
.IX Subsection "Version 1.02 (dpkg 1.19.1)"
Semantic change: bool evaluation semantics restored to their original behavior.
.SS "Version 1.01 (dpkg 1.17.0)"
.IX Subsection "Version 1.01 (dpkg 1.17.0)"
New argument: Accept an options argument in \f(CW$v\fR\->\fBas_string()\fR.
.PP
New method: \f(CW$v\fR\->\fBis_native()\fR.
.SS "Version 1.00 (dpkg 1.15.6)"
.IX Subsection "Version 1.00 (dpkg 1.15.6)"
Mark the module as public.