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 Group().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         /** \brief source package name this version comes from
 219            Always contains the name, even if it is the same as the binary name */
 220         inline const char *SourcePkgName() const {return Owner->StrP + S->SourcePkgName;}
 221         /** \brief source version this version comes from
 222            Always contains the version string, even if it is the same as the binary version */
 223         inline const char *SourceVerStr() const {return Owner->StrP + S->SourceVerStr;}
 224         inline const char *Arch() const {
 225                 if ((S->MultiArch & pkgCache::Version::All) == pkgCache::Version::All)
 226                         return "all";
 227                 return S->ParentPkg == 0?0:Owner->StrP + ParentPkg()->Arch;
 228         }
 229         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 230
 231         inline DescIterator DescriptionList() const;
 232         DescIterator TranslatedDescription() const;
 233         inline DepIterator DependsList() const;
 234         inline PrvIterator ProvidesList() const;
 235         inline VerFileIterator FileList() const;
 236         bool Downloadable() const;
 237         inline const char *PriorityType() const {return Owner->Priority(S->Priority);}
 238         const char *MultiArchType() const APT_PURE;
 239         std::string RelStr() const;
 240
 241         bool Automatic() const;
 242         VerFileIterator NewestFile() const;
 243
 244         inline VerIterator(pkgCache &Owner,Version *Trg = 0) : Iterator<Version, VerIterator>(Owner, Trg) {
 245                 if (S == 0)
 246                         S = OwnerPointer();
 247         }
 248         inline VerIterator() : Iterator<Version, VerIterator>() {}
 249 };
 250                                                                         /*}}}*/
 251 // Description Iterator                                                 /*{{{*/
 252 class pkgCache::DescIterator : public Iterator<Description, DescIterator> {
 253         protected:
 254         inline Description* OwnerPointer() const {
 255                 return (Owner != 0) ? Owner->DescP : 0;
 256         }
 257
 258         public:
 259         // Iteration
 260         void operator ++(int) {if (S != Owner->DescP) S = Owner->DescP + S->NextDesc;}
 261         inline void operator ++() {operator ++(0);}
 262
 263         // Comparison
 264         int CompareDesc(const DescIterator &B) const;
 265
 266         // Accessors
 267         inline const char *LanguageCode() const {return Owner->StrP + S->language_code;}
 268         inline const char *md5() const {return Owner->StrP + S->md5sum;}
 269         inline DescFileIterator FileList() const;
 270
 271         inline DescIterator() : Iterator<Description, DescIterator>() {}
 272         inline DescIterator(pkgCache &Owner,Description *Trg = 0) : Iterator<Description, DescIterator>(Owner, Trg) {
 273                 if (S == 0)
 274                         S = Owner.DescP;
 275         }
 276 };
 277                                                                         /*}}}*/
 278 // Dependency iterator                                                  /*{{{*/
 279 class pkgCache::DepIterator : public Iterator<Dependency, DepIterator> {
 280         enum {DepVer, DepRev} Type;
 281
 282         protected:
 283         inline Dependency* OwnerPointer() const {
 284                 return (Owner != 0) ? Owner->DepP : 0;
 285         }
 286
 287         public:
 288         // Iteration
 289         void operator ++(int) {if (S != Owner->DepP) S = Owner->DepP +
 290                 (Type == DepVer ? S->NextDepends : S->NextRevDepends);}
 291         inline void operator ++() {operator ++(0);}
 292
 293         // Accessors
 294         inline const char *TargetVer() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 295         inline PkgIterator TargetPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->Package);}
 296         inline PkgIterator SmartTargetPkg() const {PkgIterator R(*Owner,0);SmartTargetPkg(R);return R;}
 297         inline VerIterator ParentVer() const {return VerIterator(*Owner,Owner->VerP + S->ParentVer);}
 298         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->ParentVer].ParentPkg);}
 299         inline bool Reverse() const {return Type == DepRev;}
 300         bool IsCritical() const APT_PURE;
 301         bool IsNegative() const APT_PURE;
 302         bool IsIgnorable(PrvIterator const &Prv) const APT_PURE;
 303         bool IsIgnorable(PkgIterator const &Pkg) const APT_PURE;
 304         bool IsMultiArchImplicit() const APT_PURE;
 305         bool IsSatisfied(VerIterator const &Ver) const APT_PURE;
 306         bool IsSatisfied(PrvIterator const &Prv) const APT_PURE;
 307         void GlobOr(DepIterator &Start,DepIterator &End);
 308         Version **AllTargets() const;
 309         bool SmartTargetPkg(PkgIterator &Result) const;
 310         inline const char *CompType() const {return Owner->CompType(S->CompareOp);}
 311         inline const char *DepType() const {return Owner->DepType(S->Type);}
 312
 313         //Nice printable representation
 314         friend std::ostream& operator <<(std::ostream& out, DepIterator D);
 315
 316         inline DepIterator(pkgCache &Owner, Dependency *Trg, Version* = 0) :
 317                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepVer) {
 318                 if (S == 0)
 319                         S = Owner.DepP;
 320         }
 321         inline DepIterator(pkgCache &Owner, Dependency *Trg, Package*) :
 322                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepRev) {
 323                 if (S == 0)
 324                         S = Owner.DepP;
 325         }
 326         inline DepIterator() : Iterator<Dependency, DepIterator>(), Type(DepVer) {}
 327 };
 328                                                                         /*}}}*/
 329 // Provides iterator                                                    /*{{{*/
 330 class pkgCache::PrvIterator : public Iterator<Provides, PrvIterator> {
 331         enum {PrvVer, PrvPkg} Type;
 332
 333         protected:
 334         inline Provides* OwnerPointer() const {
 335                 return (Owner != 0) ? Owner->ProvideP : 0;
 336         }
 337
 338         public:
 339         // Iteration
 340         void operator ++(int) {if (S != Owner->ProvideP) S = Owner->ProvideP +
 341                 (Type == PrvVer?S->NextPkgProv:S->NextProvides);}
 342         inline void operator ++() {operator ++(0);}
 343
 344         // Accessors
 345         inline const char *Name() const {return ParentPkg().Name();}
 346         inline const char *ProvideVersion() const {return S->ProvideVersion == 0?0:Owner->StrP + S->ProvideVersion;}
 347         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 348         inline VerIterator OwnerVer() const {return VerIterator(*Owner,Owner->VerP + S->Version);}
 349         inline PkgIterator OwnerPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->Version].ParentPkg);}
 350
 351         bool IsMultiArchImplicit() const APT_PURE;
 352
 353         inline PrvIterator() : Iterator<Provides, PrvIterator>(), Type(PrvVer) {}
 354         inline PrvIterator(pkgCache &Owner, Provides *Trg, Version*) :
 355                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvVer) {
 356                 if (S == 0)
 357                         S = Owner.ProvideP;
 358         }
 359         inline PrvIterator(pkgCache &Owner, Provides *Trg, Package*) :
 360                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvPkg) {
 361                 if (S == 0)
 362                         S = Owner.ProvideP;
 363         }
 364 };
 365                                                                         /*}}}*/
 366 // Package file                                                         /*{{{*/
 367 class pkgCache::PkgFileIterator : public Iterator<PackageFile, PkgFileIterator> {
 368         protected:
 369         inline PackageFile* OwnerPointer() const {
 370                 return (Owner != 0) ? Owner->PkgFileP : 0;
 371         }
 372
 373         public:
 374         // Iteration
 375         void operator ++(int) {if (S != Owner->PkgFileP) S = Owner->PkgFileP + S->NextFile;}
 376         inline void operator ++() {operator ++(0);}
 377
 378         // Accessors
 379         inline const char *FileName() const {return S->FileName == 0?0:Owner->StrP + S->FileName;}
 380         inline const char *Archive() const {return S->Archive == 0?0:Owner->StrP + S->Archive;}
 381         inline const char *Component() const {return S->Component == 0?0:Owner->StrP + S->Component;}
 382         inline const char *Version() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 383         inline const char *Origin() const {return S->Origin == 0?0:Owner->StrP + S->Origin;}
 384         inline const char *Codename() const {return S->Codename ==0?0:Owner->StrP + S->Codename;}
 385         inline const char *Label() const {return S->Label == 0?0:Owner->StrP + S->Label;}
 386         inline const char *Site() const {return S->Site == 0?0:Owner->StrP + S->Site;}
 387         inline const char *Architecture() const {return S->Architecture == 0?0:Owner->StrP + S->Architecture;}
 388         inline const char *IndexType() const {return S->IndexType == 0?0:Owner->StrP + S->IndexType;}
 389
 390         bool IsOk();
 391         std::string RelStr();
 392
 393         // Constructors
 394         inline PkgFileIterator() : Iterator<PackageFile, PkgFileIterator>() {}
 395         inline PkgFileIterator(pkgCache &Owner) : Iterator<PackageFile, PkgFileIterator>(Owner, Owner.PkgFileP) {}
 396         inline PkgFileIterator(pkgCache &Owner,PackageFile *Trg) : Iterator<PackageFile, PkgFileIterator>(Owner, Trg) {}
 397 };
 398                                                                         /*}}}*/
 399 // Version File                                                         /*{{{*/
 400 class pkgCache::VerFileIterator : public pkgCache::Iterator<VerFile, VerFileIterator> {
 401         protected:
 402         inline VerFile* OwnerPointer() const {
 403                 return (Owner != 0) ? Owner->VerFileP : 0;
 404         }
 405
 406         public:
 407         // Iteration
 408         void operator ++(int) {if (S != Owner->VerFileP) S = Owner->VerFileP + S->NextFile;}
 409         inline void operator ++() {operator ++(0);}
 410
 411         // Accessors
 412         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 413
 414         inline VerFileIterator() : Iterator<VerFile, VerFileIterator>() {}
 415         inline VerFileIterator(pkgCache &Owner,VerFile *Trg) : Iterator<VerFile, VerFileIterator>(Owner, Trg) {}
 416 };
 417                                                                         /*}}}*/
 418 // Description File                                                     /*{{{*/
 419 class pkgCache::DescFileIterator : public Iterator<DescFile, DescFileIterator> {
 420         protected:
 421         inline DescFile* OwnerPointer() const {
 422                 return (Owner != 0) ? Owner->DescFileP : 0;
 423         }
 424
 425         public:
 426         // Iteration
 427         void operator ++(int) {if (S != Owner->DescFileP) S = Owner->DescFileP + S->NextFile;}
 428         inline void operator ++() {operator ++(0);}
 429
 430         // Accessors
 431         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 432
 433         inline DescFileIterator() : Iterator<DescFile, DescFileIterator>() {}
 434         inline DescFileIterator(pkgCache &Owner,DescFile *Trg) : Iterator<DescFile, DescFileIterator>(Owner, Trg) {}
 435 };
 436                                                                         /*}}}*/
 437 // Inlined Begin functions can't be in the class because of order problems /*{{{*/
 438 inline pkgCache::PkgIterator pkgCache::GrpIterator::PackageList() const
 439        {return PkgIterator(*Owner,Owner->PkgP + S->FirstPackage);}
 440 inline pkgCache::VerIterator pkgCache::PkgIterator::VersionList() const
 441        {return VerIterator(*Owner,Owner->VerP + S->VersionList);}
 442 inline pkgCache::VerIterator pkgCache::PkgIterator::CurrentVer() const
 443        {return VerIterator(*Owner,Owner->VerP + S->CurrentVer);}
 444 inline pkgCache::DepIterator pkgCache::PkgIterator::RevDependsList() const
 445        {return DepIterator(*Owner,Owner->DepP + S->RevDepends,S);}
 446 inline pkgCache::PrvIterator pkgCache::PkgIterator::ProvidesList() const
 447        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 448 inline pkgCache::DescIterator pkgCache::VerIterator::DescriptionList() const
 449        {return DescIterator(*Owner,Owner->DescP + S->DescriptionList);}
 450 inline pkgCache::PrvIterator pkgCache::VerIterator::ProvidesList() const
 451        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 452 inline pkgCache::DepIterator pkgCache::VerIterator::DependsList() const
 453        {return DepIterator(*Owner,Owner->DepP + S->DependsList,S);}
 454 inline pkgCache::VerFileIterator pkgCache::VerIterator::FileList() const
 455        {return VerFileIterator(*Owner,Owner->VerFileP + S->FileList);}
 456 inline pkgCache::DescFileIterator pkgCache::DescIterator::FileList() const
 457        {return DescFileIterator(*Owner,Owner->DescFileP + S->FileList);}
 458                                                                         /*}}}*/
 459 #endif