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.

SEE ALSO

       lintian(1)