.\" Automatically generated by Pod::Man 4.10 (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
..
.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
.\"
.\" 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 "Lintian::DepMap 3"
.TH Lintian::DepMap 3 "2020-02-26" "Lintian v2.55.0~bpo10+1" "Debian Package Checker"
.\" 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"
Lintian::DepMap \- Dependencies map/tree creator
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Lintian::DepMap;
\&
\&    my $map = Lintian::DepMap\->new;
\&
\&    # know about A:
\&    $map\->add(\*(AqA\*(Aq);
\&    # B depends on A:
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&
\&    # prints \*(AqA\*(Aq:
\&    print $map\->selectable;
\&
\&    # indicate we are working on \*(AqA\*(Aq (optional):
\&    $map\->select(\*(AqA\*(Aq);
\&    # do \*(AqA\*(Aq ... work work work
\&
\&    # we are done with A:
\&    $map\->satisfy(\*(AqA\*(Aq);
\&    # prints \*(AqB\*(Aq:
\&    print $map\->selectable;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Lintian::DepMap is a simple dependencies map/tree creator and \*(L"resolver\*(R".
It works by creating a tree based on the indicated dependencies and destroying
it to resolve it.
.PP
Note: in the below documentation a \f(CW\*(C`node\*(C'\fR means a node name; no internal
reference is ever returned and therefore never accepted as a parameter.
.IP "\fBnew()\fR" 4
.IX Item "new()"
Creates a new Lintian::DepMap object and returns a reference to it.
.IP "\fBinitialise()\fR" 4
.IX Item "initialise()"
Ensure, by reconstructing if necessary, the map's status is the initial.
That is, partially or fully resolved maps can be restored to its original
state by calling this method.
.Sp
This can be useful when the same map will be used multiple times.
.Sp
E.g.
.Sp
.Vb 6
\&    $map\->add(\*(AqA\*(Aq);
\&    $map\->satisfy(\*(AqA\*(Aq);
\&    # prints nothing
\&    print $map\->selectable;
\&    $map\->initialise;
\&    print $map\->selectable;
.Ve
.IP "add(node[, dependency[, dependency[, ...]]])" 4
.IX Item "add(node[, dependency[, dependency[, ...]]])"
Adds the given \f(CW\*(C`node\*(C'\fR to the map marking any second or more parameter as its
dependencies. E.g.
.Sp
.Vb 4
\&    # A has no dependency:
\&    $map\->add(\*(AqA\*(Aq);
\&    # B depends on A:
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
.Ve
.IP "addp(node[, prefix, dependency[, dependency[, ...]]])" 4
.IX Item "addp(node[, prefix, dependency[, dependency[, ...]]])"
Adds the given \f(CW\*(C`node\*(C'\fR to the map marking any third or more parameters,
after prefixing them with \f(CW\*(C`prefix\*(C'\fR, as its dependencies. E.g.
.Sp
.Vb 5
\&    # pA and pB have no dependency:
\&    $map\->add(\*(AqpA\*(Aq);
\&    $map\->add(\*(AqpA\*(Aq);
\&    # C depends on pA and pB:
\&    $map\->addp(\*(AqC\*(Aq, \*(Aqp\*(Aq, \*(AqA\*(Aq, \*(AqB\*(Aq);
.Ve
.IP "satisfy(node)" 4
.IX Item "satisfy(node)"
Indicates that the given \f(CW\*(C`node\*(C'\fR has been satisfied/done.
.Sp
The given \f(CW\*(C`node\*(C'\fR is no longer marked as being selected, if it was;
all of its branches that have no other parent are now \fBselectable()\fR
and all the references to \f(CW\*(C`node\*(C'\fR are deleted except the one from
the \fBknown()\fR list.
.Sp
E.g.
.Sp
.Vb 8
\&    # A has no dependencies:
\&    $map\->add(\*(AqA\*(Aq);
\&    # B depends on A:
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # we work on A, and we are done:
\&    $map\->satisfy(\*(AqA\*(Aq);
\&    # B is now available:
\&    $map\->selectable(\*(AqB\*(Aq);
.Ve
.Sp
\&\fBNote\fR: shall the requested node not exist this method \fBdie()\fRs.
.IP "done(node)" 4
.IX Item "done(node)"
Returns whether the given \f(CW\*(C`node\*(C'\fR has been satisfied/done.
.Sp
E.g.
.Sp
.Vb 4
\&    # A has no dependencies:
\&    $map\->add(\*(AqA\*(Aq);
\&    # we work on A, and we are done:
\&    $map\->satisfy(\*(AqA\*(Aq);
\&
\&    print "A is done!"
\&        if ($map\->done(\*(AqA\*(Aq));
.Ve
.IP "unlink(node)" 4
.IX Item "unlink(node)"
Removes all references to the given \f(CW\*(C`node\*(C'\fR except for the entry in the
\&\fBknown()\fR table.
.Sp
\&\fB\s-1IMPORTANT\s0\fR: since all references are deleted it is possible that a node
that depended on \f(CW\*(C`node\*(C'\fR may become available even when it was not expected
to.
.Sp
\&\fB\s-1IMPORTANT\s0\fR: this operation can \fBnot\fR be reversed by the means of
\&\fBinitialise()\fR.
.Sp
E.g.
.Sp
.Vb 7
\&    $map\->add(\*(AqA\*(Aq);
\&    # Prints A
\&    print $map\->selectable;
\&    # we later notice we don\*(Aqt want A
\&    $map\->unlink(\*(AqA\*(Aq);
\&    # Prints nothing
\&    print $map\->selectable;
.Ve
.Sp
\&\fBNote\fR: shall the requested node not exist this method \fBdie()\fRs.
.IP "select(node)" 4
.IX Item "select(node)"
Marks the given \f(CW\*(C`node\*(C'\fR as selected to indicate that whatever it represents
is being worked on. Note: this operation is not atomic.
.Sp
E.g.
.Sp
.Vb 9
\&    $map\->add(\*(AqA\*(Aq);
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    while($map\->pending) {
\&        for my $node ($map\->selectable) {
\&            $map\->select($node);
\&            # work work work
\&            $map\->satisfy($node);
\&        }
\&    }
.Ve
.IP "selectable([node])" 4
.IX Item "selectable([node])"
If a \f(CW\*(C`node\*(C'\fR is specified returns \s-1TRUE\s0 if it can be \fBselect()\fRed.
.Sp
\&\fBNote\fR: already \fBselect()\fRed nodes cannot be re-selected,
i.e. if the given \f(CW\*(C`node\*(C'\fR has already been selected this function will
return \s-1FALSE\s0; or any selected item will be omitted from the returned array,
in case no \f(CW\*(C`node\*(C'\fR is specified.
.IP "selected([node])" 4
.IX Item "selected([node])"
If a \f(CW\*(C`node\*(C'\fR is specified returns \s-1TRUE\s0 if it is has been selected,
\&\s-1FALSE\s0 otherwise.
.Sp
If no \f(CW\*(C`node\*(C'\fR is specified it returns an array with the name of all the
nodes that have been \fBselect()\fRed but not yet satisfied.
.Sp
E.g.
.Sp
.Vb 6
\&    # We are going to work on A
\&    $map\->select(\*(AqA\*(Aq);
\&    # Returns true
\&    $map\->selected(\*(AqA\*(Aq);
\&    # Prints A
\&    print $map\->selected;
.Ve
.IP "\fBselectAll()\fR" 4
.IX Item "selectAll()"
\&\fBselect()\fRs all the \fBselectable()\fR nodes.
.IP "parents(node)" 4
.IX Item "parents(node)"
Return an array with the name of the parent nodes for the given \f(CW\*(C`node\*(C'\fR.
.Sp
E.g.
.Sp
.Vb 4
\&    $map\->add(\*(AqA\*(Aq);
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # Prints \*(AqA\*(Aq
\&    print $map\->parents(\*(AqB\*(Aq);
.Ve
.Sp
\&\fBNote\fR: shall the requested node not exist this method \fBdie()\fRs.
.IP "ancestors(node)" 4
.IX Item "ancestors(node)"
Return an array with unique names of all ancestral nodes for the given \f(CW\*(C`node\*(C'\fR.
.Sp
E.g.
.Sp
.Vb 4
\&    $map\->add(\*(AqA\*(Aq);
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # Prints \*(AqA\*(Aq
\&    print $map\->ancestors(\*(AqB\*(Aq);
.Ve
.Sp
\&\fBNote\fR: shall the requested node not exist this method \fBdie()\fRs.
.IP "non_unique_ancestors(node)" 4
.IX Item "non_unique_ancestors(node)"
Return an array with non-unique names of all ancestral nodes for the given \f(CW\*(C`node\*(C'\fR.
.Sp
E.g.
.Sp
.Vb 4
\&    $map\->add(\*(AqA\*(Aq);
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # Prints \*(AqA\*(Aq
\&    print $map\->ancestors(\*(AqB\*(Aq);
.Ve
.Sp
\&\fBNote\fR: shall the requested node not exist this method \fBdie()\fRs.
.IP "\fBpending()\fR" 4
.IX Item "pending()"
Return the number of nodes that can or have already been selected. E.g.
.Sp
.Vb 9
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # prints 1:
\&    print $map\->pending;
\&    $map\->select(\*(AqA\*(Aq);
\&    # prints 1:
\&    print $map\->pending;
\&    $map\->satisfy(\*(AqA\*(Aq);
\&    # prints 1 (\*(AqB\*(Aq is now available):
\&    print $map\->pending;
.Ve
.IP "\fBknown()\fR" 4
.IX Item "known()"
Return an array containing the names of nodes that were added. E.g.
.Sp
.Vb 6
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # prints \*(AqB\*(Aq:
\&    print $map\->known;
\&    $map\->add(\*(AqA\*(Aq);
\&    # prints \*(AqA\*(Aq and \*(AqB\*(Aq:
\&    print $map\->known;
.Ve
.IP "known(\s-1NODE\s0)" 4
.IX Item "known(NODE)"
Returns a truth value if \s-1NODE\s0 is known or \f(CW\*(C`undef\*(C'\fR otherwise.
.IP "\fBmissing()\fR" 4
.IX Item "missing()"
Return an array containing the names of nodes that were not added but that
another node depended on it. E.g.
.Sp
.Vb 10
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # prints \*(AqA\*(Aq:
\&    print $map\->missing;
\&    $map\->add(\*(AqA\*(Aq);
\&    # prints nothing:
\&    print $map\->missing;
\&    # this also works; A depends on \*(AqZ\*(Aq:
\&    $map\->add(\*(AqA\*(Aq, \*(AqZ\*(Aq);
\&    # but now this prints \*(AqZ\*(Aq:
\&    print $map\->missing;
.Ve
.IP "circular(['deep'])" 4
.IX Item "circular(['deep'])"
Returns an array of nodes that have a circular dependency.
.Sp
E.g.
.Sp
.Vb 4
\&    $map\->add(\*(AqA\*(Aq, \*(AqB\*(Aq);
\&    $map\->add(\*(AqB\*(Aq, \*(AqA\*(Aq);
\&    # Prints A and B
\&    print $map\->circular;
.Ve
.Sp
\&\fBNote\fR: since recursive/deep circular dependencies detection is a bit
more resource expensive it is not the default.
.Sp
.Vb 7
\&    $map\->add(\*(AqA\*(Aq, \*(AqB\*(Aq);
\&    $map\->add(\*(AqB\*(Aq, \*(AqC\*(Aq);
\&    $map\->add(\*(AqC\*(Aq, \*(AqA\*(Aq);
\&    # No deep/recursive scanning is performed, prints nothing
\&    print $map\->circular;
\&    # deep scan, prints \*(AqA, B, C\*(Aq
\&    print $map\->circular(\*(Aqdeep\*(Aq);
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Raphael Geissert <atomo64@gmail.com> for Lintian.