zypp/ResFilters.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /** \file       zypp/ResFilters.h
  10  *
  11 */
  12 #ifndef ZYPP_RESFILTERS_H
  13 #define ZYPP_RESFILTERS_H
  14
  15 #include <boost/function.hpp>
  16
  17 #include "zypp/base/Functional.h"
  18 #include "zypp/Resolvable.h"
  19
  20 #include "zypp/PoolItem.h"
  21 #include "zypp/Repository.h"
  22
  23 ///////////////////////////////////////////////////////////////////
  24 namespace zypp
  25 { /////////////////////////////////////////////////////////////////
  26   ///////////////////////////////////////////////////////////////////
  27   namespace resfilter
  28   { /////////////////////////////////////////////////////////////////
  29
  30     /** \defgroup RESFILTERS Filter functors operating on ResObjects.
  31      * \ingroup g_Functor
  32      *
  33      * A simple filter is a function or functor matching the signature:
  34      * \code
  35      *   bool simplefilter( ResObject::Ptr );
  36      * \endcode
  37      *
  38      * \note It's not neccessary that your function or functor actually
  39      * returns \c bool. Anything which is convertible into a \c bool
  40      * will do;
  41      *
  42      * Besides basic filter functors which actually evaluate the
  43      * \c ResObject (e.g. \ref ByKind, \ref ByName) you may
  44      * use \ref LOGICALFILTERS to build more complex filters.
  45      *
  46      * \code
  47      * // some 'action' functor, printing and counting
  48      * // ResObjects.
  49      * struct PrintAndCount
  50      * {
  51      *   PrintAndCount( unsigned & counter_r )
  52      *   : _counter( counter_r )
  53      *   {}
  54      *
  55      *   bool operator()( ResObject::Ptr p ) const
  56      *   {
  57      *     DBG << *p << endl;
  58      *     ++_counter;
  59      *     return true;
  60      *   }
  61      *
  62      *   unsigned _counter;
  63      * };
  64      *
  65      * ResStore store;
  66      * unsigned counter = 0;
  67      *
  68      * // print and count all resolvables
  69      * store.forEach( PrintAndCount(counter) );
  70      *
  71      * // print and count all resolvables named "kernel"
  72      * counter = 0;
  73      * store.forEach( ByName("kernel"), PrintAndCount(counter) );
  74      *
  75      * // print and count all Packages named "kernel"
  76      * counter = 0;
  77      * store.forEach( chain( ByKind(ResTraits<Package>::kind),
  78      *                       ByName("kernel") ),
  79      *                PrintAndCount(counter) );
  80      *
  81      * // print and count all Packages not named "kernel"
  82      * counter = 0;
  83      * store.forEach( chain( ByKind(ResTraits<Package>::kind),
  84      *                       not_c(ByName("kernel")) ),
  85      *                PrintAndCount(counter) );
  86      *
  87      * // same as above ;)
  88      * counter = 0;
  89      * store.forEach( chain( ByKind(ResTraits<Package>::kind),
  90      *                       chain( not_c(ByName("kernel")),
  91      *                              PrintAndCount(counter) ) ),
  92      *                true_c() );
  93      * \endcode
  94      *
  95      * As you can see in the last example there is no difference in using
  96      * a filter or an action functor, as both have the same signature.
  97      * A difference of course is the way forEach interprets the returned
  98      * value.
  99      *
 100      * Consequently you can netgate and chain actions as well. Thus
 101      * <tt>PrintAndCount(counter)</tt> could be
 102      * <tt>chain(Print(),Count(counter))</tt>, if these functors are
 103      * provided.
 104      *
 105      * \note These functors are not limited to be used with ResStore::forEach.
 106      * You can use them with std::algorithms as well.
 107      *
 108      * \note In case you already have functions or methods which do what you
 109      * want, but thet don't perfectly match the required signature: Make yourself
 110      * familiar with <tt>std::ptr_fun, mem_fun, bind1st, bind2nd and compose</tt>.
 111      * They are sometimes quite helpfull.
 112      *
 113      * \c PrintAndCount is an example how a functor can return data collected
 114      * during the query. You ca easily write a collector, that takes a
 115      * <tt>std:list\<ResObject::Ptr\>\&</tt> and fills it with the matches
 116      * found.
 117      *
 118      * But as a rule of thumb, a functor should be lightweight. If you
 119      * want to get data out, pass references to variables in (and assert
 120      * these variables live as long as the query lasts). Or use \ref FunctorRef.
 121      *
 122      * Internally all functors are passed by value. Thus it would not help
 123      * you to create an instance of some collecting functor, and pass it
 124      * to the query. The query will then fill a copy of your functor, you
 125      * won't get the data back. (Well, you probabely could, by using
 126      * boosr::ref).
 127      *
 128      * Why functors and not plain functions?
 129      *
 130      * You can use plain functions if they don't have to deliver data back to
 131      * the application.
 132      * The \c C-style approach is having functions that take a <tt>void * data</tt>
 133      * as last argument. This \c data pointer is then passed arround and casted
 134      * up and down.
 135      *
 136      * If you look at a functor, you'll see that it contains both, the function
 137      * to call (it's <tt>operator()</tt> ) and the data you'd otherwise pass as
 138      * <tt>void * data</tt>. That's nice and safe.
 139     */
 140     //@{
 141     ///////////////////////////////////////////////////////////////////
 142     //
 143     // Some ResObject attributes
 144     //
 145     ///////////////////////////////////////////////////////////////////
 146
 147     /** */
 148     typedef std::unary_function<ResObject::constPtr, bool> ResObjectFilterFunctor;
 149     typedef boost::function<bool ( ResObject::constPtr )> ResFilter;
 150
 151     /** Select ResObject by kind. */
 152     struct ByKind : public ResObjectFilterFunctor
 153     {
 154       ByKind( const ResObject::Kind & kind_r )
 155       : _kind( kind_r )
 156       {}
 157
 158       bool operator()( ResObject::constPtr p ) const
 159       {
 160         return p->kind() == _kind;
 161       }
 162
 163       ResObject::Kind _kind;
 164     };
 165
 166     /** */
 167     template<class _Res>
 168       inline ByKind byKind()
 169       { return ByKind( ResTraits<_Res>::kind ); }
 170
 171     /** Select ResObject by name. */
 172     struct ByName : public ResObjectFilterFunctor
 173     {
 174       ByName( const std::string & name_r )
 175       : _name( name_r )
 176       {}
 177
 178       bool operator()( ResObject::constPtr p ) const
 179       {
 180         return p->name() == _name;
 181       }
 182
 183       std::string _name;
 184     };
 185
 186     /** Select ResObject by repository or repository alias. */
 187     struct ByRepository : public ResObjectFilterFunctor
 188     {
 189       ByRepository( Repository repository_r )
 190       : _alias( repository_r.info().alias() )
 191       {}
 192
 193       ByRepository( const std::string & alias_r )
 194       : _alias( alias_r )
 195       {}
 196
 197       bool operator()( ResObject::constPtr p ) const
 198       {
 199         return p->repoInfo().alias() == _alias;
 200       }
 201
 202       std::string _alias;
 203     };
 204
 205     /** Select ResObject by Edition using \a _Compare functor.
 206      *
 207      * Selects ResObject if <tt>_Compare( ResObject->edition(), _edition )</tt>
 208      * is \c true.
 209      * \code
 210      * // use the convenience funktions to create ByEdition:
 211      *
 212      * byEdition( someedition ); // selects ResObjects with edition == someedition
 213      *
 214      * byEdition( someedition, CompareByGT<Edition>() ) //  edition >  someedition
 215      * \endcode
 216     */
 217     template<class _Compare = CompareByEQ<Edition> >
 218       struct ByEdition : public ResObjectFilterFunctor
 219       {
 220         ByEdition( const Edition & edition_r,
 221                    _Compare cmp_r )
 222         : _edition( edition_r )
 223         , _cmp( cmp_r )
 224         {}
 225
 226         bool operator()( ResObject::constPtr p ) const
 227         {
 228           return _cmp( p->edition(), _edition );
 229         }
 230
 231         Edition  _edition;
 232         _Compare _cmp;
 233       };
 234
 235     /** */
 236     template<class _Compare>
 237       ByEdition<_Compare> byEdition( const Edition & edition_r, _Compare cmp_r )
 238       { return ByEdition<_Compare>( edition_r, cmp_r ); }
 239
 240     /** */
 241     template<class _Compare>
 242       ByEdition<_Compare> byEdition( const Edition & edition_r )
 243       { return byEdition( edition_r, _Compare() ); }
 244
 245
 246     /** Select ResObject by Arch using \a _Compare functor.
 247      *
 248      * Selects ResObject if <tt>_Compare( ResObject->arch(), _arch )</tt>
 249      * is \c true.
 250      * \code
 251      * // use the convenience funktions to create ByArch:
 252      *
 253      * byArch( somearch ); // selects ResObjects with arch == somearch
 254      *
 255      * byArch( somearch, CompareByGT<Arch>() ) //  arch >  somearch
 256      * \endcode
 257     */
 258     template<class _Compare = CompareByEQ<Arch> >
 259       struct ByArch : public ResObjectFilterFunctor
 260       {
 261         ByArch( const Arch & arch_r,
 262                    _Compare cmp_r )
 263         : _arch( arch_r )
 264         , _cmp( cmp_r )
 265         {}
 266
 267         bool operator()( ResObject::constPtr p ) const
 268         {
 269           return _cmp( p->arch(), _arch );
 270         }
 271
 272         Arch  _arch;
 273         _Compare _cmp;
 274       };
 275
 276     /** */
 277     template<class _Compare>
 278       ByArch<_Compare> byArch( const Arch & arch_r, _Compare cmp_r )
 279       { return ByArch<_Compare>( arch_r, cmp_r ); }
 280
 281     /** */
 282     template<class _Compare>
 283       ByArch<_Compare> byArch( const Arch & arch_r )
 284       { return byArch( arch_r, _Compare() ); }
 285
 286
 287     ///////////////////////////////////////////////////////////////////
 288
 289     ///////////////////////////////////////////////////////////////////
 290     //
 291     // Some PoolItem attributes
 292     //
 293     ///////////////////////////////////////////////////////////////////
 294
 295     /** */
 296     typedef std::unary_function<PoolItem, bool> PoolItemFilterFunctor;
 297
 298     /** Select PoolItem by installed. */
 299     struct ByInstalled : public PoolItemFilterFunctor
 300     {
 301       bool operator()( const PoolItem & p ) const
 302       {
 303         return p.status().isInstalled();
 304       }
 305
 306     };
 307
 308     /** Select PoolItem by uninstalled. */
 309     struct ByUninstalled : public PoolItemFilterFunctor
 310     {
 311       bool operator()( const PoolItem & p ) const
 312       {
 313         return p.status().isUninstalled();
 314       }
 315     };
 316
 317     /** Select PoolItem by transact. */
 318     struct ByTransact : public PoolItemFilterFunctor
 319     {
 320       bool operator()( const PoolItem & p ) const
 321       {
 322         return p.status().transacts();
 323       }
 324     };
 325
 326     /** Select PoolItem by lock. */
 327     struct ByLock : public PoolItemFilterFunctor
 328     {
 329       bool operator()( const PoolItem & p ) const
 330       {
 331         return p.status().isLocked();
 332       }
 333     };
 334
 335     /** Select PoolItem by keep. */
 336     struct ByKeep : public PoolItemFilterFunctor
 337     {
 338       bool operator()( const PoolItem & p ) const
 339       {
 340         return p.status().isKept();
 341       }
 342     };
 343
 344     //@}
 345     /////////////////////////////////////////////////////////////////
 346   } // namespace resfilter
 347   ///////////////////////////////////////////////////////////////////
 348   /////////////////////////////////////////////////////////////////
 349 } // namespace zypp
 350 ///////////////////////////////////////////////////////////////////
 351 #endif // ZYPP_RESFILTERS_H