From: Michael Schroeder Date: Tue, 28 May 2013 12:36:43 +0000 (+0200) Subject: document Dataiterator and Datamatch X-Git-Tag: upstream/0.4.0~123 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=e17f87287d77595779e94d26daba3d7ac68fcaa1;p=platform%2Fupstream%2Flibsolv.git document Dataiterator and Datamatch --- diff --git a/doc/libsolv-bindings.3 b/doc/libsolv-bindings.3 index 66c1ded..43f191d 100644 --- a/doc/libsolv-bindings.3 +++ b/doc/libsolv-bindings.3 @@ -2,12 +2,12 @@ .\" Title: libsolv-bindings .\" Author: [see the "Author" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 05/27/2013 +.\" Date: 05/28/2013 .\" Manual: LIBSOLV .\" Source: libsolv .\" Language: English .\" -.TH "LIBSOLV\-BINDINGS" "3" "05/27/2013" "libsolv" "LIBSOLV" +.TH "LIBSOLV\-BINDINGS" "3" "05/28/2013" "libsolv" "LIBSOLV" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -953,7 +953,7 @@ Back reference to the pool this dependency belongs to\&. .RE .\} .sp -Return the id of the repository\&. +The id of the repository\&. .sp .if n \{\ .RS 4 @@ -1883,8 +1883,8 @@ my \fI@ids\fR \fB=\fR \fI$solvable\fR\fB\->lookup_idarray(\fR\fI$keyname\fR\fB)\ .nf \fBQueue lookup_deparray(Id\fR \fIkeyname\fR\fB, Id\fR \fImarker\fR \fB= \-1)\fR my \fI@deps\fR \fB=\fR \fI$solvable\fR\fB\->lookup_deparray(\fR\fI$keyname\fR\fB)\fR; -\fIids\fR \fB=\fR \fIsolvable\fR\fB\&.lookup_deparray(\fR\fIkeyname\fR\fB)\fR -\fIids\fR \fB=\fR \fIsolvable\fR\fB\&.lookup_deparray(\fR\fIkeyname\fR\fB)\fR +\fIdeps\fR \fB=\fR \fIsolvable\fR\fB\&.lookup_deparray(\fR\fIkeyname\fR\fB)\fR +\fIdeps\fR \fB=\fR \fIsolvable\fR\fB\&.lookup_deparray(\fR\fIkeyname\fR\fB)\fR .fi .if n \{\ .RE @@ -1911,10 +1911,10 @@ Return a tuple containing the on\-media location and an optional media number fo .RS 4 .\} .nf -\fBvoid add_deparray(Id\fR \fIkeyname\fR\fB, DepId\fR \fIid\fR\fB, Id\fR \fImarker\fR \fB= \-1)\fR; -\fI$solvable\fR\fB\->add_deparray(\fR\fI$keyname\fR\fB,\fR \fI$depid\fR\fB)\fR; -\fIsolvable\fR\fB\&.add_deparray(\fR\fIkeyname\fR\fB,\fR \fIdepid\fR\fB)\fR -\fIsolvable\fR\fB\&.add_deparray(\fR\fIkeyname\fR\fB,\fR \fIdepid\fR\fB)\fR +\fBvoid add_deparray(Id\fR \fIkeyname\fR\fB, DepId\fR \fIdep\fR\fB, Id\fR \fImarker\fR \fB= \-1)\fR; +\fI$solvable\fR\fB\->add_deparray(\fR\fI$keyname\fR\fB,\fR \fI$dep\fR\fB)\fR; +\fIsolvable\fR\fB\&.add_deparray(\fR\fIkeyname\fR\fB,\fR \fIdep\fR\fB)\fR +\fIsolvable\fR\fB\&.add_deparray(\fR\fIkeyname\fR\fB,\fR \fIdep\fR\fB)\fR .fi .if n \{\ .RE @@ -2013,7 +2013,343 @@ Same as calling the str() method\&. Two solvables are equal if they are part of the same pool and have the same ids\&. .SH "THE DATAITERATOR CLASS" .sp -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\&. +.SS "CONSTANTS" +.PP +\fBSEARCH_STRING\fR +.RS 4 +Return a match if the search string matches the value\&. +.RE +.PP +\fBSEARCH_STRINGSTART\fR +.RS 4 +Return a match if the value starts with the search string\&. +.RE +.PP +\fBSEARCH_STRINGEND\fR +.RS 4 +Return a match if the value ends with the search string\&. +.RE +.PP +\fBSEARCH_SUBSTRING\fR +.RS 4 +Return a match if the search string can be matched somewhere in the value\&. +.RE +.PP +\fBSEARCH_GLOB\fR +.RS 4 +Do a glob match of the search string against the value\&. +.RE +.PP +\fBSEARCH_REGEX\fR +.RS 4 +Do a regular expression match of the search string against the value\&. +.RE +.PP +\fBSEARCH_NOCASE\fR +.RS 4 +Ignore case when matching strings\&. Works for all the above match types\&. +.RE +.PP +\fBSEARCH_FILES\fR +.RS 4 +Match the complete filenames of the file list, not just the base name\&. +.RE +.PP +\fBSEARCH_COMPLETE_FILELIST\fR +.RS 4 +When matching the file list, check every file of the package not just the subset from the primary metadata\&. +.RE +.PP +\fBSEARCH_CHECKSUMS\fR +.RS 4 +Allow the matching of checksum entries\&. +.RE +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid prepend_keyname(Id\fR \fIkeyname\fR\fB)\fR; +\fI$di\fR\fB\->prepend_keyname(\fR\fI$keyname\fR\fB)\fR; +\fIdi\fR\fB\&.prepend_keyname(\fR\fIkeyname\fR\fB)\fR +\fIdi\fR\fB\&.prepend_keyname(\fR\fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Do a sub\-search in the array stored in keyname\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid skip_solvable()\fR; +\fI$di\fR\fB\->kip_solvable()\fR; +\fIdi\fR\fB\&.skip_solvable()\fR +\fIdi\fR\fB\&.skip_solvable()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Stop matching the current solvable and advance to the next one\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +\fBfor my\fR \fI$d\fR \fB(\fR\fI@$di\fR\fB)\fR +\fBfor\fR \fId\fR \fBin\fR \fIdi\fR\fB:\fR +\fBfor\fR \fId\fR \fBin\fR \fIdi\fR +.fi +.if n \{\ +.RE +.\} +.sp +Iterate through the matches\&. If there is a match, the object in d will be of type Datamatch\&. +.SH "THE DATAMATCH CLASS" +.sp +Objects of this type will be created for every value matched by a dataiterator\&. +.SS "ATTRIBUTES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBPool *pool;\fR /* read only */ +\fI$d\fR\fB\->{\*(Aqpool\*(Aq}\fR +\fId\fR\fB\&.pool\fR +\fId\fR\fB\&.pool\fR +.fi +.if n \{\ +.RE +.\} +.sp +Back pointer to pool\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepo *repo;\fR /* read only */ +\fI$d\fR\fB\->{\*(Aqrepo\*(Aq}\fR +\fId\fR\fB\&.repo\fR +\fId\fR\fB\&.repo\fR +.fi +.if n \{\ +.RE +.\} +.sp +The repository containing the matched object\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvable *solvable;\fR /* read only */ +\fI$d\fR\fB\->{\*(Aqsolvable\*(Aq}\fR +\fId\fR\fB\&.solvable\fR +\fId\fR\fB\&.solvable\fR +.fi +.if n \{\ +.RE +.\} +.sp +The solvable containing the value that was matched\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId solvid;\fR /* read only */ +\fI$d\fR\fB\->{\*(Aqsolvid\*(Aq}\fR +\fId\fR\fB\&.solvid\fR +\fId\fR\fB\&.solvid\fR +.fi +.if n \{\ +.RE +.\} +.sp +The id of the solvable that matched\&. +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId key_id()\fR; +\fI$d\fR\fB\->key_id()\fR +\fId\fR\fB\&.key_id()\fR +\fId\fR\fB\&.key_id()\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *key_idstr()\fR; +\fI$d\fR\fB\->key_idstr()\fR +\fId\fR\fB\&.key_idstr()\fR +\fId\fR\fB\&.key_idstr()\fR +.fi +.if n \{\ +.RE +.\} +.sp +The keyname that matched, either as id or string\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId type_id()\fR; +\fI$d\fR\fB\->type_id()\fR +\fId\fR\fB\&.type_id()\fR +\fId\fR\fB\&.type_id()\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *type_idstr()\fR; +\fI$d\fR\fB\->type_idstr()\fR; +\fId\fR\fB\&.type_idstr()\fR +\fId\fR\fB\&.type_idstr()\fR +.fi +.if n \{\ +.RE +.\} +.sp +The key type of the value that was matched, either as id or string\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId id()\fR; +\fI$d\fR\fB\->id()\fR +\fId\fR\fB\&.id()\fR +\fId\fR\fB\&.id()\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId idstr()\fR; +\fI$d\fR\fB\->idstr()\fR +\fId\fR\fB\&.idstr()\fR +\fId\fR\fB\&.idstr()\fR +.fi +.if n \{\ +.RE +.\} +.sp +The Id of the value that was matched (only valid for id types), either as id or string\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *str()\fR; +\fI$d\fR\fB\->str()\fR +\fId\fR\fB\&.str()\fR +\fId\fR\fB\&.str()\fR +.fi +.if n \{\ +.RE +.\} +.sp +The string value that was matched (only valid for string types)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBunsigned long long num()\fR; +\fI$d\fR\fB\->num()\fR +\fId\fR\fB\&.num()\fR +\fId\fR\fB\&.num()\fR +.fi +.if n \{\ +.RE +.\} +.sp +The numeric value that was matched (only valid for numeric types)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBunsigned int num2()\fR; +\fI$d\fR\fB\->num2()\fR +\fId\fR\fB\&.num2()\fR +\fId\fR\fB\&.num2()\fR +.fi +.if n \{\ +.RE +.\} +.sp +The secondary numeric value that was matched (only valid for types containing two values)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBDatapos *pos()\fR; +my \fI$pos\fR \fB=\fR \fI$d\fR\fB\->pos()\fR; +\fIpos\fR \fB=\fR \fId\fR\fB\&.pos()\fR +\fIpos\fR \fB=\fR \fId\fR\fB\&.pos()\fR +.fi +.if n \{\ +.RE +.\} +.sp +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\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBDatapos *parentpos()\fR; +my \fI$pos\fR \fB=\fR \fI$d\fR\fB\->parentpos()\fR; +\fIpos\fR \fB=\fR \fId\fR\fB\&.parentpos()\fR +\fIpos\fR \fB=\fR \fId\fR\fB\&.parentpos()\fR +.fi +.if n \{\ +.RE +.\} +.sp +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\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +my \fI$str\fR \fB= "\fR\fI$d\fR\fB"\fR; +\fIstr\fR \fB= str(\fR\fId\fR\fB)\fR +\fIstr\fR \fB=\fR \fId\fR\fB\&.to_s\fR +.fi +.if n \{\ +.RE +.\} +.sp +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\&. .SH "THE SELECTION CLASS" .sp xxx 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. + + + 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. + + + 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()