apt-pkg/cacheiterators.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 /* ######################################################################
   4
   5    Cache Iterators - Iterators for navigating the cache structure
   6
   7    The iterators all provides ++,==,!=,->,* and end for their type.
   8    The end function can be used to tell if the list has been fully
   9    traversed.
  10
  11    Unlike STL iterators these contain helper functions to access the data
  12    that is being iterated over. This is because the data structures can't
  13    be formed in a manner that is intuitive to use and also mmapable.
  14
  15    For each variable in the target structure that would need a translation
  16    to be accessed correctly a translating function of the same name is
  17    present in the iterator. If applicable the translating function will
  18    return an iterator.
  19
  20    The DepIterator can iterate over two lists, a list of 'version depends'
  21    or a list of 'package reverse depends'. The type is determined by the
  22    structure passed to the constructor, which should be the structure
  23    that has the depends pointer as a member. The provide iterator has the
  24    same system.
  25
  26    This header is not user includable, please use apt-pkg/pkgcache.h
  27
  28    ##################################################################### */
  29                                                                         /*}}}*/
  30 #ifndef PKGLIB_CACHEITERATORS_H
  31 #define PKGLIB_CACHEITERATORS_H
  32 #include<apt-pkg/pkgcache.h>
  33 #include<apt-pkg/macros.h>
  34
  35 #include<iterator>
  36 #include <iosfwd>
  37 #include <string>
  38
  39 #include<string.h>
  40
  41 // abstract Iterator template                                           /*{{{*/
  42 /* This template provides the very basic iterator methods we
  43    need to have for doing some walk-over-the-cache magic */
  44 template<typename Str, typename Itr> class pkgCache::Iterator :
  45                         public std::iterator<std::forward_iterator_tag, Str> {
  46         protected:
  47         Str *S;
  48         pkgCache *Owner;
  49
  50         /** \brief Returns the Pointer for this struct in the owner
  51          *  The implementation of this method should be pretty short
  52          *  as it will only return the Pointer into the mmap stored
  53          *  in the owner but the name of this pointer is different for
  54          *  each structure and we want to abstract here at least for the
  55          *  basic methods from the actual structure.
  56          *  \return Pointer to the first structure of this type
  57          */
  58         virtual Str* OwnerPointer() const = 0;
  59
  60         public:
  61         // Iteration
  62         virtual void operator ++(int) = 0;
  63         virtual void operator ++() = 0; // Should be {operator ++(0);}
  64         inline bool end() const {return Owner == 0 || S == OwnerPointer();}
  65
  66         // Comparison
  67         inline bool operator ==(const Itr &B) const {return S == B.S;}
  68         inline bool operator !=(const Itr &B) const {return S != B.S;}
  69
  70         // Accessors
  71         inline Str *operator ->() {return S;}
  72         inline Str const *operator ->() const {return S;}
  73         inline operator Str *() {return S == OwnerPointer() ? 0 : S;}
  74         inline operator Str const *() const {return S == OwnerPointer() ? 0 : S;}
  75         inline Str &operator *() {return *S;}
  76         inline Str const &operator *() const {return *S;}
  77         inline pkgCache *Cache() const {return Owner;}
  78
  79         // Mixed stuff
  80         inline void operator =(const Itr &B) {S = B.S; Owner = B.Owner;}
  81         inline bool IsGood() const { return S && Owner && ! end();}
  82         inline unsigned long Index() const {return S - OwnerPointer();}
  83
  84         void ReMap(void const * const oldMap, void const * const newMap) {
  85                 if (Owner == 0 || S == 0)
  86                         return;
  87                 S += (Str const * const)(newMap) - (Str const * const)(oldMap);
  88         }
  89
  90         // Constructors - look out for the variable assigning
  91         inline Iterator() : S(0), Owner(0) {}
  92         inline Iterator(pkgCache &Owner,Str *T = 0) : S(T), Owner(&Owner) {}
  93 };
  94                                                                         /*}}}*/
  95 // Group Iterator                                                       /*{{{*/
  96 /* Packages with the same name are collected in a Group so someone only
  97    interest in package names can iterate easily over the names, so the
  98    different architectures can be treated as of the "same" package
  99    (apt internally treat them as totally different packages) */
 100 class pkgCache::GrpIterator: public Iterator<Group, GrpIterator> {
 101         long HashIndex;
 102
 103         protected:
 104         inline Group* OwnerPointer() const {
 105                 return (Owner != 0) ? Owner->GrpP : 0;
 106         }
 107
 108         public:
 109         // This constructor is the 'begin' constructor, never use it.
 110         inline GrpIterator(pkgCache &Owner) : Iterator<Group, GrpIterator>(Owner), HashIndex(-1) {
 111                 S = OwnerPointer();
 112                 operator ++(0);
 113         }
 114
 115         virtual void operator ++(int);
 116         virtual void operator ++() {operator ++(0);}
 117
 118         inline const char *Name() const {return S->Name == 0?0:Owner->StrP + S->Name;}
 119         inline PkgIterator PackageList() const;
 120         PkgIterator FindPkg(std::string Arch = "any") const;
 121         /** \brief find the package with the "best" architecture
 122
 123             The best architecture is either the "native" or the first
 124             in the list of Architectures which is not an end-Pointer
 125
 126             \param PreferNonVirtual tries to respond with a non-virtual package
 127                    and only if this fails returns the best virtual package */
 128         PkgIterator FindPreferredPkg(bool const &PreferNonVirtual = true) const;
 129         PkgIterator NextPkg(PkgIterator const &Pkg) const;
 130
 131         // Constructors
 132         inline GrpIterator(pkgCache &Owner, Group *Trg) : Iterator<Group, GrpIterator>(Owner, Trg), HashIndex(0) {
 133                 if (S == 0)
 134                         S = OwnerPointer();
 135         }
 136         inline GrpIterator() : Iterator<Group, GrpIterator>(), HashIndex(0) {}
 137
 138 };
 139                                                                         /*}}}*/
 140 // Package Iterator                                                     /*{{{*/
 141 class pkgCache::PkgIterator: public Iterator<Package, PkgIterator> {
 142         long HashIndex;
 143
 144         protected:
 145         inline Package* OwnerPointer() const {
 146                 return (Owner != 0) ? Owner->PkgP : 0;
 147         }
 148
 149         public:
 150         // This constructor is the 'begin' constructor, never use it.
 151         inline PkgIterator(pkgCache &Owner) : Iterator<Package, PkgIterator>(Owner), HashIndex(-1) {
 152                 S = OwnerPointer();
 153                 operator ++(0);
 154         }
 155
 156         virtual void operator ++(int);
 157         virtual void operator ++() {operator ++(0);}
 158
 159         enum OkState {NeedsNothing,NeedsUnpack,NeedsConfigure};
 160
 161         // Accessors
 162         inline const char *Name() const {return S->Name == 0?0:Owner->StrP + S->Name;}
 163         // Versions have sections - and packages can have different versions with different sections
 164         // so this interface is broken by design. It used to return the section of the "first parsed
 165         // package stanza", but as this can potentially be anything it now returns the section of the
 166         // newest version instead (if any). aka: Run as fast as you can to Version.Section().
 167         APT_DEPRECATED const char *Section() const;
 168         inline bool Purge() const {return S->CurrentState == pkgCache::State::Purge ||
 169                 (S->CurrentVer == 0 && S->CurrentState == pkgCache::State::NotInstalled);}
 170         inline const char *Arch() const {return S->Arch == 0?0:Owner->StrP + S->Arch;}
 171         inline APT_PURE GrpIterator Group() const { return GrpIterator(*Owner, Owner->GrpP + S->Group);}
 172
 173         inline VerIterator VersionList() const APT_PURE;
 174         inline VerIterator CurrentVer() const APT_PURE;
 175         inline DepIterator RevDependsList() const APT_PURE;
 176         inline PrvIterator ProvidesList() const APT_PURE;
 177         OkState State() const APT_PURE;
 178         const char *CandVersion() const APT_PURE;
 179         const char *CurVersion() const APT_PURE;
 180
 181         //Nice printable representation
 182         friend std::ostream& operator <<(std::ostream& out, PkgIterator i);
 183         std::string FullName(bool const &Pretty = false) const;
 184
 185         // Constructors
 186         inline PkgIterator(pkgCache &Owner,Package *Trg) : Iterator<Package, PkgIterator>(Owner, Trg), HashIndex(0) {
 187                 if (S == 0)
 188                         S = OwnerPointer();
 189         }
 190         inline PkgIterator() : Iterator<Package, PkgIterator>(), HashIndex(0) {}
 191 };
 192                                                                         /*}}}*/
 193 // Version Iterator                                                     /*{{{*/
 194 class pkgCache::VerIterator : public Iterator<Version, VerIterator> {
 195         protected:
 196         inline Version* OwnerPointer() const {
 197                 return (Owner != 0) ? Owner->VerP : 0;
 198         }
 199
 200         public:
 201         // Iteration
 202         void operator ++(int) {if (S != Owner->VerP) S = Owner->VerP + S->NextVer;}
 203         inline void operator ++() {operator ++(0);}
 204
 205         // Comparison
 206         int CompareVer(const VerIterator &B) const;
 207         /** \brief compares two version and returns if they are similar
 208
 209             This method should be used to identify if two pseudo versions are
 210             referring to the same "real" version */
 211         inline bool SimilarVer(const VerIterator &B) const {
 212                 return (B.end() == false && S->Hash == B->Hash && strcmp(VerStr(), B.VerStr()) == 0);
 213         }
 214
 215         // Accessors
 216         inline const char *VerStr() const {return S->VerStr == 0?0:Owner->StrP + S->VerStr;}
 217         inline const char *Section() const {return S->Section == 0?0:Owner->StrP + S->Section;}
 218         inline const char *Arch() const {
 219                 if ((S->MultiArch & pkgCache::Version::All) == pkgCache::Version::All)
 220                         return "all";
 221                 return S->ParentPkg == 0?0:Owner->StrP + ParentPkg()->Arch;
 222         }
 223         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 224
 225         inline DescIterator DescriptionList() const;
 226         DescIterator TranslatedDescription() const;
 227         inline DepIterator DependsList() const;
 228         inline PrvIterator ProvidesList() const;
 229         inline VerFileIterator FileList() const;
 230         bool Downloadable() const;
 231         inline const char *PriorityType() const {return Owner->Priority(S->Priority);}
 232         const char *MultiArchType() const APT_PURE;
 233         std::string RelStr() const;
 234
 235         bool Automatic() const;
 236         VerFileIterator NewestFile() const;
 237
 238         inline VerIterator(pkgCache &Owner,Version *Trg = 0) : Iterator<Version, VerIterator>(Owner, Trg) {
 239                 if (S == 0)
 240                         S = OwnerPointer();
 241         }
 242         inline VerIterator() : Iterator<Version, VerIterator>() {}
 243 };
 244                                                                         /*}}}*/
 245 // Description Iterator                                                 /*{{{*/
 246 class pkgCache::DescIterator : public Iterator<Description, DescIterator> {
 247         protected:
 248         inline Description* OwnerPointer() const {
 249                 return (Owner != 0) ? Owner->DescP : 0;
 250         }
 251
 252         public:
 253         // Iteration
 254         void operator ++(int) {if (S != Owner->DescP) S = Owner->DescP + S->NextDesc;}
 255         inline void operator ++() {operator ++(0);}
 256
 257         // Comparison
 258         int CompareDesc(const DescIterator &B) const;
 259
 260         // Accessors
 261         inline const char *LanguageCode() const {return Owner->StrP + S->language_code;}
 262         inline const char *md5() const {return Owner->StrP + S->md5sum;}
 263         inline DescFileIterator FileList() const;
 264
 265         inline DescIterator() : Iterator<Description, DescIterator>() {}
 266         inline DescIterator(pkgCache &Owner,Description *Trg = 0) : Iterator<Description, DescIterator>(Owner, Trg) {
 267                 if (S == 0)
 268                         S = Owner.DescP;
 269         }
 270 };
 271                                                                         /*}}}*/
 272 // Dependency iterator                                                  /*{{{*/
 273 class pkgCache::DepIterator : public Iterator<Dependency, DepIterator> {
 274         enum {DepVer, DepRev} Type;
 275
 276         protected:
 277         inline Dependency* OwnerPointer() const {
 278                 return (Owner != 0) ? Owner->DepP : 0;
 279         }
 280
 281         public:
 282         // Iteration
 283         void operator ++(int) {if (S != Owner->DepP) S = Owner->DepP +
 284                 (Type == DepVer ? S->NextDepends : S->NextRevDepends);}
 285         inline void operator ++() {operator ++(0);}
 286
 287         // Accessors
 288         inline const char *TargetVer() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 289         inline PkgIterator TargetPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->Package);}
 290         inline PkgIterator SmartTargetPkg() const {PkgIterator R(*Owner,0);SmartTargetPkg(R);return R;}
 291         inline VerIterator ParentVer() const {return VerIterator(*Owner,Owner->VerP + S->ParentVer);}
 292         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->ParentVer].ParentPkg);}
 293         inline bool Reverse() const {return Type == DepRev;}
 294         bool IsCritical() const APT_PURE;
 295         bool IsNegative() const APT_PURE;
 296         bool IsIgnorable(PrvIterator const &Prv) const APT_PURE;
 297         bool IsIgnorable(PkgIterator const &Pkg) const APT_PURE;
 298         bool IsMultiArchImplicit() const APT_PURE;
 299         bool IsSatisfied(VerIterator const &Ver) const APT_PURE;
 300         bool IsSatisfied(PrvIterator const &Prv) const APT_PURE;
 301         void GlobOr(DepIterator &Start,DepIterator &End);
 302         Version **AllTargets() const;
 303         bool SmartTargetPkg(PkgIterator &Result) const;
 304         inline const char *CompType() const {return Owner->CompType(S->CompareOp);}
 305         inline const char *DepType() const {return Owner->DepType(S->Type);}
 306
 307         //Nice printable representation
 308         friend std::ostream& operator <<(std::ostream& out, DepIterator D);
 309
 310         inline DepIterator(pkgCache &Owner, Dependency *Trg, Version* = 0) :
 311                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepVer) {
 312                 if (S == 0)
 313                         S = Owner.DepP;
 314         }
 315         inline DepIterator(pkgCache &Owner, Dependency *Trg, Package*) :
 316                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepRev) {
 317                 if (S == 0)
 318                         S = Owner.DepP;
 319         }
 320         inline DepIterator() : Iterator<Dependency, DepIterator>(), Type(DepVer) {}
 321 };
 322                                                                         /*}}}*/
 323 // Provides iterator                                                    /*{{{*/
 324 class pkgCache::PrvIterator : public Iterator<Provides, PrvIterator> {
 325         enum {PrvVer, PrvPkg} Type;
 326
 327         protected:
 328         inline Provides* OwnerPointer() const {
 329                 return (Owner != 0) ? Owner->ProvideP : 0;
 330         }
 331
 332         public:
 333         // Iteration
 334         void operator ++(int) {if (S != Owner->ProvideP) S = Owner->ProvideP +
 335                 (Type == PrvVer?S->NextPkgProv:S->NextProvides);}
 336         inline void operator ++() {operator ++(0);}
 337
 338         // Accessors
 339         inline const char *Name() const {return Owner->StrP + Owner->PkgP[S->ParentPkg].Name;}
 340         inline const char *ProvideVersion() const {return S->ProvideVersion == 0?0:Owner->StrP + S->ProvideVersion;}
 341         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 342         inline VerIterator OwnerVer() const {return VerIterator(*Owner,Owner->VerP + S->Version);}
 343         inline PkgIterator OwnerPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->Version].ParentPkg);}
 344
 345         bool IsMultiArchImplicit() const APT_PURE;
 346
 347         inline PrvIterator() : Iterator<Provides, PrvIterator>(), Type(PrvVer) {}
 348         inline PrvIterator(pkgCache &Owner, Provides *Trg, Version*) :
 349                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvVer) {
 350                 if (S == 0)
 351                         S = Owner.ProvideP;
 352         }
 353         inline PrvIterator(pkgCache &Owner, Provides *Trg, Package*) :
 354                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvPkg) {
 355                 if (S == 0)
 356                         S = Owner.ProvideP;
 357         }
 358 };
 359                                                                         /*}}}*/
 360 // Package file                                                         /*{{{*/
 361 class pkgCache::PkgFileIterator : public Iterator<PackageFile, PkgFileIterator> {
 362         protected:
 363         inline PackageFile* OwnerPointer() const {
 364                 return (Owner != 0) ? Owner->PkgFileP : 0;
 365         }
 366
 367         public:
 368         // Iteration
 369         void operator ++(int) {if (S != Owner->PkgFileP) S = Owner->PkgFileP + S->NextFile;}
 370         inline void operator ++() {operator ++(0);}
 371
 372         // Accessors
 373         inline const char *FileName() const {return S->FileName == 0?0:Owner->StrP + S->FileName;}
 374         inline const char *Archive() const {return S->Archive == 0?0:Owner->StrP + S->Archive;}
 375         inline const char *Component() const {return S->Component == 0?0:Owner->StrP + S->Component;}
 376         inline const char *Version() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 377         inline const char *Origin() const {return S->Origin == 0?0:Owner->StrP + S->Origin;}
 378         inline const char *Codename() const {return S->Codename ==0?0:Owner->StrP + S->Codename;}
 379         inline const char *Label() const {return S->Label == 0?0:Owner->StrP + S->Label;}
 380         inline const char *Site() const {return S->Site == 0?0:Owner->StrP + S->Site;}
 381         inline const char *Architecture() const {return S->Architecture == 0?0:Owner->StrP + S->Architecture;}
 382         inline const char *IndexType() const {return S->IndexType == 0?0:Owner->StrP + S->IndexType;}
 383
 384         bool IsOk();
 385         std::string RelStr();
 386
 387         // Constructors
 388         inline PkgFileIterator() : Iterator<PackageFile, PkgFileIterator>() {}
 389         inline PkgFileIterator(pkgCache &Owner) : Iterator<PackageFile, PkgFileIterator>(Owner, Owner.PkgFileP) {}
 390         inline PkgFileIterator(pkgCache &Owner,PackageFile *Trg) : Iterator<PackageFile, PkgFileIterator>(Owner, Trg) {}
 391 };
 392                                                                         /*}}}*/
 393 // Version File                                                         /*{{{*/
 394 class pkgCache::VerFileIterator : public pkgCache::Iterator<VerFile, VerFileIterator> {
 395         protected:
 396         inline VerFile* OwnerPointer() const {
 397                 return (Owner != 0) ? Owner->VerFileP : 0;
 398         }
 399
 400         public:
 401         // Iteration
 402         void operator ++(int) {if (S != Owner->VerFileP) S = Owner->VerFileP + S->NextFile;}
 403         inline void operator ++() {operator ++(0);}
 404
 405         // Accessors
 406         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 407
 408         inline VerFileIterator() : Iterator<VerFile, VerFileIterator>() {}
 409         inline VerFileIterator(pkgCache &Owner,VerFile *Trg) : Iterator<VerFile, VerFileIterator>(Owner, Trg) {}
 410 };
 411                                                                         /*}}}*/
 412 // Description File                                                     /*{{{*/
 413 class pkgCache::DescFileIterator : public Iterator<DescFile, DescFileIterator> {
 414         protected:
 415         inline DescFile* OwnerPointer() const {
 416                 return (Owner != 0) ? Owner->DescFileP : 0;
 417         }
 418
 419         public:
 420         // Iteration
 421         void operator ++(int) {if (S != Owner->DescFileP) S = Owner->DescFileP + S->NextFile;}
 422         inline void operator ++() {operator ++(0);}
 423
 424         // Accessors
 425         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 426
 427         inline DescFileIterator() : Iterator<DescFile, DescFileIterator>() {}
 428         inline DescFileIterator(pkgCache &Owner,DescFile *Trg) : Iterator<DescFile, DescFileIterator>(Owner, Trg) {}
 429 };
 430                                                                         /*}}}*/
 431 // Inlined Begin functions can't be in the class because of order problems /*{{{*/
 432 inline pkgCache::PkgIterator pkgCache::GrpIterator::PackageList() const
 433        {return PkgIterator(*Owner,Owner->PkgP + S->FirstPackage);}
 434 inline pkgCache::VerIterator pkgCache::PkgIterator::VersionList() const
 435        {return VerIterator(*Owner,Owner->VerP + S->VersionList);}
 436 inline pkgCache::VerIterator pkgCache::PkgIterator::CurrentVer() const
 437        {return VerIterator(*Owner,Owner->VerP + S->CurrentVer);}
 438 inline pkgCache::DepIterator pkgCache::PkgIterator::RevDependsList() const
 439        {return DepIterator(*Owner,Owner->DepP + S->RevDepends,S);}
 440 inline pkgCache::PrvIterator pkgCache::PkgIterator::ProvidesList() const
 441        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 442 inline pkgCache::DescIterator pkgCache::VerIterator::DescriptionList() const
 443        {return DescIterator(*Owner,Owner->DescP + S->DescriptionList);}
 444 inline pkgCache::PrvIterator pkgCache::VerIterator::ProvidesList() const
 445        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 446 inline pkgCache::DepIterator pkgCache::VerIterator::DependsList() const
 447        {return DepIterator(*Owner,Owner->DepP + S->DependsList,S);}
 448 inline pkgCache::VerFileIterator pkgCache::VerIterator::FileList() const
 449        {return VerFileIterator(*Owner,Owner->VerFileP + S->FileList);}
 450 inline pkgCache::DescFileIterator pkgCache::DescIterator::FileList() const
 451        {return DescFileIterator(*Owner,Owner->DescFileP + S->FileList);}
 452                                                                         /*}}}*/
 453 #endif