Update selection documentation

diff --git a/doc/gen/libsolv-bindings.3 b/doc/gen/libsolv-bindings.3
index 7350224def2d6bb4a756a905839e92bdb4010389..9a844a4a8491b37cedf5a2a3f778d661650155a4 100644 (file)
--- a/doc/gen/libsolv-bindings.3
+++ b/doc/gen/libsolv-bindings.3
@@ -2,12 +2,12 @@
 .\"     Title: Libsolv-Bindings
 .\"    Author: [see the "Author" section]
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 09/07/2017
+.\"      Date: 11/16/2017
 .\"    Manual: LIBSOLV
 .\"    Source: libsolv
 .\"  Language: English
 .\"
-.TH "LIBSOLV\-BINDINGS" "3" "09/07/2017" "libsolv" "LIBSOLV"
+.TH "LIBSOLV\-BINDINGS" "3" "11/16/2017" "libsolv" "LIBSOLV"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -971,6 +971,36 @@ Create a selection by matching packages against the specified string\&. See the
 .RS 4
 .\}
 .nf
+\fBSelection matchdeps(const char *\fR\fIname\fR\fB, int\fR \fIflags\fR\fB, Id\fR \fIkeyname\fR\fB, Id\fR \fImarker\fR \fB= \-1)\fR
+my \fI$sel\fR \fB=\fR \fI$pool\fR\fB\->matchdeps(\fR\fI$name\fR\fB,\fR \fI$flags\fR\fB,\fR \fI$keyname\fR\fB)\fR;
+\fIsel\fR \fB=\fR \fIpool\fR\fB\&.matchdeps(\fR\fIname\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+\fIsel\fR \fB=\fR \fIpool\fR\fB\&.matchdeps(\fR\fIname\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Create a selection by matching package dependencies against the specified string\&. This can be used if you want to match other dependency types than "provides"\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\fBSelection matchdepid(DepId\fR \fIdep\fR\fB, int\fR \fIflags\fR\fB, Id\fR \fIkeyname\fR\fB, Id\fR \fImarker\fR \fB= \-1)\fR
+my \fI$sel\fR \fB=\fR \fI$pool\fR\fB\->matchdepid(\fR\fIdep\fR\fB,\fR \fI$flags\fR\fB,\fR \fI$keyname\fR\fB)\fR;
+\fIsel\fR \fB=\fR \fIpool\fR\fB\&.matchdepid(\fR\fIdep\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+\fIsel\fR \fB=\fR \fIpool\fR\fB\&.matchdepid(\fR\fIdep\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Create a selection by matching package dependencies against the specified dependency\&. This may be faster than matchdeps and also works with complex dependencies\&. The downside is that you cannot use globs or case insensitive matching\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
 \fBvoid setpooljobs(Jobs *\fR\fIjobs\fR\fB)\fR
 \fI$pool\fR\fB\->setpooljobs(\e\fR\fI@jobs\fR\fB)\fR;
 \fIpool\fR\fB\&.setpooljobs(\fR\fIjobs\fR\fB)\fR
@@ -3008,12 +3038,37 @@ Create the selection by matching the canonical representation of the package\&.
 .PP
 \fBSELECTION_DOTARCH\fR
 .RS 4
-Allow an \(lq\&.<architecture>\(rq suffix when matching names or provides\&.
+Allow an "\&.<architecture>" suffix when matching names or provides\&.
 .RE
 .PP
 \fBSELECTION_REL\fR
 .RS 4
-Allow the specification of a relation when matching names or provides, e\&.g\&. "name >= 1\&.2"\&.
+Allow the specification of a relation when matching names or dependencies, e\&.g\&. "name >= 1\&.2"\&.
+.RE
+.PP
+\fBSELECTION_GLOB\fR
+.RS 4
+Allow glob matching for package names, package provides, and file names\&.
+.RE
+.PP
+\fBSELECTION_NOCASE\fR
+.RS 4
+Ignore case when matching package names, package provides, and file names\&.
+.RE
+.PP
+\fBSELECTION_FLAT\fR
+.RS 4
+Return only one selection element describing the selected packages\&. The default is to create multiple elements for all globbed packages\&. Multiple elements are useful if you want to turn the selection into an install job, in that case you want an install job for every globbed package\&.
+.RE
+.PP
+\fBSELECTION_SKIP_KIND\fR
+.RS 4
+Remove a "packagekind:" prefix from the package names\&.
+.RE
+.PP
+\fBSELECTION_MATCH_DEPSTR\fR
+.RS 4
+When matching dependencies, do a string match on the result of dep2str instead of using the normal dependency intersect algorithm\&.
 .RE
 .PP
 \fBSELECTION_INSTALLED_ONLY\fR
@@ -3031,19 +3086,34 @@ Limit the package search to source packages only\&.
 Extend the package search to also match source packages\&. The default is only to match binary packages\&.
 .RE
 .PP
-\fBSELECTION_GLOB\fR
+\fBSELECTION_WITH_DISABLED\fR
 .RS 4
-Allow glob matching for package names, package provides, and file names\&.
+Extend the package search to also include disabled packages\&.
 .RE
 .PP
-\fBSELECTION_NOCASE\fR
+\fBSELECTION_WITH_BADARCH\fR
 .RS 4
-Ignore case when matching package names, package provides, and file names\&.
+Extend the package search to also include packages that are not installable on the configured architecture\&.
 .RE
 .PP
-\fBSELECTION_FLAT\fR
+\fBSELECTION_WITH_ALL\fR
 .RS 4
-Return only one selection element describing the selected packages\&. The default is to create multiple elements for all globbed packages\&. Multiple elements are useful if you want to turn the selection into an install job, in that case you want an install job for every globbed package\&.
+Shortcut for selecting the three modifiers above\&.
+.RE
+.PP
+\fBSELECTION_ADD\fR
+.RS 4
+Add the result of the match to the current selection instead of replacing it\&.
+.RE
+.PP
+\fBSELECTION_SUBTRACT\fR
+.RS 4
+Remove the result of the match to the current selection instead of replacing it\&.
+.RE
+.PP
+\fBSELECTION_FILTER\fR
+.RS 4
+Intersect the result of the match to the current selection instead of replacing it\&.
 .RE
 .SS "ATTRIBUTES"
 .sp
@@ -3127,6 +3197,21 @@ Build the union of two selections\&. All packages of the other selection will be
 .RS 4
 .\}
 .nf
+\fBvoid subtract(Selection *\fR\fIother\fR\fB)\fR
+\fI$sel\fR\fB\->subtract(\fR\fI$other\fR\fB)\fR;
+\fIsel\fR\fB\&.subtract(\fR\fIother\fR\fB)\fR
+\fIsel\fR\fB\&.subtract(\fR\fIother\fR\fB)\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Remove the packages of the other selection from the packages of the selection object\&. Does an in\-place modification\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
 \fBvoid add_raw(Id\fR \fIhow\fR\fB, Id\fR \fIwhat\fR\fB)\fR
 \fI$sel\fR\fB\->add_raw(\fR\fI$how\fR\fB,\fR \fI$what\fR\fB)\fR;
 \fIsel\fR\fB\&.add_raw(\fR\fIhow\fR\fB,\fR \fIwhat\fR\fB)\fR
@@ -3136,7 +3221,7 @@ Build the union of two selections\&. All packages of the other selection will be
 .RE
 .\}
 .sp
-Add a raw element to the selection\&. Check the Job class for information about the how and what parameters\&.
+Add a raw element to the selection\&. Check the Job class for information about the how and what parameters\&. Note that the selection flags are no longer meaningful after the add_raw operation\&.
 .sp
 .if n \{\
 .RS 4
@@ -3172,6 +3257,51 @@ Convert a selection into an array of Solvable objects\&.
 .RS 4
 .\}
 .nf
+\fBvoid select(const char *\fR\fIname\fR\fB, int\fR \fIflags\fR\fB)\fR
+\fI$sel\fR\fB\->select(\fR\fI$name\fR\fB,\fR \fI$flags\fR\fB)\fR;
+\fIsel\fR\fB\&.select(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR
+\fIsel\fR\fB\&.select(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Do a select operation and combine the result with the current selection\&. You can choose the desired combination method by using either the SELECTION_ADD, SELECTION_SUBTRACT, or SELECTION_FILTER flag\&. If none of the flags are used, SELECTION_FILTER|SELECTION_WITH_ALL is assumed\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\fBvoid matchdeps(const char *\fR\fIname\fR\fB, int\fR \fIflags\fR\fB, Id\fR \fIkeyname\fR\fB, Id\fR \fImarker\fR \fB= \-1)\fR
+\fI$sel\fR\fB\->matchdeps(\fR\fI$name\fR\fB,\fR \fI$flags\fR\fB,\fR \fI$keyname\fR\fB)\fR;
+\fIsel\fR\fB\&.matchdeps(\fR\fIname\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+\fIsel\fR\fB\&.matchdeps(\fR\fIname\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Do a matchdeps operation and combine the result with the current selection\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\fBvoid matchdepid(DepId\fR \fIdep\fR\fB, int\fR \fIflags\fR\fB, Id\fR \fIkeyname\fR\fB, Id\fR \fImarker\fR \fB= \-1)\fR
+\fI$sel\fR\fB\->matchdepid(\fR\fI$dep\fR\fB,\fR \fI$flags\fR\fB,\fR \fI$keyname\fR\fB)\fR;
+\fIsel\fR\fB\&.matchdepid(\fR\fIdep\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+\fIsel\fR\fB\&.matchdepid(\fR\fIdep\fR\fB,\fR \fIflags\fR\fB,\fR \fIkeyname\fR\fB)\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Do a matchdepid operation and combine the result with the current selection\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
 \fB<stringification>\fR
 my \fI$str\fR \fB=\fR \fI$sel\fR\fB\->str\fR;
 \fIstr\fR \fB= str(\fR\fIsel\fR\fB)\fR

diff --git a/doc/libsolv-bindings.txt b/doc/libsolv-bindings.txt
index 83ae6c29335a53887e93a46e254432824f59f578..c204502f1e3875b3dc88ac61ab3b76e07b263577 100644 (file)
--- a/doc/libsolv-bindings.txt
+++ b/doc/libsolv-bindings.txt
@@ -551,6 +551,24 @@ Create a selection by matching packages against the specified string. See the
 Selection class for a list of flags and how to create solver jobs from a
 selection.
 
+       Selection matchdeps(const char *name, int flags, Id keyname, Id marker = -1)
+       my $sel = $pool->matchdeps($name, $flags, $keyname);
+       sel = pool.matchdeps(name, flags, keyname)
+       sel = pool.matchdeps(name, flags, keyname)
+
+Create a selection by matching package dependencies against the specified string.
+This can be used if you want to match other dependency types than "provides".
+
+       Selection matchdepid(DepId dep, int flags, Id keyname, Id marker = -1)
+       my $sel = $pool->matchdepid(dep, $flags, $keyname);
+       sel = pool.matchdepid(dep, flags, keyname)
+       sel = pool.matchdepid(dep, flags, keyname)
+
+Create a selection by matching package dependencies against the specified
+dependency. This may be faster than matchdeps and also works with complex
+dependencies. The downside is that you cannot use globs or case insensitive
+matching.
+
        void setpooljobs(Jobs *jobs)
        $pool->setpooljobs(\@jobs);
        pool.setpooljobs(jobs)
@@ -1682,22 +1700,12 @@ of the package. This is normally a combination of the name,
 the version, and the architecture of a package.
 
 *SELECTION_DOTARCH*::
-Allow an ``.<architecture>'' suffix when matching names or
+Allow an ".<architecture>" suffix when matching names or
 provides.
  
 *SELECTION_REL*::
 Allow the specification of a relation when matching names
-or provides, e.g. "name >= 1.2".
-
-*SELECTION_INSTALLED_ONLY*::
-Limit the package search to installed packages.
-
-*SELECTION_SOURCE_ONLY*::
-Limit the package search to source packages only.
-
-*SELECTION_WITH_SOURCE*::
-Extend the package search to also match source packages. The default is
-only to match binary packages.
+or dependencies, e.g. "name >= 1.2".
 
 *SELECTION_GLOB*::
 Allow glob matching for package names, package provides, and file names.
@@ -1712,6 +1720,42 @@ Multiple elements are useful if you want to turn the selection into
 an install job, in that case you want an install job for every
 globbed package.
 
+*SELECTION_SKIP_KIND*::
+Remove a "packagekind:" prefix from the package names.
+
+*SELECTION_MATCH_DEPSTR*::
+When matching dependencies, do a string match on the result of dep2str
+instead of using the normal dependency intersect algorithm.
+
+*SELECTION_INSTALLED_ONLY*::
+Limit the package search to installed packages.
+
+*SELECTION_SOURCE_ONLY*::
+Limit the package search to source packages only.
+
+*SELECTION_WITH_SOURCE*::
+Extend the package search to also match source packages. The default is
+only to match binary packages.
+
+*SELECTION_WITH_DISABLED*::
+Extend the package search to also include disabled packages.
+
+*SELECTION_WITH_BADARCH*::
+Extend the package search to also include packages that are not installable
+on the configured architecture.
+
+*SELECTION_WITH_ALL*::
+Shortcut for selecting the three modifiers above.
+
+*SELECTION_ADD*::
+Add the result of the match to the current selection instead of replacing it.
+
+*SELECTION_SUBTRACT*::
+Remove the result of the match to the current selection instead of replacing it.
+
+*SELECTION_FILTER*::
+Intersect the result of the match to the current selection instead of replacing it.
+
 === ATTRIBUTES ===
 
        Pool *pool;                             /* read only */
@@ -1761,13 +1805,22 @@ be added to the set of packages of the selection object. Does an in-place
 modification. Note that the selection flags are no longer meaningful after the
 add operation.
 
+       void subtract(Selection *other)
+       $sel->subtract($other);
+       sel.subtract(other)
+       sel.subtract(other)
+
+Remove the packages of the other selection from the packages of the selection
+object. Does an in-place modification.
+
        void add_raw(Id how, Id what)
        $sel->add_raw($how, $what);
        sel.add_raw(how, what)
        sel.add_raw(how, what)
 
 Add a raw element to the selection. Check the Job class for information about
-the how and what parameters.
+the how and what parameters. Note that the selection flags are no longer meaningful
+after the add_raw operation.
 
        Job *jobs(int action)
        my @jobs = $sel->jobs($action);
@@ -1785,6 +1838,30 @@ erase). See the Job class for the action and action modifier constants.
 
 Convert a selection into an array of Solvable objects.
 
+       void select(const char *name, int flags)
+       $sel->select($name, $flags);
+       sel.select(name, flags)
+       sel.select(name, flags)
+
+Do a select operation and combine the result with the current selection. You
+can choose the desired combination method by using either the SELECTION_ADD,
+SELECTION_SUBTRACT, or SELECTION_FILTER flag. If none of the flags are
+used, SELECTION_FILTER|SELECTION_WITH_ALL is assumed.
+
+       void matchdeps(const char *name, int flags, Id keyname, Id marker = -1)
+       $sel->matchdeps($name, $flags, $keyname);
+       sel.matchdeps(name, flags, keyname)
+       sel.matchdeps(name, flags, keyname)
+
+Do a matchdeps operation and combine the result with the current selection.
+
+       void matchdepid(DepId dep, int flags, Id keyname, Id marker = -1)
+       $sel->matchdepid($dep, $flags, $keyname);
+       sel.matchdepid(dep, flags, keyname)
+       sel.matchdepid(dep, flags, keyname)
+
+Do a matchdepid operation and combine the result with the current selection.
+
        <stringification>
        my $str = $sel->str;
        str = str(sel)