document Dataiterator and Datamatch

1 files changed, 202 insertions, 10 deletions

diff --git a/doc/libsolv-bindings.txt b/doc/libsolv-bindings.txt
index dddccbd..4acec0f 100644
--- a/doc/libsolv-bindings.txt
+++ b/doc/libsolv-bindings.txt
@@ -550,7 +550,7 @@ Back reference to the pool this dependency belongs to.
 	repo.id
 	repo.id
 
-Return the id of the repository.
+The id of the repository.
 
 	const char *name;		/* read/write */
 	$repo->{'name'}
@@ -1057,8 +1057,8 @@ a specific id and want to avoid the string compare overhead.
 
 	Queue lookup_deparray(Id keyname, Id marker = -1)
 	my @deps = $solvable->lookup_deparray($keyname);
-	ids = solvable.lookup_deparray(keyname)
-	ids = 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
@@ -1080,10 +1080,10 @@ Return a tuple containing the on-media location and an optional
 media number for multi-part repositories (e.g. repositories
 spawning multiple DVDs).
 
-	void add_deparray(Id keyname, DepId id, Id marker = -1);
-	$solvable->add_deparray($keyname, $depid);
-	solvable.add_deparray(keyname, depid)
-	solvable.add_deparray(keyname, depid)
+	void add_deparray(Id keyname, DepId dep, Id marker = -1);
+	$solvable->add_deparray($keyname, $dep);
+	solvable.add_deparray(keyname, dep)
+	solvable.add_deparray(keyname, dep)
 
 Add a new dependency to the attributes stored in keyname.
 
@@ -1134,7 +1134,199 @@ ids.
 
 THE DATAITERATOR CLASS
 ----------------------
-xxx
+
+Dataiterators can be used to do complex string searches or
+to iterate over arrays. They can be created via the
+constructors in the Pool, Repo, and Solvable classes. The
+Repo and Solvable constructors will limit the search to
+the repository or the specific package.
+
+=== CONSTANTS ===
+
+*SEARCH_STRING*::
+  Return a match if the search string matches the value.
+
+*SEARCH_STRINGSTART*::
+  Return a match if the value starts with the search string.
+
+*SEARCH_STRINGEND*::
+  Return a match if the value ends with the search string.
+
+*SEARCH_SUBSTRING*::
+  Return a match if the search string can be matched somewhere
+  in the value.
+
+*SEARCH_GLOB*::
+  Do a glob match of the search string against the value.
+
+*SEARCH_REGEX*::
+  Do a regular expression match of the search string against
+  the value.
+
+*SEARCH_NOCASE*::
+  Ignore case when matching strings. Works for all the above
+  match types.
+
+*SEARCH_FILES*::
+  Match the complete filenames of the file list, not just the
+  base name.
+
+*SEARCH_COMPLETE_FILELIST*::
+  When matching the file list, check every file of the package
+  not just the subset from the primary metadata.
+
+*SEARCH_CHECKSUMS*::
+  Allow the matching of checksum entries.
+
+=== METHODS ===
+
+	void prepend_keyname(Id keyname);
+	$di->prepend_keyname($keyname);
+	di.prepend_keyname(keyname)
+	di.prepend_keyname(keyname)
+
+Do a sub-search in the array stored in keyname.
+
+	void skip_solvable();
+	$di->kip_solvable();
+	di.skip_solvable()
+	di.skip_solvable()
+
+Stop matching the current solvable and advance to the next
+one.
+
+	<iteration>
+	for my $d (@$di)
+	for d in di:
+	for d in di
+
+Iterate through the matches. If there is a match, the object
+in d will be of type Datamatch.
+
+THE DATAMATCH CLASS
+-------------------
+Objects of this type will be created for every value matched
+by a dataiterator.
+
+=== ATTRIBUTES ===
+
+	Pool *pool;				/* read only */
+	$d->{'pool'}
+	d.pool
+	d.pool
+
+Back pointer to pool.
+
+	Repo *repo;				/* read only */
+	$d->{'repo'}
+	d.repo
+	d.repo
+
+The repository containing the matched object.
+
+	Solvable *solvable;			/* read only */
+	$d->{'solvable'}
+	d.solvable
+	d.solvable
+
+The solvable containing the value that was matched.
+
+	Id solvid;				/* read only */
+	$d->{'solvid'}
+	d.solvid
+	d.solvid
+
+The id of the solvable that matched.
+
+=== METHODS ===
+
+	Id key_id();
+	$d->key_id()
+	d.key_id()
+	d.key_id()
+
+	const char *key_idstr();
+	$d->key_idstr()
+	d.key_idstr()
+	d.key_idstr()
+
+The keyname that matched, either as id or string.
+
+	Id type_id();
+	$d->type_id()
+	d.type_id()
+	d.type_id()
+
+	const char *type_idstr();
+	$d->type_idstr();
+	d.type_idstr()
+	d.type_idstr()
+
+The key type of the value that was matched, either as id or string.
+
+	Id id();
+	$d->id()
+	d.id()
+	d.id()
+
+	Id idstr();
+	$d->idstr()
+	d.idstr()
+	d.idstr()
+
+The Id of the value that was matched (only valid for id types),
+either as id or string.
+
+	const char *str();
+	$d->str()
+	d.str()
+	d.str()
+
+The string value that was matched (only valid for string types).
+
+	unsigned long long num();
+	$d->num()
+	d.num()
+	d.num()
+
+The numeric value that was matched (only valid for numeric types).
+
+	unsigned int num2();
+	$d->num2()
+	d.num2()
+	d.num2()
+
+The secondary numeric value that was matched (only valid for types
+containing two values).
+
+	Datapos *pos();
+	my $pos = $d->pos();
+	pos = d.pos()
+	pos = d.pos()
+
+The position object of the current match. It can be used to do
+sub-searches starting at the match (if it is of an array type).
+See the Datapos class for more information.
+
+	Datapos *parentpos();
+	my $pos = $d->parentpos();
+	pos = d.parentpos()
+	pos = d.parentpos()
+
+The position object of the array containing the current match.
+It can be used to do sub-searches, see the Datapos class for more
+information.
+
+	<stringification>
+	my $str = "$d";
+	str = str(d)
+	str = d.to_s
+
+Return the stringification of the matched value. Stringification
+depends on the search flags, for file list entries it will return
+just the base name unless SEARCH_FILES is used, for checksums
+it will return an empty string unless SEARCH_CHECKSUMS is used.
+Numeric values are currently stringified to an empty string.
 
 THE SELECTION CLASS
 -------------------
@@ -1225,9 +1417,9 @@ Same as add_stat, but instead of the filename a file descriptor is used.
 	raw = chksum.raw()
 
 Finalize the checksum and return the result as raw bytes. This means that the
-result can contain zero bytes or unprintable characters.
+result can contain NUL bytes or unprintable characters.
 
-	unsigned char *hex()
+	const char *hex()
 	my $raw = $chksum->hex();
 	raw = chksum.hex()
 	raw = chksum.hex()