zypp::PoolQuery Class Reference

Meta-data query API. More...

#include <PoolQuery.h>

Inheritance diagram for zypp::PoolQuery:
[legend]

List of all members.

Classes

class  Impl

Public Types

typedef std::set< ResKindKinds
typedef std::set< std::string > StrContainer
typedef std::map
< sat::SolvAttr, StrContainer
AttrRawStrMap
typedef detail::PoolQueryIterator const_iterator
typedef unsigned int size_type
typedef function< bool(const
sat::Solvable &)> 
ProcessResolvable

Public Member Functions

 PoolQuery ()
 ~PoolQuery ()
void execute (ProcessResolvable fnc)
 Executes the query with the current settings.
void addKind (const ResKind &kind)
 Filter by selectable kind.
void addRepo (const std::string &repoalias)
 Filter by repo.
void addString (const std::string &value)
 Add a global query string.
void addAttribute (const sat::SolvAttr &attr, const std::string &value="")
 Filter by the value of the specified attr attribute.
void setEdition (const Edition &edition, const Rel &op=Rel::EQ)
 Set version condition.
void setRequireAll (bool require_all=true)
 Require that all of the values set by addString or addAttribute match the values of respective attributes.
bool recover (std::istream &str, char delim= '\n')
 Reads from stream query.
void serialize (std::ostream &str, char delim= '\n') const
 Writes a machine-readable string representation of the query to stream.
std::string asString () const
 Return a human-readable description of the query.
bool operator== (const PoolQuery &b) const
bool operator!= (const PoolQuery &b) const
Match flags () const
 Free function to get the satsolver repo search flags.
void setFlags (const Match &flags)
 Free function to set the satsolver repo search flags.
const_iterator begin () const
 Query result accessers.
const_iterator end () const
 An iterator pointing to the end of the query result.
bool empty () const
 Whether the result is empty.
size_type size () const
 Number of solvables in the query result.
Filter by dependencies matching a broken down capability <tt>name [op edition]</tt>.
The capabilities name part may be defined as query string like with addAttribute.

Globing and regex are supported. Global query strings defined by addString are considered.

So without any op edition addDependency behaves the same as addAttribute. If an edition range is given, matches are restricted accordingly. Thete are various overloads, so pick the one you like best.

 {
   setMatchGlob();
   setCaseSensitive( false );
   addDependency( sat::SolvAttr::provides, "kde*", Rel::EQ, Edition("2.0") );
   addDependency( sat::SolvAttr::provides, "kde*", Edition("2.0") ); // same as above
 }
 {
   setMatchGlob();
   setCaseSensitive( false );
   addString( "kde*" );
   addDependency( sat::SolvAttr::provides, Rel::EQ, Edition("2.0") );// same as above
   addDependency( sat::SolvAttr::provides, Edition("2.0") );         // same as above
 }

Note:
Thre's also a version of addDependency provided, that takes a complete Capability as argument. This always requires an exact match of the name part (as the resolver would do it).
This is the list of valid dependency attributes:
   SolvAttr::provides
   SolvAttr::obsoletes
   SolvAttr::conflicts
   SolvAttr::requires
   SolvAttr::recommends
   SolvAttr::suggests
   SolvAttr::supplements
   SolvAttr::enhances

Note:
What happens if a non dependency attribute is passed?< > If an edition range is given, it is matched against the matching solvables edition instead. Without edition range it behaves the same as addAttribute.
   // Find all packages providing "kernel > 2.0"
   addDependency( sat::SolvAttr::provides, "kernel", Rel::GT, Edition("2.0") );

   // // Find all packages named "kernel" and with edition "> 2.0"
   addDependency( sat::SolvAttr::name, "kernel", Rel::GT, Edition("2.0") );


void addDependency (const sat::SolvAttr &attr, const std::string &name, const Rel &op, const Edition &edition)
 Query "name|global op edition".
void addDependency (const sat::SolvAttr &attr, const std::string &name, const Edition &edition)
void addDependency (const sat::SolvAttr &attr, const std::string &name)
void addDependency (const sat::SolvAttr &attr, const Rel &op, const Edition &edition)
void addDependency (const sat::SolvAttr &attr, const Edition &edition)
void addDependency (const sat::SolvAttr &attr)
void addDependency (const sat::SolvAttr &attr, Capability cap_r)
Text Matching Options
Note:
The implementation treats an empty search string as <it>"match always"</it>. So if you want to actually match an empty value, try ( "^$", setMatchRegex ).


void setCaseSensitive (bool value=true)
 Turn case sentitivity on or off (unsets or sets SEARCH_NOCASE flag).
void setFilesMatchFullPath (bool value=true)
 If set (default), look at the full path when searching in filelists.
void setFilesMatchBasename (bool value=true)
void setMatchExact ()
 Set to match exact string instead of substring.
void setMatchSubstring ()
 Set to substring (the default).
void setMatchGlob ()
 Set to match globs.
void setMatchRegex ()
 Set to use the query strings as regexes.
void setMatchWord ()
 Set to match words (uses regex).
getters
const StrContainerstrings () const
 Search strings added via addString().
const AttrRawStrMapattributes () const
 Map (map<SolvAttr, StrContainer>) of attribute values added via addAttribute(), addDep in string form.
const StrContainerattribute (const sat::SolvAttr &attr) const
const Kindskinds () const
const StrContainerrepos () const
const Edition edition () const
const Rel editionRel () const
bool caseSensitive () const
 returns true if search is case sensitive
bool filesMatchFullPath () const
 Whether searching in filelists looks at the full path or just at the basenames.
bool filesMatchBasename () const
bool matchExact () const
bool matchSubstring () const
bool matchGlob () const
bool matchRegex () const
bool matchWord () const
Match::Mode matchMode () const
 Returns string matching mode as enum.
bool requireAll () const
 Whether all values added via addString() or addAttribute() are required to match the values of the respective attributes.
StatusFilter statusFilterFlags () const

Private Attributes

RW_pointer< Impl_pimpl
 Pointer to implementation.

Related Functions

(Note that these are not member functions.)

std::ostream & operator<< (std::ostream &str, const PoolQuery &obj)
std::ostream & dumpOn (std::ostream &str, const PoolQuery &obj)
enum  StatusFilter { ALL = 0, INSTALLED_ONLY = 1, UNINSTALLED_ONLY = 2 }
 Installed status filter setters. More...
void setInstalledOnly ()
 Return only repo packages.
void setUninstalledOnly ()
 Return only packages from repos other than .
void setStatusFilterFlags (StatusFilter flags)
 Set status filter directly.


Detailed Description

Meta-data query API.

Returns solvables of specified kinds from specified repositories with attributes matching the specified search strings.

The search strings can be specified via addString() and addAttribute() methods. String matching type can be set using the setMatch*() methods. Multiple search strings for a particular attribute will be combined into a regex (see addString() and addAttribute() for more details).

The begin() and end() methods return a PoolQueryIterator returning sat::Solvable objects which can easily be turned into Resolvable objects. Additionally, thanx to the sat::SolvIterMixin, a Selectable and PoolItem iterators are automatically available.

Note:
You will sometimes face the problem, that when using the PoolItem iterator you hit multiple version of the same package, while when using the ui::Selectable iterator the information which of the available candidates actually matched got lost. In this case class PoolItemBest may help you. Use it to pick the best version only.
PoolQuery q; q.addAttribute(sat::SolvAttr::name, "zypp*"); q.addKind(ResKind::package); q.setMatchGlob();

for (PoolQuery::Selectable_iterator it = q.selectableBegin(); it != q.selectableEnd(); ++it) { ui::Selectable::constPtr s = *it; // ... }

Performance considerations

Results of simple queries like those using one string and/or one attribute and/or one repository are filtered by sat-solver's Dataiterator directly, and thus it is fast.

Queries with multiple strings are implemented using regexes. Queries based on kinds, multiple repos, and multiple attributes are filtered inside the PoolQuery, so these tend to be slower.

See also:
detail::PoolQueryIterator on how to inspect matches in detail.

tests/zypp/PoolQuery_test.cc for more examples

sat::SolvIterMixin

Definition at line 90 of file PoolQuery.h.


Member Typedef Documentation

typedef std::set<ResKind> zypp::PoolQuery::Kinds

Definition at line 93 of file PoolQuery.h.

typedef std::set<std::string> zypp::PoolQuery::StrContainer

Definition at line 94 of file PoolQuery.h.

Definition at line 95 of file PoolQuery.h.

Definition at line 97 of file PoolQuery.h.

typedef unsigned int zypp::PoolQuery::size_type

Reimplemented from zypp::sat::SolvIterMixin< PoolQuery, detail::PoolQueryIterator >.

Definition at line 98 of file PoolQuery.h.

typedef function<bool( const sat::Solvable & )> zypp::PoolQuery::ProcessResolvable

Definition at line 101 of file PoolQuery.h.


Member Enumeration Documentation

Installed status filter setters.

Filter by status (installed uninstalled)

Enumerator:
ALL 
INSTALLED_ONLY 
UNINSTALLED_ONLY 

Definition at line 162 of file PoolQuery.h.


Constructor & Destructor Documentation

zypp::PoolQuery::PoolQuery (  ) 

Definition at line 780 of file PoolQuery.cc.

zypp::PoolQuery::~PoolQuery (  ) 

Definition at line 784 of file PoolQuery.cc.


Member Function Documentation

detail::PoolQueryIterator zypp::PoolQuery::begin (  )  const

Query result accessers.

Compile the query and return an iterator to the result.

Returns:
An iterator (detail::PoolQueryIterator) returning sat::Solvable objects pointing at the beginning of the query result.
Exceptions:
sat::MatchInvalidRegexException if the query was about to use a regex which failed to compile.
Note:
Note that PoolQuery is derived from sat::SolvIterMixin which makes PoolItem and Selectable iterators automatically available.
See also:
sat::SolvIterMixin

Definition at line 1657 of file PoolQuery.cc.

References _pimpl, and zypp::RW_pointer< _D, _Traits >::getPtr().

Referenced by zypp::Locks::addLock(), zypp::LocksRemovePredicate::contains(), zypp::dumpOn(), empty(), execute(), zypp::ApplyLock::operator()(), zypp::PoolQueryResult::operator+=(), zypp::PoolQueryResult::operator-=(), zypp::Locks::removeLock(), and size().

detail::PoolQueryIterator zypp::PoolQuery::end (  )  const [inline]

bool zypp::PoolQuery::empty (  )  const

Whether the result is empty.

Reimplemented from zypp::sat::SolvIterMixin< PoolQuery, detail::PoolQueryIterator >.

Definition at line 939 of file PoolQuery.cc.

References begin(), and end().

Referenced by zypp::LocksCleanPredicate::operator()().

PoolQuery::size_type zypp::PoolQuery::size (  )  const

Number of solvables in the query result.

Reimplemented from zypp::sat::SolvIterMixin< PoolQuery, detail::PoolQueryIterator >.

Definition at line 946 of file PoolQuery.cc.

References begin(), end(), and for_.

void zypp::PoolQuery::execute ( ProcessResolvable  fnc  ) 

Executes the query with the current settings.

Results are yielded via the fnc callback.

Definition at line 959 of file PoolQuery.cc.

References begin(), end(), and zypp::invokeOnEach().

void zypp::PoolQuery::addKind ( const ResKind kind  ) 

Filter by selectable kind.

By default, all kinds will be returned. If addKind() is used, only the specified kinds will be returned (multiple kinds will be ORed).

Pass ResKind constants to this method, (e.g. ResKind::package).

Definition at line 797 of file PoolQuery.cc.

References _pimpl.

Referenced by zypp::Locks::addLock(), and zypp::Locks::removeLock().

void zypp::PoolQuery::addRepo ( const std::string &  repoalias  ) 

Filter by repo.

By default, all repos will be returned. If addRepo() is used, only the specified repo will be returned (multiple repos will be ORed).

Definition at line 787 of file PoolQuery.cc.

References _pimpl, and WAR.

void zypp::PoolQuery::setInstalledOnly (  ) 

Return only repo packages.

Definition at line 872 of file PoolQuery.cc.

References _pimpl, and INSTALLED_ONLY.

void zypp::PoolQuery::setUninstalledOnly (  ) 

Return only packages from repos other than .

Definition at line 874 of file PoolQuery.cc.

References _pimpl, and UNINSTALLED_ONLY.

void zypp::PoolQuery::setStatusFilterFlags ( PoolQuery::StatusFilter  flags  ) 

Set status filter directly.

See also:
StatusFilter

Definition at line 876 of file PoolQuery.cc.

References _pimpl.

void zypp::PoolQuery::addString ( const std::string &  value  ) 

Add a global query string.

The string added via this method is applied to all query attributes as if addAttribute(..., ) was called for all of them.

This method can be used multiple times in which case the query strings will be combined (together with strings added via addAttribute()) into a regex. Searched attribute value will match this regex if any of these strings will match the value. This can be changed by (not yet implemented) setRequireAll() method.

void zypp::PoolQuery::addAttribute ( const sat::SolvAttr attr,
const std::string &  value = "" 
)

Filter by the value of the specified attr attribute.

This can be any of the available solvable attributes.

This method can be used multiple times with the same attr in which case the query strings will be combined (together with strings added via addString()) into a regex. Searched attribute value will match this regex if any of these strings will match the value. This can be changed by (not yet implemented) setRequireAll() method.

Note:
Though it is possible to use dependency attributes like Solv::Attr::provides here, note that the query string is matched against a dependencies "name" part only. Any "op edition" part of a Capability is not considered at all.
See also:
addDependency on how to query for capabilities including edition ranges.
Note:
Solvables of a kind not supporting the specified attribute will not be returned.
Todo:
check the above
Parameters:
attr Attribute identfier. Use sat::Solvattr::* constants
value What to search for.
See also:
sat::SolvAttr

Definition at line 803 of file PoolQuery.cc.

References _pimpl.

Referenced by addDependency(), zypp::Locks::addLock(), and zypp::Locks::removeLock().

void zypp::PoolQuery::addDependency ( const sat::SolvAttr attr,
const std::string &  name,
const Rel op,
const Edition edition 
)

Query "name|global op edition".

Definition at line 806 of file PoolQuery.cc.

References _pimpl, addAttribute(), zypp::Rel::ANY_e, zypp::Rel::inSwitch(), zypp::Rel::NONE_e, and zypp::Match::OTHER.

void zypp::PoolQuery::addDependency ( const sat::SolvAttr attr,
const std::string &  name,
const Edition edition 
) [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 280 of file PoolQuery.h.

References addDependency(), and zypp::Rel::EQ.

Referenced by addDependency().

void zypp::PoolQuery::addDependency ( const sat::SolvAttr attr,
const std::string &  name 
) [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 284 of file PoolQuery.h.

References addDependency(), and zypp::Rel::ANY.

Referenced by addDependency().

void zypp::PoolQuery::addDependency ( const sat::SolvAttr attr,
const Rel op,
const Edition edition 
) [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 288 of file PoolQuery.h.

References addDependency().

Referenced by addDependency().

void zypp::PoolQuery::addDependency ( const sat::SolvAttr attr,
const Edition edition 
) [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 292 of file PoolQuery.h.

References addDependency(), and zypp::Rel::EQ.

Referenced by addDependency().

void zypp::PoolQuery::addDependency ( const sat::SolvAttr attr  )  [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 296 of file PoolQuery.h.

References addDependency(), and zypp::Rel::ANY.

Referenced by addDependency().

void zypp::PoolQuery::addDependency ( const sat::SolvAttr attr,
Capability  cap_r 
)

void zypp::PoolQuery::setEdition ( const Edition edition,
const Rel op = Rel::EQ 
)

Set version condition.

This will filter out solvables not matching solvableEdition op edition.

Parameters:
edition Edition to look for.
op Found-wanted relation operator.

Definition at line 850 of file PoolQuery.cc.

References _pimpl.

void zypp::PoolQuery::setCaseSensitive ( bool  value = true  ) 

Turn case sentitivity on or off (unsets or sets SEARCH_NOCASE flag).

PoolQuery defaults to case insensitive search unless this method is used.

Parameters:
value Whether to turn the case sensitivity on (default) or off.

Definition at line 917 of file PoolQuery.cc.

References _pimpl, and zypp::Match::NOCASE.

Referenced by zypp::Locks::addLock(), and zypp::Locks::removeLock().

void zypp::PoolQuery::setFilesMatchFullPath ( bool  value = true  ) 

If set (default), look at the full path when searching in filelists.

Otherwise just match the the basenames.

See also:
Match::FILES

Definition at line 922 of file PoolQuery.cc.

References _pimpl, and zypp::Match::FILES.

Referenced by setFilesMatchBasename().

void zypp::PoolQuery::setFilesMatchBasename ( bool  value = true  )  [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 337 of file PoolQuery.h.

References setFilesMatchFullPath().

void zypp::PoolQuery::setMatchExact (  ) 

Set to match exact string instead of substring.

Definition at line 857 of file PoolQuery.cc.

References _pimpl.

Referenced by zypp::Locks::addLock(), and zypp::Locks::removeLock().

void zypp::PoolQuery::setMatchSubstring (  ) 

Set to substring (the default).

Definition at line 856 of file PoolQuery.cc.

References _pimpl.

void zypp::PoolQuery::setMatchGlob (  ) 

Set to match globs.

Definition at line 859 of file PoolQuery.cc.

References _pimpl.

void zypp::PoolQuery::setMatchRegex (  ) 

Set to use the query strings as regexes.

Definition at line 858 of file PoolQuery.cc.

References _pimpl.

void zypp::PoolQuery::setMatchWord (  ) 

Set to match words (uses regex).

Definition at line 860 of file PoolQuery.cc.

References _pimpl.

void zypp::PoolQuery::setRequireAll ( bool  require_all = true  ) 

Require that all of the values set by addString or addAttribute match the values of respective attributes.

Todo:
doesn't work yet, don't use this function

Definition at line 880 of file PoolQuery.cc.

References _pimpl.

const PoolQuery::StrContainer & zypp::PoolQuery::strings (  )  const

Search strings added via addString().

Definition at line 885 of file PoolQuery.cc.

References _pimpl.

const PoolQuery::AttrRawStrMap & zypp::PoolQuery::attributes (  )  const

Map (map<SolvAttr, StrContainer>) of attribute values added via addAttribute(), addDep in string form.

Definition at line 889 of file PoolQuery.cc.

References _pimpl.

const PoolQuery::StrContainer & zypp::PoolQuery::attribute ( const sat::SolvAttr attr  )  const

Definition at line 893 of file PoolQuery.cc.

References _pimpl.

const PoolQuery::Kinds & zypp::PoolQuery::kinds (  )  const

Definition at line 907 of file PoolQuery.cc.

References _pimpl.

const PoolQuery::StrContainer & zypp::PoolQuery::repos (  )  const

Definition at line 911 of file PoolQuery.cc.

References _pimpl.

const Edition zypp::PoolQuery::edition (  )  const

Definition at line 900 of file PoolQuery.cc.

References _pimpl.

const Rel zypp::PoolQuery::editionRel (  )  const

Definition at line 902 of file PoolQuery.cc.

References _pimpl.

bool zypp::PoolQuery::caseSensitive (  )  const

returns true if search is case sensitive

Definition at line 915 of file PoolQuery.cc.

References _pimpl, and zypp::Match::NOCASE.

bool zypp::PoolQuery::filesMatchFullPath (  )  const

Whether searching in filelists looks at the full path or just at the basenames.

Definition at line 920 of file PoolQuery.cc.

References _pimpl, and zypp::Match::FILES.

Referenced by filesMatchBasename().

bool zypp::PoolQuery::filesMatchBasename (  )  const [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 389 of file PoolQuery.h.

References filesMatchFullPath().

bool zypp::PoolQuery::matchExact (  )  const

Definition at line 925 of file PoolQuery.cc.

References _pimpl.

bool zypp::PoolQuery::matchSubstring (  )  const

Definition at line 926 of file PoolQuery.cc.

References _pimpl.

bool zypp::PoolQuery::matchGlob (  )  const

Definition at line 927 of file PoolQuery.cc.

References _pimpl.

bool zypp::PoolQuery::matchRegex (  )  const

Definition at line 928 of file PoolQuery.cc.

References _pimpl.

bool zypp::PoolQuery::matchWord (  )  const

Definition at line 930 of file PoolQuery.cc.

References _pimpl.

Match::Mode zypp::PoolQuery::matchMode (  )  const [inline]

Returns string matching mode as enum.

See also:
Match::Mode

Definition at line 401 of file PoolQuery.h.

References flags(), and zypp::Match::mode().

bool zypp::PoolQuery::requireAll (  )  const

Whether all values added via addString() or addAttribute() are required to match the values of the respective attributes.

Definition at line 933 of file PoolQuery.cc.

References _pimpl.

Referenced by zypp::Locks::removeLock().

PoolQuery::StatusFilter zypp::PoolQuery::statusFilterFlags (  )  const

Definition at line 936 of file PoolQuery.cc.

References _pimpl.

bool zypp::PoolQuery::recover ( std::istream &  str,
char  delim = '\n' 
)

Reads from stream query.

Attributes is sepated by delim. Query is separated by two delim.

Parameters:
str input stream which contains query
delim delimeter for attributes
Returns:
true if non-empty query is recovered
See also:
readPoolQueriesFromFile

Referenced by zypp::readPoolQueriesFromFile().

void zypp::PoolQuery::serialize ( std::ostream &  str,
char  delim = '\n' 
) const

Writes a machine-readable string representation of the query to stream.

Use delim as attribute delimiter.

Parameters:
str output stream to write to
delim delimiter for attributes
See also:
writePoolQueriesToFile

string zypp::PoolQuery::asString (  )  const

Return a human-readable description of the query.

Definition at line 1334 of file PoolQuery.cc.

References _pimpl.

Referenced by zypp::operator<<().

bool zypp::PoolQuery::operator== ( const PoolQuery b  )  const

Definition at line 1343 of file PoolQuery.cc.

References _pimpl.

bool zypp::PoolQuery::operator!= ( const PoolQuery b  )  const [inline]

Definition at line 440 of file PoolQuery.h.

Match zypp::PoolQuery::flags (  )  const

Free function to get the satsolver repo search flags.

See also:
Match

Definition at line 866 of file PoolQuery.cc.

References _pimpl.

Referenced by matchMode().

void zypp::PoolQuery::setFlags ( const Match flags  ) 

Free function to set the satsolver repo search flags.

See also:
Match

Definition at line 868 of file PoolQuery.cc.

References _pimpl.


Friends And Related Function Documentation

std::ostream & operator<< ( std::ostream &  str,
const PoolQuery obj 
) [related]

Stream output.

std::ostream & dumpOn ( std::ostream &  str,
const PoolQuery obj 
) [related]

Detailed stream output.

Definition at line 1340 of file PoolQuery.cc.


Member Data Documentation


The documentation for this class was generated from the following files:

doxygen