1 /*---------------------------------------------------------------------\
3 | |__ / \ / / . \ . \ |
8 \---------------------------------------------------------------------*/
9 /** \file zypp/PoolQuery.h
12 #ifndef ZYPP_POOLQUERY_H
13 #define ZYPP_POOLQUERY_H
19 #include "zypp/base/Regex.h"
20 #include "zypp/base/PtrTypes.h"
21 #include "zypp/base/Function.h"
23 #include "zypp/sat/SolvIterMixin.h"
24 #include "zypp/sat/LookupAttr.h"
25 #include "zypp/sat/AttrMatcher.h"
26 #include "zypp/sat/Pool.h"
28 ///////////////////////////////////////////////////////////////////
30 { /////////////////////////////////////////////////////////////////
34 class PoolQueryIterator;
37 ///////////////////////////////////////////////////////////////////
39 // CLASS NAME : PoolQuery
42 * Meta-data query API. Returns solvables of specified kinds from specified
43 * repositories with attributes matching the specified search strings.
45 * The search strings can be specified via \ref addString() and
46 * \ref addAttribute() methods. String matching type can be set using the
47 * setMatch*() methods. Multiple search strings for a particular attribute
48 * will be combined into a regex (see \ref addString() and
49 * \ref addAttribute() for more details).
51 * The begin() and end() methods return a PoolQueryIterator returning
52 * \ref sat::Solvable objects which can easily be turned into \ref Resolvable
53 * objects. Additionally, thanx to the \ref sat::SolvIterMixin, a Selectable
54 * and PoolItem iterators are automatically available.
58 * q.addAttribute(sat::SolvAttr::name, "zypp*");
59 * q.addKind(ResKind::package);
62 * for (PoolQuery::Selectable_iterator it = q.selectableBegin();
63 * it != q.selectableEnd(); ++it)
65 * ui::Selectable::constPtr s = *it;
70 * Performance considerations
72 * Results of simple queries like those using one string and/or one attribute
73 * and/or one repository are filtered by sat-solver's Dataiterator directly,
74 * and thus it is fast.
76 * Queries with multiple strings are implemented using regexes. Queries based
77 * on kinds, multiple repos, and multiple attributes are filtered inside
78 * the PoolQuery, so these tend to be slower.
80 * \see tests/zypp/PoolQuery_test.cc for more examples
81 * \see sat::SolvIterMixin
83 class PoolQuery : public sat::SolvIterMixin<PoolQuery, detail::PoolQueryIterator>
86 typedef std::set<std::string> StrContainer;
87 typedef std::set<ResKind> Kinds;
88 typedef std::map<sat::SolvAttr, StrContainer> AttrRawStrMap;
89 typedef std::map<sat::SolvAttr, std::string> AttrCompiledStrMap;
90 typedef std::map<sat::SolvAttr, str::regex> AttrRegexMap;
92 typedef detail::PoolQueryIterator const_iterator;
93 typedef unsigned int size_type;
96 typedef function<bool( const sat::Solvable & )> ProcessResolvable;
101 /** Query result accessers. */
104 * Compile the query and return an iterator to the result.
106 * \return An iterator (\ref detail::PoolQueryIterator) returning
107 * sat::Solvable objects pointing at the beginning of the query result.
108 * \throws sat::MatchInvalidRegexException if the query was about to use a regex which
111 * \note Note that PoolQuery is derived from \ref sat::SolvIterMixin which
112 * makes PoolItem and Selectable iterators automatically available.
113 * \see \ref sat::SolvIterMixin
115 const_iterator begin() const;
117 /** An iterator pointing to the end of the query result. */
118 const_iterator end() const;
120 /** Whether the result is empty. */
123 /** Number of solvables in the query result. */
124 size_type size() const;
128 * Executes the query with the current settings.
129 * Results are yielded via the \a fnc callback.
131 void execute(ProcessResolvable fnc);
134 * Filter by selectable kind.
136 * By default, all kinds will be returned. If addKind() is used,
137 * only the specified kinds will be returned (multiple kinds will be ORed).
139 * Pass ResKind constants to this method, (e.g. ResKind::package).
141 void addKind(const ResKind & kind);
146 * By default, all repos will be returned. If addRepo() is used,
147 * only the specified repo will be returned (multiple repos will be ORed).
149 void addRepo(const std::string &repoalias);
151 /** Installed status filter setters. */
155 * Filter by status (installed uninstalled)
158 ALL = 0, // both install filter and uninstall filter bits are 0
163 /** Return only @System repo packages */
164 void setInstalledOnly();
165 /** Return only packages from repos other than @System. */
166 void setUninstalledOnly();
167 /** Set status filter directly \see StatusFilter */
168 void setStatusFilterFlags( StatusFilter flags );
173 * Add a global query string. The string added via this method is applied
174 * to all query attributes as if addAttribute(..., \value) was called
177 * This method can be used multiple times in which case the query strings
178 * will be combined (together with strings added via addAttribute()) into
179 * a regex. Searched attribute value will match this regex if <b>any</b>
180 * of these strings will match the value. This can be changed by
181 * (not yet implemented) \ref setRequireAll() method.
183 void addString(const std::string & value);
186 * Filter by the \a value of the specified \a attr attribute. This can
187 * be any of the available solvable attributes.
189 * This method can be used multiple times with the same \a attr in which
190 * case the query strings will be combined (together with strings added
191 * via addString()) into a regex. Searched attribute value will match
192 * this regex if <b>any</b> of these strings will match the value.
193 * This can be changed by (not yet implemented) \ref setRequireAll()
196 * \note Though it is possible to use dependency attributes like
197 * \ref Solv::Attr::provides here, note that the query string is
198 * matched against a dependencies \c "name" part only. Any
199 * <tt>"op edition"</tt> part of a \ref Capability is \b not
200 * considered at all. \see \ref addDependency on how to query for
201 * capabilities including edition ranges.
203 * \note Solvables of a kind not supporting the specified attribute will
204 * <b>not</b> be returned.
205 * \todo check the above
207 * \param attr Attribute identfier. Use sat::Solvattr::* constants
208 * \param value What to search for.
212 void addAttribute( const sat::SolvAttr & attr, const std::string & value = "" );
214 /** \name Filter by dependencies matching a broken down capability <tt>name [op edition]</tt>.
216 * The capabilities \c name part may be defined as query string
217 * like with \ref addAttribute. Globing and regex are supported.
218 * Global query strings defined by \ref addString are considered.
220 * So without any <tt>op edition</tt> addDependency behaves the
221 * same as \ref addAttribute. If an edition range is given, matches
222 * are restricted accordingly. Thete are various overloads, so pick
223 * the one you like best.
228 * setCaseSensitive( false );
229 * addDependency( sat::SolvAttr::provides, "kde*", Rel::EQ, Edition("2.0") );
230 * addDependency( sat::SolvAttr::provides, "kde*", Edition("2.0") ); // same as above
234 * setCaseSensitive( false );
235 * addString( "kde*" );
236 * addDependency( sat::SolvAttr::provides, Rel::EQ, Edition("2.0") );// same as above
237 * addDependency( sat::SolvAttr::provides, Edition("2.0") ); // same as above
241 * \note Thre's also a version of \ref addDependency provided, that takes a
242 * complete \ref Capability as argument. This always requires an exact match
243 * of the name part (as the resolver would do it).
245 * This is the list of valid dependency attributes:
248 * SolvAttr::obsoletes
249 * SolvAttr::conflicts
251 * SolvAttr::recommends
253 * SolvAttr::supplements
257 * \note <b>What happens if a non dependency attribute is passed?<\b>
258 * If an edition range is given, it is matched against the matching
259 * solvables edition instead. Without edition range it behaves the
260 * same as \ref addAttribute.
263 * // Find all packages providing "kernel > 2.0"
264 * addDependency( sat::SolvAttr::provides, "kernel", Rel::GT, Edition("2.0") );
266 * // // Find all packages named "kernel" and with edition "> 2.0"
267 * addDependency( sat::SolvAttr::name, "kernel", Rel::GT, Edition("2.0") );
271 /** Query <tt>"name|global op edition"</tt>. */
272 void addDependency( const sat::SolvAttr & attr, const std::string & name, const Rel & op, const Edition & edition );
274 /** \overload Query <tt>"name|global == edition"</tt>. */
275 void addDependency( const sat::SolvAttr & attr, const std::string & name, const Edition & edition )
276 { addDependency( attr, name, Rel::EQ, edition ); }
278 /** \overload Query <tt>"name|global"</tt>. */
279 void addDependency( const sat::SolvAttr & attr, const std::string & name )
280 { addDependency( attr, name, Rel::ANY, Edition() ); }
282 /** \overload Query <tt>"global op edition"</tt>.*/
283 void addDependency( const sat::SolvAttr & attr, const Rel & op, const Edition & edition )
284 { addDependency( attr, std::string(), op, edition ); }
286 /** \overload Query <tt>"global == edition"</tt>. */
287 void addDependency( const sat::SolvAttr & attr, const Edition & edition )
288 { addDependency( attr, std::string(), Rel::EQ, edition ); }
290 /** \overload Query <tt>"global"</tt>. */
291 void addDependency( const sat::SolvAttr & attr )
292 { addDependency( attr, std::string(), Rel::ANY, Edition() ); }
294 /** \overload Query taking a \ref Capability (always exact name match).
295 * \note If a non dependency attribute is passed, the \ref Capability
296 * will always be matched against the Solvables \c name and \c edition.
298 void addDependency( const sat::SolvAttr & attr, Capability cap_r );
302 * Set version condition. This will filter out solvables not matching
303 * <tt>solvableEdition \a op \a edition</tt>.
305 * \param edition Edition to look for.
306 * \param op Found-wanted relation operator.
308 void setEdition(const Edition & edition, const Rel & op = Rel::EQ);
310 /** \name Text Matching Options
311 * \note The implementation treats an empty search string as
312 * <it>"match always"</it>. So if you want to actually match
313 * an empty value, try <tt>( "^$", setMatchRegex )</tt>.
317 * Turn case sentitivity on or off (unsets or sets \ref SEARCH_NOCASE flag).
318 * PoolQuery defaults to case insensitive search unless this method
321 * \param value Whether to turn the case sensitivity on (default) or off.
323 void setCaseSensitive( bool value = true );
326 * If set (default), look at the full path when searching in filelists.
327 * Otherwise just match the the basenames.
328 * \see \ref Match::FILES
330 void setFilesMatchFullPath( bool value = true );
332 void setFilesMatchBasename( bool value = true )
333 { setFilesMatchFullPath( !value ); }
335 /** Set to match exact string instead of substring.*/
336 void setMatchExact();
337 /** Set to substring (the default). */
338 void setMatchSubstring();
339 /** Set to match globs. */
341 /** Set to use the query strings as regexes */
342 void setMatchRegex();
343 /** Set to match words (uses regex) */
345 //void setLocale(const Locale & locale);
349 * Require that all of the values set by addString or addAttribute
350 * match the values of respective attributes.
352 * \todo doesn't work yet, don't use this function
354 void setRequireAll( bool require_all = true );
360 /** Search strings added via addString() */
361 const StrContainer & strings() const;
363 * Map (map<SolvAttr, StrContainer>) of attribute values added via
364 * addAttribute(), addDep in string form */
365 const AttrRawStrMap & attributes() const;
367 const StrContainer & attribute(const sat::SolvAttr & attr) const;
369 const Kinds & kinds() const;
371 const StrContainer & repos() const;
373 const Edition edition() const;
374 const Rel editionRel() const;
377 * returns true if search is case sensitive
379 bool caseSensitive() const;
381 /** Whether searching in filelists looks at the full path or just at the basenames. */
382 bool filesMatchFullPath() const;
384 bool filesMatchBasename() const
385 { return !filesMatchFullPath(); }
387 bool matchExact() const;
388 bool matchSubstring() const;
389 bool matchGlob() const;
390 bool matchRegex() const;
391 bool matchWord() const;
393 /** Returns string matching mode as enum.
394 * \see \ref Match::Mode
396 Match::Mode matchMode() const
397 { return flags().mode(); }
400 * Whether all values added via addString() or addAttribute() are required
401 * to match the values of the respective attributes.
403 bool requireAll() const;
405 StatusFilter statusFilterFlags() const;
409 * Reads from stream query. Attributes is sepated by delim. Query is
410 * separated by two delim.
412 * \param str input stream which contains query
413 * \param delim delimeter for attributes
414 * \return true if non-empty query is recovered
416 * \see readPoolQueriesFromFile
418 bool recover( std::istream &str, char delim = '\n' );
421 * Writes a machine-readable string representation of the query to stream.
422 * Use \a delim as attribute delimiter.
424 * \param str output stream to write to
425 * \param delim delimiter for attributes
427 * \see writePoolQueriesToFile
429 void serialize( std::ostream &str, char delim = '\n' ) const;
431 /** Return a human-readable description of the query */
432 std::string asString() const;
434 bool operator==(const PoolQuery& b) const;
435 bool operator!=(const PoolQuery& b) const { return !(*this == b ); }
440 * Free function to get the satsolver repo search
448 * Free function to set the satsolver repo search
453 void setFlags( const Match & flags );
458 /** Pointer to implementation */
459 RW_pointer<Impl> _pimpl;
461 ///////////////////////////////////////////////////////////////////
463 /** \relates PoolQuery Stream output. */
464 std::ostream & operator<<( std::ostream & str, const PoolQuery & obj );
467 ///////////////////////////////////////////////////////////////////
469 { /////////////////////////////////////////////////////////////////
471 class PoolQueryMatcher;
473 ///////////////////////////////////////////////////////////////////
475 // CLASS NAME : PoolQuery::PoolQueryIterator
477 /** \ref PoolQuery iterator as returned by \ref PoolQuery::begin.
479 class PoolQueryIterator : public boost::iterator_adaptor<
480 PoolQueryIterator // Derived
481 , sat::LookupAttr::iterator // Base
482 , const sat::Solvable // Value
483 , boost::forward_traversal_tag // CategoryOrTraversal
484 , const sat::Solvable // Reference
488 /** Default ctor is also \c end.*/
492 /** \Ref PoolQuery ctor. */
493 PoolQueryIterator( const shared_ptr<PoolQueryMatcher> & matcher_r )
494 : _matcher( matcher_r )
498 friend class boost::iterator_core_access;
500 sat::Solvable dereference() const
501 { return base_reference().inSolvable(); }
506 shared_ptr<PoolQueryMatcher> _matcher;
508 ///////////////////////////////////////////////////////////////////
510 /** \relates PoolQueryIterator Stream output. */
511 inline std::ostream & operator<<( std::ostream & str, const PoolQueryIterator & obj )
512 { return str << obj.base(); }
514 ///////////////////////////////////////////////////////////////////
516 ///////////////////////////////////////////////////////////////////
518 inline detail::PoolQueryIterator PoolQuery::end() const
519 { return detail::PoolQueryIterator(); }
521 /////////////////////////////////////////////////////////////////
523 ///////////////////////////////////////////////////////////////////
525 #endif // ZYPP_POOLQUERY_H