Imported Upstream version 0.7.11
[platform/upstream/libsolv.git] / doc / libsolv-bindings.txt
index e44d53a..ac112cf 100644 (file)
@@ -45,7 +45,7 @@ tied arrays so that it is possible to iterate with a for() statement:
 As a downside of this approach, iterator objects cannot have attributes.
 
 If an array needs to be passed to a method it is usually done by reference,
-if a method returns an array it returns it on the stack:
+if a method returns an array it returns it on the perl stack:
 
        my @problems = $solver->solve(\@jobs);
 
@@ -59,7 +59,7 @@ natural constant subs), so don't forget the leading ``$'' when accessing a
 constant. Also do not forget to prepend the namespace of the constant:
 
        $pool->set_flag($solv::Pool::POOL_FLAG_OBSOLETEUSESCOLORS, 1);
-       
+
 
 Python Specifics
 ----------------
@@ -93,7 +93,7 @@ __repr__ method to ease debugging.
        print dep
        print repr(repo)
 
-Constants are attributes of the classes:
+Constants are attributes of the corresponding classes:
 
        pool.set_flag(solv.Pool.POOL_FLAG_OBSOLETEUSESCOLORS, 1);
 
@@ -167,7 +167,7 @@ a foreach style:
 
 libsolv's arrays are mapped to tcl's lists:
 
-        TCL set jobs [list $job1 $job2]
+       TCL set jobs [list $job1 $job2]
        TCL set problems [$solver solve $jobs]
        TCL puts "We have [llength $problems] problems..."
 
@@ -183,9 +183,9 @@ Some objects also support a ``=='' method for equality tests, and a
 Swig implements all constants as numeric variables, constants belonging
 to a libsolv class are prefixed with the class name:
 
-       TCL $pool set_flag $solv::Pool_POOL_FLAG_OBSOLETEUSESCOLORS  1
+       TCL $pool set_flag $solv::Pool_POOL_FLAG_OBSOLETEUSESCOLORS 1
        TCL puts [$solvable lookup_str $solv::SOLVABLE_SUMMARY]
-       
+
 
 The Solv Class
 --------------
@@ -218,10 +218,10 @@ like an extra Solvable that has the Id SOLVID_META.
 *SOLVID_POS*::
 Use the data position stored inside of the pool instead of accessing
 some solvable by Id. The bindings have the Datapos objects as an
-abstraction mechanism, so you do not need this constant.
+abstraction mechanism, so you most likely do not need this constant.
 
 Constant string Ids
-  
+
 *ID_NULL*::
 Always zero
 
@@ -248,7 +248,7 @@ Repositories, Dependencies, each indexed by Ids.
        pool = Solv::Pool.new()
 
 Create a new pool instance. In most cases you just need one pool.
-Note that the returned object "owns" the pool, i.e. if the object is 
+Note that the returned object "owns" the pool, i.e. if the object is
 freed, the pool is also freed. You can use the disown method to
 break this ownership relation.
 
@@ -300,7 +300,7 @@ in old rpm versions, modern systems should never need this.
 *POOL_FLAG_FORBIDSELFCONFLICTS*::
 Disallow the installation of packages that conflict with themselves.
 Debian always allows self-conflicting packages, rpm used to forbid
-them but switched to also allowing them recently.
+them but switched to also allowing them since rpm-4.9.0.
 
 *POOL_FLAG_OBSOLETEUSESPROVIDES*::
 Make obsolete type dependency match against provides instead of
@@ -315,10 +315,10 @@ with the same name, rpm-5 switched to also removing packages
 providing the same name.
 
 *POOL_FLAG_OBSOLETEUSESCOLORS*::
-Rpm's multilib implementation (used in RedHat and Fedora)
-distinguishes between 32bit and 64bit packages (the terminology
-is that they have a different color). If obsoleteusescolors is
-set, packages with different colors will not obsolete each other.
+Rpm's multilib implementation distinguishes between 32bit and 64bit
+packages (the terminology is that they have a different color).
+If obsoleteusescolors is set, packages with different colors will
+not obsolete each other.
 
 *POOL_FLAG_IMPLICITOBSOLETEUSESCOLORS*::
 Same as POOL_FLAG_OBSOLETEUSESCOLORS, but used to find out if
@@ -328,9 +328,9 @@ false and POOL_FLAG_IMPLICITOBSOLETEUSESCOLORS should be true
 (this is the default if FEDORA is defined when libsolv is compiled).
 
 *POOL_FLAG_NOINSTALLEDOBSOLETES*::
-New versions of rpm consider the obsoletes of installed packages
-when checking for dependency, thus you may not install a package
-that is obsoleted by some other installed package, unless you
+Since version 4.9.0 rpm considers the obsoletes of installed packages
+when checking for dependency conflicts, thus you may not install a
+package that is obsoleted by some other installed package unless you
 also erase the other package.
 
 *POOL_FLAG_HAVEDISTEPOCH*::
@@ -339,7 +339,7 @@ version comparison if the epoch/version/release of two packages
 are the same.
 
 *POOL_FLAG_NOOBSOLETESMULTIVERSION*::
-If a package is installed in multiversionmode, rpm used to ignore
+If a package is installed in multiversion mode, rpm used to ignore
 both the implicit obsoletes and the obsolete dependency of a
 package. This was changed to ignoring just the implicit obsoletes,
 thus you may install multiple versions of the same name, but
@@ -393,7 +393,7 @@ value, the more output is generated.
 Set/get a pool specific flag. The flags define how the system works, e.g. how
 the package manager treats obsoletes. The default flags should be sane for most
 applications, but in some cases you may want to tweak a flag, for example if
-you want to solv package dependencies for some other system than yours.
+you want to solve package dependencies for some other system.
 
        void set_rootdir(const char *rootdir)
        $pool->set_rootdir(rootdir);
@@ -475,7 +475,8 @@ repository is loaded and addfileprovides is called.
        pool.createwhatprovides()
 
 Create the internal ``whatprovides'' hash over all of the provides of all
-packages. This method must be called before doing any lookups on provides.
+installable packages. This method must be called before doing any lookups on
+provides.
 It's encouraged to do it right after all repos are set up, usually right after
 the call to addfileprovides().
 
@@ -487,6 +488,35 @@ the call to addfileprovides().
 Return all solvables that provide the specified dependency. You can use either
 a Dep object or a simple Id as argument.
 
+       Solvable *best_solvables(Solvable *solvables, int flags = 0)
+       my @solvables = $pool->best_solvables($solvables);
+       solvables = pool.best_solvables(solvables)
+       solvables = pool.best_solvables(solvables)
+
+Filter list of solvables by repo priority, architecture and version.
+
+       Solvable *whatcontainsdep(Id keyname, DepId dep, Id marker = -1)
+       my @solvables = $pool->whatcontainsdep($keyname, $dep)
+       solvables = pool.whatcontainsdep(keyname, dep)
+       solvables = pool.whatcontainsdep(keyname, dep)
+
+Return all solvables for which keyname contains the dependency.
+
+       Solvable *whatmatchesdep(Id keyname, DepId dep, Id marker = -1)
+       my @solvables = $pool->whatmatchesdep($keyname, $sdep)
+       solvables = pool.whatmatchesdep(keyname, dep)
+       solvables = pool.whatmatchesdep(keyname, dep)
+
+Return all solvables that have dependencies in keyname that match the dependency.
+
+       Solvable *whatmatchessolvable(Id keyname, Solvable solvable, Id marker = -1)
+       my @solvables = $pool->whatmatchessolvable($keyname, $solvable)
+       solvables = pool.whatmatchessolvable(keyname, solvable)
+       solvables = pool.whatmatchessolvable(keyname, solvable)
+
+Return all solvables that match package dependencies against solvable's
+provides.
+
        Id *matchprovidingids(const char *match, int flags)
        my @ids = $pool->matchprovidingids($match, $flags);
        ids = pool.matchprovidingids(match, flags)
@@ -504,6 +534,21 @@ string. See the Dataiterator class for the allowed flags.
 create solver jobs working on a specific set of packages. See the Solver class
 for more information.
 
+       void set_namespaceproviders(DepId ns, DepId evr, bool value = 1)
+       $pool->set_namespaceproviders($ns, $evr, 1);
+       pool.set_namespaceproviders(ns, evr, True)
+       pool.set_namespaceproviders(ns, evr, true)
+
+Manually set a namespace provides entry in the whatprovides index.
+
+       void flush_namespaceproviders(DepId ns, DepId evr)
+       $pool->flush_namespaceproviders($ns, $evr);
+       $pool.flush_namespaceproviders(ns, evr)
+       $pool.flush_namespaceproviders(ns, evr)
+
+Flush the cache of all namespaceprovides matching the specified namespace
+dependency. You can use zero as a wildcard argument.
+
        bool isknownarch(DepId id)
        my $bool = $pool->isknownarch($id);
        bool = pool.isknownarch(id)
@@ -523,8 +568,8 @@ Create a new solver object.
        job = pool.Job(how, what)
        job = pool.Job(how, what)
 
-Create a new Job object. Kind of low level, in most cases you would use a
-Selection or Dep job constructor instead.
+Create a new Job object. Kind of low level, in most cases you would
+instead use a Selection or Dep job constructor.
 
        Selection Selection()
        my $sel = $pool->Selection();
@@ -538,7 +583,7 @@ selections.
        my $sel = $pool->Selection_all();
        sel = pool.Selection_all()
        sel = pool.Selection_all()
-       
+
 Create a selection containing all packages. Useful as starting point for
 intersecting other selections or for update/distupgrade jobs.
 
@@ -551,6 +596,32 @@ 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.
+
+       Selection matchsolvable(Solvable solvable, int flags, Id keyname, Id marker = -1)
+       my $sel = $pool->matchsolvable($solvable, $flags, $keyname);
+       sel = pool.matchsolvable(solvable, flags, keyname)
+       sel = pool.matchsolvable(solvable, flags, keyname)
+
+Create a selection by matching package dependencies against the specified
+solvable's provides.
+
        void setpooljobs(Jobs *jobs)
        $pool->setpooljobs(\@jobs);
        pool.setpooljobs(jobs)
@@ -563,8 +634,8 @@ selection.
 
 Get/Set fixed jobs stored in the pool. Those jobs are automatically appended to
 all solver jobs, they are meant for fixed configurations like which packages
-can be multiversion installed, which packages were userinstalled or must not be
-erased.
+can be multiversion installed, which packages were userinstalled, or which
+packages must not be erased.
 
        void set_loadcallback(Callable *callback)
        $pool->setloadcallback(\&callbackfunction);
@@ -588,6 +659,35 @@ circular references (e.g. if the pool's appdata value points to some meta data
 structure that contains a pool handle). If used incorrectly, this method can
 lead to application crashes, so beware. (This method is a no-op for ruby and tcl.)
 
+       Id *get_considered_list()
+       my @ids = $pool->get_considered_list();
+       ids = pool.get_considered_list()
+       ids = pool.get_considered_list()
+
+       void set_considered_list(Id *ids)
+       $pool->set_considered_list(\@ids);
+       pool.set_considered_list(ids)
+       pool.set_considered_list(ids)
+
+Get/set the list of solvables that are eligible for installation. Note that
+you need to recreate the whatprovides hash after changing the list.
+
+       Id *get_disabled_list()
+       my @ids = $pool->get_disabled_list();
+       ids = pool.get_disabled_list()
+       ids = pool.get_disabled_list()
+
+       void set_disabled_list(Id *ids)
+       $pool->set_disabled_list(\@ids);
+       pool.set_disabled_list(ids)
+       pool.set_disabled_list(ids)
+
+Get/set the list of solvables that are not eligible for installation. This is
+basically the inverse of the ``considered'' methods above, i.e. calling
+``set_disabled_list()'' with an empty list will make all solvables eligible for
+installation. Note you need to recreate the whatprovides hash after changing the
+list.
+
 === DATA RETRIEVAL METHODS ===
 
 In the following functions, the _keyname_ argument describes what to retrieve.
@@ -700,7 +800,7 @@ pool and _create_ is false, zero is returned.
        id = pool.rel2id(nameid, evrid, flags)
 
 Create a ``relational'' dependency. Such dependencies consist of a name part,
-the _flags_ describing the relation, and a version part. The flags are:
+_flags_ describing the relation, and a version part. The flags are:
 
        $solv::REL_EQ | $solv::REL_GT | $solv::REL_LT
        solv.REL_EQ | solv.REL_GT | solv.REL_LT
@@ -750,15 +850,16 @@ Back reference to the pool this dependency belongs to.
 
 The id of this dependency.
 
-== Methods ==
+=== METHODS ===
 
        Dep Rel(int flags, DepId evrid, bool create = 1)
        my $reldep = $dep->Rel($flags, $evrdep);
        reldep = dep.Rel(flags, evrdep)
        reldep = dep.Rel(flags, evrdep)
 
-Create a relational dependency from to string dependencies and a flags
-argument. See the pool's rel2id method for a description of the flags.
+Create a relational dependency from the caller dependency, the flags,
+and a dependency describing the ``version'' part.
+See the pool's rel2id method for a description of the flags.
 
        Selection Selection_name(int setflags = 0)
        my $sel = $dep->Selection_name();
@@ -796,7 +897,7 @@ Same as calling the str() method.
        if dep1 == dep2:
        if dep1 == dep2
 
-The dependencies are equal if they are part of the same pool and have the same
+Two dependencies are equal if they are part of the same pool and have the same
 ids.
 
 
@@ -825,7 +926,7 @@ The id of the repository.
        $repo->{name}
        repo.name
        repo.name
-       
+
 The repositories name. To libsolv, the name is just a string with no specific
 meaning.
 
@@ -875,7 +976,7 @@ timestamp.
 
 *REPO_REUSE_REPODATA*::
 Reuse the last repository data area (``repodata'') instead of creating a
-new one.
+new area.
 
 *REPO_NO_INTERNALIZE*::
 Do not internalize the added repository data. This is useful if
@@ -1173,9 +1274,9 @@ Add the contents of the mageia/mandriva repository metadata (the
 "synthesis.hdlist" file) to the repository.
 
        bool add_mdk_info(FILE *fp, int flags = 0)
-       $repo->add_mdk($fp);
-       repo.add_mdk(fp)
-       repo.add_mdk(fp)
+       $repo->add_mdk_info($fp);
+       repo.add_mdk_info(fp)
+       repo.add_mdk_info(fp)
 
 Extend the packages from the synthesis file with the info.xml and files.xml
 data. Do not forget to specify *REPO_EXTEND_SOLVABLES*.
@@ -1309,10 +1410,10 @@ a specific id and want to avoid the string compare overhead.
 
        Id lookup_id(Id keyname)
        my $id = $solvable->lookup_id($keyname);
-       id = solvable.lookup_id(solvid)
-       id = solvable.lookup_id(solvid)
+       id = solvable.lookup_id(keyname)
+       id = solvable.lookup_id(keyname)
 
-       unsigned long long lookup_num(Id solvid, Id keyname, unsigned long long notfound = 0)
+       unsigned long long lookup_num(Id keyname, unsigned long long notfound = 0)
        my $num = $solvable->lookup_num($keyname);
        num = solvable.lookup_num(keyname)
        num = solvable.lookup_num(keyname)
@@ -1336,7 +1437,7 @@ a specific id and want to avoid the string compare overhead.
        my @deps = $solvable->lookup_deparray($keyname);
        deps = solvable.lookup_deparray(keyname)
        deps = solvable.lookup_deparray(keyname)
-       
+
 Generic lookup methods. Retrieve data stored for the specific keyname.
 The lookup_idarray() method will return an array of Ids, use
 lookup_deparray if you want an array of Dependency objects instead.
@@ -1349,14 +1450,21 @@ array, use 1 to select the second part or 0 to retrieve all ids
 including the marker.
 
        const char *lookup_location(unsigned int *OUTPUT);
-       my ($location, $medianr) = $solvable->lookup_location();
-       location, medianr = solvable.lookup_location()
-       location, medianr = solvable.lookup_location()
+       my ($location, $mediano) = $solvable->lookup_location();
+       location, mediano = solvable.lookup_location()
+       location, mediano = solvable.lookup_location()
 
 Return a tuple containing the on-media location and an optional
 media number for multi-part repositories (e.g. repositories
 spawning multiple DVDs).
 
+       const char *lookup_sourcepkg();
+       my $sourcepkg = $solvable->lookup_sourcepkg();
+       sourcepkg = solvable.lookup_sourcepkg()
+       sourcepkg = solvable.lookup_sourcepkg()
+
+Return a sourcepkg name associated with solvable.
+
        Dataiterator Dataiterator(Id keyname, const char *match = 0, int flags = 0)
        my $di = $solvable->Dataiterator($keyname, $match, $flags);
        di = solvable.Dataiterator(keyname, match, flags)
@@ -1419,7 +1527,7 @@ Note that "equal" does not mean that the evr is identical.
        solvable.matchesdep(keyname, dep)
        solvable.matchesdep?(keyname, dep)
 
-Return true if the dependencies stored in keyname match the specified dependeny.
+Return true if the dependencies stored in keyname match the specified dependency.
 
        Selection Selection(int setflags = 0)
        my $sel = $solvable->Selection();
@@ -1503,7 +1611,7 @@ Allow the matching of checksum entries.
 Do a sub-search in the array stored in keyname.
 
        void skip_solvable();
-       $di->kip_solvable();
+       $di->skip_solvable();
        di.skip_solvable()
        di.skip_solvable()
 
@@ -1675,22 +1783,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.
@@ -1705,6 +1803,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 */
@@ -1714,14 +1848,12 @@ globbed package.
 
 Back pointer to pool.
 
-=== METHODS ===
-
-       int flags();
-       my $flags = $sel->flags();
-       flags = sel.flags()
-       flags = sel.flags()
+       int flags;                              /* read only */
+       $sel->{flags}
+       flags = sel.flags
+       flags = sel.flags
 
-Return the result flags of the selection. The flags are a subset
+The result flags of the selection. The flags are a subset
 of the ones used when creating the selection, they describe which
 method was used to get the result. For example, if you create the
 selection with ``SELECTION_NAME | SELECTION_PROVIDES'', the resulting
@@ -1729,13 +1861,22 @@ flags will either be SELECTION_NAME or SELECTION_PROVIDES depending
 if there was a package that matched the name or not. If there was
 no match at all, the flags will be zero.
 
-       bool isempty();
+=== METHODS ===
+
+       bool isempty()
        $sel->isempty()
        sel.isempty()
        sel.isempty?
 
 Return true if the selection is empty, i.e. no package could be matched.
 
+       Selection clone(int flags = 0)
+       my $cloned = $sel->clone();
+       cloned = sel.clone()
+       cloned = sel.clone()
+
+Return a copy of a selection.
+
        void filter(Selection *other)
        $sel->filter($other);
        sel.filter(other)
@@ -1754,13 +1895,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);
@@ -1778,6 +1928,37 @@ 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.
+
+       void matchsolvable(Solvable solvable, int flags, Id keyname, Id marker = -1)
+       $sel->matchsolvable($solvable, $flags, $keyname);
+       sel.matchsolvable(solvable, flags, keyname)
+       sel.matchsolvable(solvable, flags, keyname)
+
+Do a matchsolvable operation and combine the result with the current selection.
+
        <stringification>
        my $str = $sel->str;
        str = str(sel)
@@ -1837,7 +2018,7 @@ Update the matching installed packages to their best version. If none
 of the specified packages are installed, try to update the installed
 packages to the specified versions. See the section about targeted
 updates about more information.
+
 *SOLVER_WEAKENDEPS*::
 Allow to break the dependencies of the matching packages. Handle with care.
 
@@ -2086,7 +2267,7 @@ Allow the solver to downgrade packages without asking for confirmation
 Allow the solver to change the architecture of an installed package
 without asking for confirmation. Note that changes to/from noarch
 are always considered to be allowed.
-  
+
 *SOLVER_FLAG_ALLOW_VENDORCHANGE*::
 Allow the solver to change the vendor of an installed package
 without asking for confirmation. Each vendor is part of one or more
@@ -2129,7 +2310,7 @@ by setting this flag.
 
 *SOLVER_FLAG_NEED_UPDATEPROVIDE*::
 This is somewhat the opposite of SOLVER_FLAG_NO_UPDATEPROVIDE: Only
-packages that provied the installed package names are considered
+packages that provide the installed package names are considered
 for updating.
 
 *SOLVER_FLAG_SPLITPROVIDES*::
@@ -2145,7 +2326,7 @@ Install recommended or supplemented packages even if they have no
 connection to the current transaction. You can use this feature
 to implement a simple way for the user to install new recommended
 packages that were not available in the past.
-  
+
 *SOLVER_FLAG_NO_INFARCHCHECK*::
 Turn off the inferior architecture checking that is normally done
 by the solver. Normally, the solver allows only the installation
@@ -2457,6 +2638,23 @@ interfaces that show both the job result and the problems.
 Return the reason why a specific solvable was installed or erased. For most of
 the reasons the rule that triggered the decision is also returned.
 
+       Solvable *get_recommended(bool noselected=0);
+       my @solvables = $solver->get_recommended();
+       solvables = solver.get_recommended()
+       solvables = solver.get_recommended()
+
+Return all solvables that are recommended by the solver run result. This includes
+solvables included in the result, set noselected if you want to filter those.
+
+       Solvable *get_suggested(bool noselected=0);
+       my @solvables = $solver->get_suggested();
+       solvables = solver.get_suggested()
+       solvables = solver.get_suggested()
+
+Return all solvables that are suggested by the solver run result. This includes
+solvables included in the result, set noselected if you want to filter those.
+
+
 The Problem Class
 -----------------
 Problems are the way of the solver to interact with the user. You can simply list
@@ -2493,8 +2691,8 @@ that somewhat describes the problem best to the user.
 
        Rule *findallproblemrules(bool unfiltered = 0)
        my @probrules = $problem->findallproblemrules();
-       probrules = problem.findallproblemrule()
-       probrules = problem.findallproblemrule()
+       probrules = problem.findallproblemrules()
+       probrules = problem.findallproblemrules()
 
 Return all rules responsible for the problem. The returned set of rules contains
 all the needed information why there was a problem, but it's hard to present
@@ -2783,7 +2981,7 @@ the solver class.
 
 Create a job that implements the solution element. Add this job to the array
 of jobs for all elements of type different to SOLVER_SOLUTION_JOB and
-SOLVER_SOLUTION_POOLJOB. For the later two, a SOLVER_NOOB Job is created,
+SOLVER_SOLUTION_POOLJOB. For the latter two, a SOLVER_NOOB Job is created,
 you should replace the old job with the new one.
 
        const char *str()
@@ -2900,7 +3098,7 @@ Use this flag if you want to map OBSOLETE elements to the UPGRADE type.
 *SOLVER_TRANSACTION_MERGE_ARCHCHANGES*::
 Do not add extra categories for every architecture change, instead cumulate
 them in one category.
-  
+
 *SOLVER_TRANSACTION_MERGE_VENDORCHANGES*::
 Do not add extra categories for every vendor change, instead cumulate
 them in one category.
@@ -3005,7 +3203,7 @@ be installed packages, returns all of the packages that the new package
 replaces. The special ``other'' solvable is always the first entry of the
 returned array.
 
-       int calc_installsizechange();
+       long long calc_installsizechange();
        my $change = $trans->calc_installsizechange();
        change = trans.calc_installsizechange()
        change = trans.calc_installsizechange()
@@ -3039,7 +3237,7 @@ in passive mode, but
   update A-2-1 (other: A-1-1)
   erase  B
 
-in active mode. If the mode contains SOLVER_TRANSACTION_SHOW_ALL, the 
+in active mode. If the mode contains SOLVER_TRANSACTION_SHOW_ALL, the
 passive mode list will be unchanged but the active mode list will just
 contain A-2-1.
 
@@ -3165,7 +3363,7 @@ Add a (binary) string to the checksum.
        chksum.add_fp(file)
 
 Add the contents of a file to the checksum.
-       
+
        void add_stat(const char *filename)
        $chksum->add_stat($filename);
        chksum.add_stat(filename)
@@ -3297,7 +3495,7 @@ The Repodata Class
 The Repodata stores attributes for packages and the repository itself, each
 repository can have multiple repodata areas. You normally only need to
 directly access them if you implement lazy downloading of repository data.
-Repodata areas are created by calling the repository's add_repodata() method 
+Repodata areas are created by calling the repository's add_repodata() method
 or by using repo_add methods without the REPO_REUSE_REPODATA or REPO_USE_LOADING
 flag.
 
@@ -3334,6 +3532,26 @@ after it has been internalized.
 
 Write the contents of the repodata area as solv file.
 
+       Id str2dir(const char *dir, bool create = 1)
+       my $did = data->str2dir($dir);
+       did = data.str2dir(dir)
+       did = data.str2dir(dir)
+
+       const char *dir2str(Id did, const char *suffix = 0)
+       $dir = pool->dir2str($did);
+       dir = pool.dir2str(did)
+       dir = pool.dir2str(did)
+
+Convert a string (directory) into an Id and back. If the string is currently not in the
+pool and _create_ is false, zero is returned.
+
+       void add_dirstr(Id solvid, Id keyname, Id dir, const char *str)
+       $data->add_dirstr($solvid, $keyname, $dir, $string)
+       data.add_dirstr(solvid, keyname, dir, string)
+       data.add_dirstr(solvid, keyname, dir, string)
+
+Add a file path consisting of a dirname Id and a basename string.
+
        bool add_solv(FILE *fp, int flags = 0);
        $data->add_solv($fp);
        data.add_solv(fp)
@@ -3357,9 +3575,10 @@ area.
        data.extend_to_repo()
 
 Extend the repodata so that it has the same size as the repo it belongs to.
-This method is only needed when switching to a just written repodata extension
-to make the repodata match the written extension (which is always of the
-size of the repo).
+This method is needed when setting up a new extension repodata so that it
+matches the repository size. It is also needed when switching to a just written
+repodata extension to make the repodata match the written extension (which is
+always of the size of the repo).
 
        <equality>
        if ($data1 == $data2)
@@ -3376,6 +3595,21 @@ the same id.
        string = data.lookup_str(solvid, keyname)
        string = data.lookup_str(solvid, keyname)
 
+       const char *lookup_id(Id solvid, Id keyname)
+       my $string = $data->lookup_id($solvid, $keyname);
+       string = data.lookup_id(solvid, keyname)
+       string = data.lookup_id(solvid, keyname)
+
+       unsigned long long lookup_num(Id solvid, Id keyname, unsigned long long notfound = 0)
+       my $num = $data->lookup_num($solvid, $keyname);
+       num = data.lookup_num(solvid, keyname)
+       num = data.lookup_num(solvid, keyname)
+
+       bool lookup_void(Id solvid, Id keyname)
+       my $bool = $data->lookup_void($solvid, $keyname);
+       bool = data.lookup_void(solvid, keyname)
+       bool = data.lookup_void(solvid, keyname)
+
        Id *lookup_idarray(Id solvid, Id keyname)
        my @ids = $data->lookup_idarray($solvid, $keyname);
        ids = data.lookup_idarray(solvid, keyname)
@@ -3392,15 +3626,25 @@ SOLVID_META solvid that stores repodata meta information.
 
 === DATA STORAGE METHODS ===
 
+       void set_str(Id solvid, Id keyname, const char *str);
+       $data->set_str($solvid, $keyname, $str);
+       data.set_str(solvid, keyname, str)
+       data.set_str(solvid, keyname, str)
+
        void set_id(Id solvid, Id keyname, DepId id);
        $data->set_id($solvid, $keyname, $id);
        data.set_id(solvid, keyname, id)
        data.set_id(solvid, keyname, id)
 
-       void set_str(Id solvid, Id keyname, const char *str);
-       $data->set_str($solvid, $keyname, $str);
-       data.set_str(solvid, keyname, str)
-       data.set_str(solvid, keyname, str)
+       void set_num(Id solvid, Id keyname, unsigned long long num);
+       $data->set_num($solvid, $keyname, $num);
+       data.set_num(solvid, keyname, num)
+       data.set_num(solvid, keyname, num)
+
+       void set_void(Id solvid, Id keyname);
+       $data->set_void($solvid, $keyname);
+       data.set_void(solvid, keyname)
+       data.set_void(solvid, keyname)
 
        void set_poolstr(Id solvid, Id keyname, const char *str);
        $data->set_poolstr($solvid, $keyname, $str);
@@ -3412,6 +3656,16 @@ SOLVID_META solvid that stores repodata meta information.
        data.set_checksum(solvid, keyname, chksum)
        data.set_checksum(solvid, keyname, chksum)
 
+       void set_sourcepkg(Id solvid, const char *sourcepkg);
+       $data.set_sourcepkg($solvid, $sourcepkg);
+       data.set_sourcepkg(solvid, sourcepkg)
+       data.set_sourcepkg(solvid, sourcepkg)
+
+       void set_location(Id solvid, unsigned int mediano, const char *location);
+       $data.set_location($solvid, $mediano, $location);
+       data.set_location(solvid, mediano, location)
+       data.set_location(solvid, mediano, location)
+
        void add_idarray(Id solvid, Id keyname, DepId id);
        $data->add_idarray($solvid, $keyname, $id);
        data.add_idarray(solvid, keyname, id)
@@ -3427,6 +3681,11 @@ SOLVID_META solvid that stores repodata meta information.
        data.add_flexarray(solvid, keyname, handle)
        data.add_flexarray(solvid, keyname, handle)
 
+       void unset(Id solvid, Id keyname);
+       $data->unset($solvid, $keyname);
+       data.unset(solvid, keyname)
+       data.unset(solvid, keyname)
+
 Data storage methods. Probably only useful to store data in the special
 SOLVID_META solvid that stores repodata meta information. Note that
 repodata areas can have their own Id pool (see the REPO_LOCALPOOL flag),
@@ -3463,9 +3722,9 @@ Back pointer to repository object.
 Create a Dataiterator at the position of the datapos object.
 
        const char *lookup_deltalocation(unsigned int *OUTPUT);
-       my ($location, $medianr) = $datapos->lookup_deltalocation();
-       location, medianr = datapos.lookup_deltalocation()
-       location, medianr = datapos.lookup_deltalocation()
+       my ($location, $mediano) = $datapos->lookup_deltalocation();
+       location, mediano = datapos.lookup_deltalocation()
+       location, mediano = datapos.lookup_deltalocation()
 
 Return a tuple containing the on-media location and an optional media number
 for a delta rpm. This obviously only works if the data position points to
@@ -3529,3 +3788,6 @@ Author
 ------
 Michael Schroeder <mls@suse.de>
 
+////
+vim: syntax=asciidoc
+////