.\" 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::Relation 3" .TH Lintian::Relation 3 "2021-02-01" "Lintian v2.104.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::Relation \- Lintian operations on dependencies and relationships .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& my $depends = Lintian::Relation\->new(\*(Aqfoo | bar, baz\*(Aq); \& print "yes\en" if $depends\->implies(\*(Aqbaz\*(Aq); \& print "no\en" if $depends\->implies(\*(Aqfoo\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides functions for parsing and evaluating package relationship fields such as Depends and Recommends for binary packages and Build-Depends for source packages. It parses a relationship into an internal format and can then answer questions such as \*(L"does this dependency require that a given package be installed\*(R" or \*(L"is this relationship a superset of another relationship.\*(R" .PP A dependency line is viewed as a predicate formula. The comma separator means \*(L"and\*(R", and the alternatives separator means \*(L"or\*(R". A bare package name is the predicate \*(L"a package of this name is available\*(R". A package name with a version clause is the predicate \*(L"a package of this name that satisfies this version clause is available.\*(R" Architecture restrictions, as specified in Policy for build dependencies, are supported and also checked in the implication logic unless the \fBnew_noarch()\fR constructor is used. With that constructor, architecture restrictions are ignored. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .IP "new(\s-1RELATION\s0)" 4 .IX Item "new(RELATION)" Creates a new Lintian::Relation object corresponding to the parsed relationship \s-1RELATION.\s0 This object can then be used to ask questions about that relationship. \s-1RELATION\s0 may be \f(CW\*(C`undef\*(C'\fR or the empty string, in which case the returned Lintian::Relation object is empty (always satisfied). .IP "parse_element" 4 .IX Item "parse_element" .PD 0 .IP "new_norestriction(\s-1RELATION\s0)" 4 .IX Item "new_norestriction(RELATION)" .PD Creates a new Lintian::Relation object corresponding to the parsed relationship \s-1RELATION,\s0 ignoring architecture restrictions and restriction lists. This should be used in cases where we only care if a dependency is present in some cases and we don't want to require that the architectures match (such as when checking for proper build dependencies, since if there are architecture constraints the maintainer is doing something beyond Lintian's ability to analyze) or that the restrictions list match (Lintian can't handle dependency implications with build profiles yet). \s-1RELATION\s0 may be \f(CW\*(C`undef\*(C'\fR or the empty string, in which case the returned Lintian::Relation object is empty (always satisfied). .IP "new_noarch(\s-1RELATION\s0)" 4 .IX Item "new_noarch(RELATION)" An alias for new_norestriction. .IP "and(\s-1RELATION, ...\s0)" 4 .IX Item "and(RELATION, ...)" Creates a new Lintian::Relation object produced by \s-1AND\s0'ing all the relations together. Semantically it is the similar to: .Sp .Vb 1 \& Lintian::Relation\->new (join (\*(Aq, \*(Aq, @relations)) .Ve .Sp Except it can avoid some overhead and it works if some of the elements are Lintian::Relation objects already. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" .IP "\fBduplicates()\fR" 4 .IX Item "duplicates()" Returns a list of duplicated elements within the relation object. Each element of the returned list will be a reference to an anonymous array holding a set of relations considered duplicates of each other. Two relations are considered duplicates if one implies the other, meaning that if one relationship is satisfied, the other is necessarily satisfied. This relationship does not have to be commutative: the opposite implication may not hold. .IP "\fBrestriction_less()\fR" 4 .IX Item "restriction_less()" Returns a restriction-less variant of this relation (or this relation object if it has no restrictions). .IP "implies(\s-1RELATION\s0)" 4 .IX Item "implies(RELATION)" Returns true if the relationship implies \s-1RELATION,\s0 meaning that if the Lintian::Relation object is satisfied, \s-1RELATION\s0 will always be satisfied. \&\s-1RELATION\s0 may be either a string or another Lintian::Relation object. .Sp By default, architecture restrictions are honored in \s-1RELATION\s0 if it is a string. If architecture restrictions should be ignored in \s-1RELATION,\s0 create a Lintian::Relation object with \fBnew_noarch()\fR and pass that in as \&\s-1RELATION\s0 instead of the string. .IP "implies_element" 4 .IX Item "implies_element" .PD 0 .IP "implies_array" 4 .IX Item "implies_array" .IP "implies_inverse(\s-1RELATION\s0)" 4 .IX Item "implies_inverse(RELATION)" .PD Returns true if the relationship implies that \s-1RELATION\s0 is certainly false, meaning that if the Lintian::Relation object is satisfied, \s-1RELATION\s0 cannot be satisfied. \s-1RELATION\s0 may be either a string or another Lintian::Relation object. .Sp As with \fBimplies()\fR, by default, architecture restrictions are honored in \&\s-1RELATION\s0 if it is a string. If architecture restrictions should be ignored in \s-1RELATION,\s0 create a Lintian::Relation object with \fBnew_noarch()\fR and pass that in as \s-1RELATION\s0 instead of the string. .IP "implies_element_inverse" 4 .IX Item "implies_element_inverse" .PD 0 .IP "implies_array_inverse" 4 .IX Item "implies_array_inverse" .IP "\fBunparse()\fR" 4 .IX Item "unparse()" .PD Returns the textual form of a relationship. This converts the internal form back into the textual representation and returns that, not the original argument, so the spacing is standardized. Returns undef on internal failures (such as an object in an unexpected format). .IP "matches (REGEX[, \s-1WHAT\s0])" 4 .IX Item "matches (REGEX[, WHAT])" Check if one of the predicates in this relation matches \s-1REGEX.\s0 \s-1WHAT\s0 determines what is tested against \s-1REGEX\s0 and if not given, defaults to \&\s-1VISIT_PRED_NAME.\s0 .Sp This method will return a truth value if \s-1REGEX\s0 matches at least one predicate or clause (as defined by the \s-1WHAT\s0 parameter \- see below). .Sp \&\s-1NOTE:\s0 Often \*(L"implies\*(R" (or \*(L"implies_inverse\*(R") is a better choice than this method. This method should generally only be used when checking for a \*(L"pattern\*(R" package (e.g. phpapi\-[\ed\ew+]+). .Sp \&\s-1WHAT\s0 can be one of: .RS 4 .IP "\s-1VISIT_PRED_NAME\s0" 4 .IX Item "VISIT_PRED_NAME" Match \s-1REGEX\s0 against the package name in each predicate (i.e. version and architecture constrains are ignored). Each predicate is tested in isolation. As an example: .Sp .Vb 3 \& my $rel = Lintian::Relation\->new (\*(Aqsomepkg | pkg\-0 (>= 1)\*(Aq); \& # Will match (version is ignored) \& $rel\->matches (qr/^pkg\-\ed$/, VISIT_PRED_NAME); .Ve .IP "\s-1VISIT_PRED_FULL\s0" 4 .IX Item "VISIT_PRED_FULL" Match \s-1REGEX\s0 against the full (normalized) predicate (i.e. including version and architecture). Each predicate is tested in isolation. As an example: .Sp .Vb 2 \& my $vrel = Lintian::Relation\->new (\*(Aqsomepkg | pkg\-0 (>= 1)\*(Aq); \& my $uvrel = Lintian::Relation\->new (\*(Aqsomepkg | pkg\-0\*(Aq); \& \& # Will NOT match (does not match with version) \& $vrel\->matches (qr/^pkg\-\ed$/, VISIT_PRED_FULL); \& # Will match (this relation does not have a version) \& $uvrel\->matches (qr/^pkg\-\ed$/, VISIT_PRED_FULL); \& \& # Will match (but only because there is a version) \& $vrel\->matches (qr/^pkg\-\ed \e(.*\e)$/, VISIT_PRED_FULL); \& # Will NOT match (there is no version in the relation) \& $uvrel\->matches (qr/^pkg\-\ed \e(.*\e)$/, VISIT_PRED_FULL); .Ve .IP "\s-1VISIT_OR_CLAUSE_FULL\s0" 4 .IX Item "VISIT_OR_CLAUSE_FULL" Match \s-1REGEX\s0 against the full (normalized) \s-1OR\s0 clause. Each predicate will have both version and architecture constrains present. As an example: .Sp .Vb 3 \& my $vpred = Lintian::Relation\->new (\*(Aqpkg\-0 (>= 1)\*(Aq); \& my $orrel = Lintian::Relation\->new (\*(Aqsomepkg | pkg\-0 (>= 1)\*(Aq); \& my $rorrel = Lintian::Relation\->new (\*(Aqpkg\-0 (>= 1) | somepkg\*(Aq); \& \& # Will match \& $vrel\->matches (qr/^pkg\-\ed(?: \e([^\e)]\e))?$/, VISIT_OR_CLAUSE_FULL); \& # These Will NOT match (does not match the "|" and the "somepkg" part) \& $orrel\->matches (qr/^pkg\-\ed(?: \e([^\e)]\e))?$/, VISIT_OR_CLAUSE_FULL); \& $rorrel\->matches (qr/^pkg\-\ed(?: \e([^\e)]\e))?$/, VISIT_OR_CLAUSE_FULL); .Ve .RE .RS 4 .RE .IP "visit (CODE[, \s-1FLAGS\s0])" 4 .IX Item "visit (CODE[, FLAGS])" Visit clauses or predicates of this relation. Each clause or predicate is passed to \s-1CODE\s0 as first argument and will be available as \&\f(CW$_\fR. .Sp The optional bitmask parameter, \s-1FLAGS,\s0 can be used to control what is visited and such. If \s-1FLAGS\s0 is not given, it defaults to \&\s-1VISIT_PRED_NAME.\s0 The possible values of \s-1FLAGS\s0 are: .RS 4 .IP "\s-1VISIT_PRED_NAME\s0" 4 .IX Item "VISIT_PRED_NAME" The package name in each predicate is visited, but the version and architecture part(s) are left out (if any). .IP "\s-1VISIT_PRED_FULL\s0" 4 .IX Item "VISIT_PRED_FULL" The full predicates are visited in turn. The predicate will be normalized (by \*(L"unparse\*(R"). .IP "\s-1VISIT_OR_CLAUSE_FULL\s0" 4 .IX Item "VISIT_OR_CLAUSE_FULL" \&\s-1CODE\s0 will be passed the full \s-1OR\s0 clauses of this relation. The clauses will be normalized (by \*(L"unparse\*(R") .Sp Note: It will not visit the underlying predicates in the clause. .IP "\s-1VISIT_STOP_FIRST_MATCH\s0" 4 .IX Item "VISIT_STOP_FIRST_MATCH" Stop the visits the first time \s-1CODE\s0 returns a truth value. This is similar to first, except visit will return the value returned by \s-1CODE.\s0 .RE .RS 4 .Sp Except where a given flag specifies otherwise, the return value of visit is last value returned by \s-1CODE\s0 (or \f(CW\*(C`undef\*(C'\fR for the empty relation). .RE .IP "empty" 4 .IX Item "empty" Returns a truth value if this relation is empty (i.e. it contains no predicates). .IP "unparsable_predicates" 4 .IX Item "unparsable_predicates" Returns a list of predicates that were unparsable. .Sp They are returned in the original textual representation and are also sorted by said representation. .SH "AUTHOR" .IX Header "AUTHOR" Originally written by Russ Allbery for Lintian. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBlintian\fR\|(1)