Ubuntu Manpage: Lintian::Relation - Lintian operations on dependencies and relationships

NAME

       Lintian::Relation - Lintian operations on dependencies and relationships

SYNOPSIS

           my $depends = Lintian::Relation->new('foo | bar, baz');
           print encode_utf8("yes\n") if $depends->satisfies('baz');
           print encode_utf8("no\n") if $depends->satisfies('foo');

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 "does this dependency require that a given package
       be installed" or "is this relationship a superset of another relationship."

       A dependency line is viewed as a predicate formula.  The comma separator means "and", and the
       alternatives separator means "or".  A bare package name is the predicate "a package of this name is
       available".  A package name with a version clause is the predicate "a package of this name that satisfies
       this version clause is available."  Architecture restrictions, as specified in Policy for build
       dependencies, are supported and also checked in the implication logic unless the new_norestriction()
       constructor is used.  With that constructor, architecture restrictions are ignored.

INSTANCE METHODS

       trunk
       load (RELATION)
           Creates  a  new  Lintian::Relation  object  corresponding  to the parsed relationship RELATION.  This
           object can then be used to ask questions about that relationship.  RELATION may  be  "undef"  or  the
           empty string, in which case the returned Lintian::Relation object is empty (always satisfied).

       load_norestriction (RELATION)
           Creates  a  new  Lintian::Relation object corresponding to the parsed relationship RELATION, 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).  RELATION may be
           "undef" or the empty string, in which case the returned Lintian::Relation  object  is  empty  (always
           satisfied).

       logical_and(RELATION, ...)
           Creates  a new Lintian::Relation object produced by AND'ing all the relations together.  Semantically
           it is the similar to:

            Lintian::Relation->new (join (', ', @relations))

           Except it can avoid some overhead and it works if some of the elements are Lintian::Relation  objects
           already.

       redundancies()
           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 redundancies of  each
           other.   Two  relations  are  considered redundancies if one satisfies 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.

       restriction_less
           Returns a restriction-less variant of this relation.

       satisfies(RELATION)
           Returns true if the relationship satisfies RELATION, meaning that if the Lintian::Relation object  is
           satisfied,  RELATION  will  always  be  satisfied.   RELATION  may  be  either  a  string  or another
           Lintian::Relation object.

           By default, architecture restrictions are honored in RELATION if it is  a  string.   If  architecture
           restrictions   should   be   ignored   in   RELATION,   create   a   Lintian::Relation   object  with
           new_norestriction() and pass that in as RELATION instead of the string.

       implies_array
       satisfies_inverse(RELATION)
           Returns true if the relationship satisfies that RELATION is certainly  false,  meaning  that  if  the
           Lintian::Relation object is satisfied, RELATION cannot be satisfied.  RELATION may be either a string
           or another Lintian::Relation object.

           As with satisfies(), by default, architecture restrictions are honored in RELATION if it is a string.
           If  architecture  restrictions  should be ignored in RELATION, create a Lintian::Relation object with
           new_norestriction() and pass that in as RELATION instead of the string.

       implies_array_inverse
       to_string
           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).

       matches (REGEX[, WHAT])
           Check if one of the predicates in this relation  matches  REGEX.   WHAT  determines  what  is  tested
           against REGEX and if not given, defaults to VISIT_PRED_NAME.

           This  method  will return a truth value if REGEX matches at least one predicate or clause (as defined
           by the WHAT parameter - see below).

           NOTE: Often "satisfies" (or "satisfies_inverse") is a better choice than this  method.   This  method
           should generally only be used when checking for a "pattern" package (e.g. phpapi-[\d\w+]+).

           WHAT can be one of:

           VISIT_PRED_NAME
               Match  REGEX against the package name in each predicate (i.e. version and architecture constrains
               are ignored).  Each predicate is tested in isolation.  As an example:

                my $rel = Lintian::Relation->new ('somepkg | pkg-0 (>= 1)');
                # Will match (version is ignored)
                $rel->matches (qr/^pkg-\d$/, VISIT_PRED_NAME);

           VISIT_PRED_FULL
               Match REGEX against the full (normalized) predicate (i.e. including  version  and  architecture).
               Each predicate is tested in isolation.  As an example:

                my $vrel = Lintian::Relation->new ('somepkg | pkg-0 (>= 1)');
                my $uvrel = Lintian::Relation->new ('somepkg | pkg-0');

                # Will NOT match (does not match with version)
                $vrel->matches (qr/^pkg-\d$/, VISIT_PRED_FULL);
                # Will match (this relation does not have a version)
                $uvrel->matches (qr/^pkg-\d$/, VISIT_PRED_FULL);

                # Will match (but only because there is a version)
                $vrel->matches (qr/^pkg-\d \(.*\)$/, VISIT_PRED_FULL);
                # Will NOT match (there is no version in the relation)
                $uvrel->matches (qr/^pkg-\d  \(.*\)$/, VISIT_PRED_FULL);

           VISIT_OR_CLAUSE_FULL
               Match  REGEX  against the full (normalized) OR clause.  Each predicate will have both version and
               architecture constrains present.  As an example:

                my $vpred = Lintian::Relation->new ('pkg-0 (>= 1)');
                my $orrel = Lintian::Relation->new ('somepkg | pkg-0 (>= 1)');
                my $rorrel = Lintian::Relation->new ('pkg-0 (>= 1) | somepkg');

                # Will match
                $vrel->matches (qr/^pkg-\d(?: \([^\)]\))?$/, VISIT_OR_CLAUSE_FULL);
                # These Will NOT match (does not match the "|" and the "somepkg" part)
                $orrel->matches (qr/^pkg-\d(?: \([^\)]\))?$/, VISIT_OR_CLAUSE_FULL);
                $rorrel->matches (qr/^pkg-\d(?: \([^\)]\))?$/, VISIT_OR_CLAUSE_FULL);

       equals
           Same      for      full-string       matches.       Satisfies       the       perlcritic       policy
           RegularExpressions::ProhibitFixedStringMatches.

       visit (CODE[, FLAGS])
           Visit  clauses  or  predicates of this relation.  Each clause or predicate is passed to CODE as first
           argument and will be available as $_.

           The optional bitmask parameter, FLAGS, can be used to control what is visited and such.  If FLAGS  is
           not given, it defaults to VISIT_PRED_NAME.  The possible values of FLAGS are:

           VISIT_PRED_NAME
               The  package name in each predicate is visited, but the version and architecture part(s) are left
               out (if any).

           VISIT_PRED_FULL
               The full predicates are visited in turn.  The predicate will be normalized (by "to_string").

           VISIT_OR_CLAUSE_FULL
               CODE will be passed the full OR clauses of this relation.  The clauses  will  be  normalized  (by
               "to_string")

               Note: It will not visit the underlying predicates in the clause.

           VISIT_STOP_FIRST_MATCH
               Stop  the  visits  the  first  time CODE returns a truth value.  This is similar to first, except
               visit will return the value returned by CODE.

           Except where a given flag specifies otherwise, the return value of visit is last  value  returned  by
           CODE (or "undef" for the empty relation).

       is_empty
           Returns a truth value if this relation is empty (i.e. it contains no predicates).

       unparsable_predicates
           Returns a list of predicates that were unparsable.

           They are returned in the original textual representation and are also sorted by said representation.

AUTHOR

       Originally written by Russ Allbery <rra@debian.org> for Lintian.

NAME

SYNOPSIS

DESCRIPTION

INSTANCE METHODS

AUTHOR

SEE ALSO