.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Debbugs::Versions 3pm" .TH Debbugs::Versions 3pm "2018-02-26" "perl v5.26.1" "User Contributed Perl Documentation" .\" 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" Debbugs::Versions \- debbugs version information processing .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Debbugs::Versions module provides generic support functions for the implementation of version tracking in debbugs. .PP Complex organizations, such as Debian, require the tracking of bugs in multiple versions of packages. The versioning scheme is frequently branched: for example, a security update announced by an upstream developer will be packaged as-is for the unstable distribution while a minimal backport is made to the stable distribution. In order to report properly on the bugs open in each distribution, debbugs must be aware of the structure of the version tree for each package. .PP Gathering the version data is beyond the scope of this module: in the case of Debian it is carried out by mechanical analysis of package changelogs. Debbugs::Versions takes version data for a package generated by this or any other means, merges it into a tree structure, and allows the user to perform queries based on supplied data about the versions in which bugs have been found and the versions in which they have been fixed. .SH "DATA FORMAT" .IX Header "DATA FORMAT" The data format looks like this (backslashes are not actually there, and indicate continuation lines): .PP .Vb 9 \& 1.5.4 1.5.0 1.5\-iwj.0.4 1.5\-iwj.0.3 1.5\-iwj.0.2 1.5\-iwj.0.1 1.4.0 1.3.14 \e \& 1.3.13 1.3.12 1.3.11 1.3.10 ... \& 1.4.1.6 1.4.1.5 1.4.1.4 1.4.1.3 1.4.1.2 1.4.1.1 1.4.1 1.4.0.31 1.4.0.30 \e \& 1.4.0.29 1.4.0.28 1.4.0.27 1.4.0.26.0.1 1.4.0.26 1.4.0.25 1.4.0.24 \e \& 1.4.0.23.2 1.4.0.23.1 1.4.0.23 1.4.0.22 1.4.0.21 1.4.0.20 1.4.0.19 \e \& 1.4.0.18 1.4.0.17 1.4.0.16 1.4.0.15 1.4.0.14 1.4.0.13 1.4.0.12 \e \& 1.4.0.11 1.4.0.10 1.4.0.9 1.4.0.8 1.4.0.7 1.4.0.6 1.4.0.5 1.4.0.4 \e \& 1.4.0.3 1.4.0.2 1.4.0.1 1.4.0 \e \& 1.4.0.35 1.4.0.34 1.4.0.33 1.4.0.32 1.4.0.31 .Ve .SH "METHODS" .IX Header "METHODS" .IP "new" 8 .IX Item "new" Constructs a Debbugs::Versions object. The argument is a reference to a version comparison function, which must be usable by Perl's built-in \f(CW\*(C`sort\*(C'\fR function. .IP "isancestor" 8 .IX Item "isancestor" Takes two arguments, \f(CW\*(C`ancestor\*(C'\fR and \f(CW\*(C`descendant\*(C'\fR. Returns true if and only if \f(CW\*(C`ancestor\*(C'\fR is a version on which \f(CW\*(C`descendant\*(C'\fR is based according to the version data supplied to this object. (As a degenerate case, this relation is reflexive: a version is considered to be an ancestor of itself.) .Sp This method is expected mainly to be used internally by the \f(CW\*(C`merge\*(C'\fR method. .IP "leaves" 8 .IX Item "leaves" Find the leaves of the version tree, i.e. those versions with no descendants. .Sp This method is mainly for internal use. .IP "merge" 8 .IX Item "merge" Merges one branch of version data into this object. This branch takes the form of a list of versions, each of which is to be considered as based on the next in the list. .IP "load" 8 .IX Item "load" Loads version data from the filehandle passed as the argument. Each line of input is expected to represent one branch, with versions separated by whitespace. .IP "save" 8 .IX Item "save" Outputs the version tree represented by this object to the filehandle passed as the argument. The format is the same as that expected by the \f(CW\*(C`load\*(C'\fR method. .IP "buggy" 8 .IX Item "buggy" Takes three arguments, \f(CW\*(C`version\*(C'\fR, \f(CW\*(C`found\*(C'\fR, and \f(CW\*(C`fixed\*(C'\fR. Returns true if and only if \f(CW\*(C`version\*(C'\fR is based on or equal to a version in the list referenced by \f(CW\*(C`found\*(C'\fR, and not based on or equal to one referenced by \&\f(CW\*(C`fixed\*(C'\fR. .Sp \&\f(CW\*(C`buggy\*(C'\fR attempts to cope with found and fixed versions not in the version tree by simply checking whether any fixed versions are recorded in the event that nothing is known about any of the found versions. .IP "allstates" 8 .IX Item "allstates" Takes two arguments, \f(CW\*(C`found\*(C'\fR and \f(CW\*(C`fixed\*(C'\fR, which are interpreted as in \&\*(L"buggy\*(R". Efficiently returns the state of the bug at every known version, in the form of a hash from versions to states (as returned by \*(L"buggy\*(R"). If you pass a third argument, \f(CW\*(C`interested\*(C'\fR, this method will stop after determining the state of the bug at all the versions listed therein. .Sp Whether this is faster than calling \*(L"buggy\*(R" for each version you're interested in is not altogether clear, and depends rather strongly on the number of known and interested versions.