paludis  Version 2.6.0
package_id.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 2007, 2008, 2009, 2010, 2011, 2014 Ciaran McCreesh
5  *
6  * This file is part of the Paludis package manager. Paludis is free software;
7  * you can redistribute it and/or modify it under the terms of the GNU General
8  * Public License version 2, as published by the Free Software Foundation.
9  *
10  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
11  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
13  * details.
14  *
15  * You should have received a copy of the GNU General Public License along with
16  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
17  * Place, Suite 330, Boston, MA 02111-1307 USA
18  */
19 
20 #ifndef PALUDIS_GUARD_PALUDIS_PACKAGE_ID_HH
21 #define PALUDIS_GUARD_PALUDIS_PACKAGE_ID_HH 1
22 
24 
26 #include <paludis/util/operators.hh>
27 #include <paludis/util/pimp.hh>
28 #include <paludis/util/wrapped_forward_iterator.hh>
29 #include <paludis/util/wrapped_output_iterator.hh>
30 #include <paludis/util/fs_path-fwd.hh>
31 #include <paludis/util/set.hh>
32 #include <paludis/util/sequence.hh>
33 
34 #include <paludis/action-fwd.hh>
35 #include <paludis/dep_spec-fwd.hh>
36 #include <paludis/spec_tree-fwd.hh>
37 #include <paludis/mask-fwd.hh>
39 #include <paludis/metadata_key_holder.hh>
40 #include <paludis/name-fwd.hh>
42 #include <paludis/contents-fwd.hh>
44 #include <paludis/choice-fwd.hh>
45 #include <paludis/slot-fwd.hh>
46 
47 #include <memory>
48 
49 /** \file
50  * Declarations for PackageID classes.
51  *
52  * \ingroup g_package_id
53  *
54  * \section Examples
55  *
56  * - \ref example_package_id.cc "example_package_id.cc" (for package IDs)
57  * - \ref example_action.cc "example_action.cc" (for actions)
58  * - \ref example_metadata_key.cc "example_metadata_key.cc" (for metadata keys)
59  * - \ref example_mask.cc "example_mask.cc" (for masks)
60  */
61 
62 namespace paludis
63 {
64  /**
65  * A PackageID represents a unique package version in a particular
66  * Repository.
67  *
68  * All PackageID instances have some basic identification data:
69  *
70  * - A name
71  * - A version
72  * - An owning repository
73  *
74  * It should be noted that the above together are not sufficient to uniquely
75  * identify a package. Some repositories support multiple slots per version
76  * of a package, and some repositories support additional affixes that
77  * prevent a package from being uniquely identifiable merely by the above.
78  *
79  * PackageID instances also have:
80  *
81  * - A collection of metadata keys. Some of these keys have a particular
82  * specific role in certain places. These can be fetched via blah_key()
83  * methods, all of which may return an empty pointer. Other keys have no
84  * meaningful global role, and can only be fetched using the iteration
85  * methods.
86  *
87  * - A collection (often empty) of masks. A masked package cannot be
88  * installed.
89  *
90  * A PackageID instance may support certain actions, which are represented
91  * via an Action subclass instance.
92  *
93  * \ingroup g_package_id
94  */
97  public MetadataKeyHolder
98  {
99  private:
100  Pimp<PackageID> _imp;
101 
102  protected:
103  /**
104  * Add a new Mask.
105  */
106  virtual void add_mask(const std::shared_ptr<const Mask> &) const;
107 
108  /**
109  * Add a new OverriddenMask.
110  *
111  * \since 0.34
112  */
113  virtual void add_overridden_mask(const std::shared_ptr<const OverriddenMask> &) const;
114 
115  /**
116  * This method will be called before any of the mask iteration
117  * methods does its work. It can be used by subclasses to implement
118  * as-needed loading of masks.
119  */
120  virtual void need_masks_added() const = 0;
121 
122  public:
123  ///\name Basic operations
124  ///\{
125 
126  PackageID();
127  virtual ~PackageID() = 0;
128 
129  std::size_t hash() const PALUDIS_ATTRIBUTE((warn_unused_result));
130 
131  ///\}
132 
133  ///\name Name related operations
134  ///\{
135 
136  /**
137  * Return our canonical string representation.
138  *
139  * This method (which is called by paludis::stringify()) should be
140  * used when outputting a PackageID or a PackageID's version. Some
141  * repositories need to display additional information to identify a
142  * package, so outputting merely the name and / or version may be
143  * insufficient.
144  */
145  virtual const std::string canonical_form(const PackageIDCanonicalForm) const = 0;
146 
147  /**
148  * What is our package name?
149  *
150  * Use canonical_form instead for outputting.
151  */
152  virtual const QualifiedPackageName name() const = 0;
153 
154  /**
155  * What is our package version?
156  *
157  * Use canonical_form instead for outputting.
158  */
159  virtual const VersionSpec version() const = 0;
160 
161  /**
162  * What is our owning repository?
163  *
164  * \since 0.58
165  */
166  virtual const RepositoryName repository_name() const = 0;
167 
168  /**
169  * Return a PackageDepSpec that uniquely identifies us.
170  *
171  * When stringified, can be turned back into an equivalent unique
172  * PackageDepSpec by using parse_user_package_dep_spec.
173  *
174  * \since 0.36
175  */
176  virtual PackageDepSpec uniquely_identifying_spec() const = 0;
177 
178  ///\}
179 
180  ///\name Specific metadata keys
181  ///\{
182 
183  /**
184  * The slot, if specified, controls whether the package can be
185  * installed in parallel with other versions of the same package.
186  *
187  * \since 0.36
188  */
189  virtual const std::shared_ptr<const MetadataValueKey<Slot> > slot_key() const = 0;
190 
191  /**
192  * The keywords_key, if non-zero, is used by FindUnusedPackagesTask
193  * to determine whether a package is unused.
194  */
195  virtual const std::shared_ptr<const MetadataCollectionKey<KeywordNameSet> > keywords_key() const = 0;
196 
197  /**
198  * The dependencies_key, if non-zero, provides all of a package's
199  * dependencies.
200  *
201  * If dependencies_key is used, the client should ignore
202  * build_dependencies_key, run_dependencies_key and post_dependencies_key.
203  *
204  * Repositories that support this key must also provide the old
205  * split out keys.
206  *
207  * \since 0.41
208  */
209  virtual const std::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > dependencies_key() const = 0;
210 
211  /**
212  * The build_dependencies_key, if non-zero, indicates a package's
213  * build-time dependencies.
214  */
215  virtual const std::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > build_dependencies_key() const = 0;
216 
217  /**
218  * The run_dependencies_key, if non-zero, indicates a package's
219  * run-time dependencies.
220  */
221  virtual const std::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > run_dependencies_key() const = 0;
222 
223  /**
224  * The post_dependencies_key, if non-zero, indicates a package's
225  * post-merge dependencies.
226  */
227  virtual const std::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > post_dependencies_key() const = 0;
228 
229  /**
230  * The fetches_key, if non-zero, indicates files that have to be fetched
231  * in order to install a package.
232  */
233  virtual const std::shared_ptr<const MetadataSpecTreeKey<FetchableURISpecTree> > fetches_key() const = 0;
234 
235  /**
236  * The homepage_key, if non-zero, describes a package's homepages.
237  */
238  virtual const std::shared_ptr<const MetadataSpecTreeKey<SimpleURISpecTree> > homepage_key() const = 0;
239 
240  /**
241  * The short_description_key, if non-zero, provides a short (no more
242  * than a few hundred characters) description of a package.
243  */
244  virtual const std::shared_ptr<const MetadataValueKey<std::string> > short_description_key() const = 0;
245 
246  /**
247  * The long_description_key, if non-zero, provides a long
248  * description of a package.
249  */
250  virtual const std::shared_ptr<const MetadataValueKey<std::string> > long_description_key() const = 0;
251 
252  /**
253  * The installed_time_key, if non-zero, contains the time a package
254  * was installed. It affects dependency resolution if DepList is
255  * using dl_reinstall_scm_daily or dl_reinstall_scm_weekly.
256  */
257  virtual const std::shared_ptr<const MetadataTimeKey> installed_time_key() const = 0;
258 
259  /**
260  * The from_repositories key, if non-zero, contains the set of repositories
261  * that the ID is 'from'. An ID can be 'from' multiple repositories if, for
262  * example, it was built via a binary package.
263  */
264  virtual const std::shared_ptr<const MetadataCollectionKey<Set<std::string> > > from_repositories_key() const = 0;
265 
266  /**
267  * The fs_location_key, if non-zero, indicates the filesystem
268  * location (for example, the ebuild file or VDB directory) that
269  * best describes the location of a PackageID.
270  */
271  virtual const std::shared_ptr<const MetadataValueKey<FSPath> > fs_location_key() const = 0;
272 
273  /**
274  * The choices_key, if non-zero, contains zero or more
275  * MetadataValueKey<std::shared_ptr<const Choice> > child
276  * keys holding choice information for this ID.
277  */
278  virtual const std::shared_ptr<const MetadataValueKey<std::shared_ptr<const Choices> > > choices_key() const = 0;
279 
280  /**
281  * The behaviours_key may contain strings indicating that the PackageID
282  * behaves in a particular way.
283  *
284  * Strings with recognised meanings currently are:
285  *
286  * - "transient", saying that an installed ID's origin is expected not to exist
287  * - "used", saying that an installed ID should not be treated as unused
288  * - "unbinaryable", saying that we should be excluded from requests to create a binary
289  * - "unchrootable", saying that we should be excluded from requests to install to a chroot
290  * - "binary", saying that we are already a binary package
291  *
292  * \since 0.48
293  */
294  virtual const std::shared_ptr<const MetadataCollectionKey<Set<std::string> > > behaviours_key() const = 0;
295 
296  ///\}
297 
298  ///\name Actions
299  ///\{
300 
301  /**
302  * Do we support a particular action?
303  *
304  * Attempting to call perform_action with an unsupported action type
305  * will lead to an UnsupportedActionError. However, in performance
306  * critical code and in situations where creating a full Action
307  * subclass instance is non-trivial, supports_action is much
308  * simpler.
309  */
310  virtual bool supports_action(const SupportsActionTestBase &) const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
311 
312  /**
313  * Perform the specified action.
314  */
315  virtual void perform_action(Action &) const = 0;
316 
317  /**
318  * The contents, if non-zero, contains the contents of a
319  * package. For installed packages, this means the files installed;
320  * for installable packages, this means the files that will be
321  * installed (if known, which it may be for some binary packages).
322  *
323  * \since 0.66
324  */
325  virtual const std::shared_ptr<const Contents> contents() const = 0;
326 
327  ///\}
328 
329  ///\name Masks
330  ///\{
331 
332  struct MasksConstIteratorTag;
334 
335  MasksConstIterator begin_masks() const PALUDIS_ATTRIBUTE((warn_unused_result));
336  MasksConstIterator end_masks() const PALUDIS_ATTRIBUTE((warn_unused_result));
337 
338  /**
339  * Do we have any effective masks? Equivalent to begin_masks() != end_masks().
340  */
341  bool masked() const PALUDIS_ATTRIBUTE((warn_unused_result));
342 
343  ///\}
344 
345  ///\name Overridden masks
346  ///\{
347  ///\since 0.34
348 
349  struct OverriddenMasksConstIteratorTag;
351 
352  OverriddenMasksConstIterator begin_overridden_masks() const PALUDIS_ATTRIBUTE((warn_unused_result));
353  OverriddenMasksConstIterator end_overridden_masks() const PALUDIS_ATTRIBUTE((warn_unused_result));
354 
355  ///\}
356 
357  ///\name Extra comparisons
358  ///\{
359 
360  /**
361  * Perform an arbitrary less than comparison on another PackageID.
362  *
363  * Used by PackageIDSetComparator and operator==. This function
364  * should not be used by anything else.
365  *
366  * This function will only be called if the other PackageID has the
367  * same name, version and repository as this. If this is not enough
368  * to uniquely identify an ID (e.g. if there is an affix, or if multiple
369  * slots per version are allowed), then this function's
370  * implementation must differentiate appropriately.
371  */
372  virtual bool arbitrary_less_than_comparison(const PackageID &) const
373  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
374 
375  /**
376  * Provide any additional hash information for a PackageID.
377  *
378  * The standard PackageID hash incorporates the repository name, the
379  * package name and the version of the package. If this function is
380  * defined, its value is also used when determining a hash. This can
381  * provide increased performance if a repository uses affixes or
382  * multiple slots per version.
383  */
384  virtual std::size_t extra_hash_value() const
385  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
386 
387  ///\}
388 
389  /**
390  * Allow the PackageID to drop any memory-cached metadata it holds.
391  *
392  * \since 0.42
393  */
394  virtual void can_drop_in_memory_cache() const;
395  };
396 
397  /**
398  * PackageID instances are equality-comparable.
399  *
400  * \ingroup g_package_id
401  * \since 0.26
402  */
403  bool operator== (const PackageID &, const PackageID &) PALUDIS_ATTRIBUTE((warn_unused_result)) PALUDIS_VISIBLE;
404 
405  /**
406  * A comparison functor that uses PackageID::arbitrary_less_than_comparison
407  * to provide a meaningless but stable ordering for PackageIDSet.
408  *
409  * \ingroup g_package_id
410  * \since 0.26
411  * \nosubgrouping
412  */
413  class PALUDIS_VISIBLE PackageIDSetComparator
414  {
415  public:
416  /**
417  * Perform an arbitrary less-than comparison.
418  */
419  bool operator() (const std::shared_ptr<const PackageID> &,
420  const std::shared_ptr<const PackageID> &) const;
421  };
422 
423  /**
424  * A comparison functor that provides a less-than comparison on PackageID
425  * instances according to, in order, their name, their version, their
426  * repository's importance according to the supplied Environment,
427  * and Environment::arbitrary_less_than_comparison.
428  *
429  * \ingroup g_package_id
430  * \since 0.26
431  * \nosubgrouping
432  */
433  class PALUDIS_VISIBLE PackageIDComparator
434  {
435  private:
437 
438  public:
439  ///\name Standard library typedefs
440  ///\{
441 
442  typedef bool result_type;
443 
444  ///\}
445 
446  ///\name Basic operations
447  ///\{
448 
449  PackageIDComparator(const Environment * const);
452 
453  ///\}
454 
455  /**
456  * Perform the less-than comparison.
457  */
458  bool operator() (const std::shared_ptr<const PackageID> &,
459  const std::shared_ptr<const PackageID> &) const;
460  };
461 
462  extern template class PALUDIS_VISIBLE Sequence<std::shared_ptr<const PackageID> >;
463  extern template class PALUDIS_VISIBLE WrappedForwardIterator<Sequence<std::shared_ptr<const PackageID> >::ConstIteratorTag,
464  const std::shared_ptr<const PackageID> >;
465  extern template class PALUDIS_VISIBLE WrappedForwardIterator<Sequence<std::shared_ptr<const PackageID> >::ReverseConstIteratorTag,
466  const std::shared_ptr<const PackageID> >;
467  extern template class PALUDIS_VISIBLE WrappedOutputIterator<Sequence<std::shared_ptr<const PackageID> >::InserterTag,
468  std::shared_ptr<const PackageID> >;
469 
470  extern template class PALUDIS_VISIBLE Set<std::shared_ptr<const PackageID>, PackageIDSetComparator>;
471  extern template class PALUDIS_VISIBLE WrappedForwardIterator<Set<std::shared_ptr<const PackageID>, PackageIDSetComparator>::ConstIteratorTag,
472  const std::shared_ptr<const PackageID> >;
473  extern template class PALUDIS_VISIBLE WrappedOutputIterator<Set<std::shared_ptr<const PackageID>, PackageIDSetComparator>::InserterTag,
474  std::shared_ptr<const PackageID> >;
475 
478 }
479 
480 #endif
Definition: package_id.hh:413
Definition: pimp.hh:51
Definition: about_metadata-fwd.hh:23
Definition: name.hh:110
PackageIDCanonicalForm
Definition: package_id-fwd.hh:17
Definition: version_spec.hh:107
Definition: wrapped_output_iterator-fwd.hh:26
Definition: package_id.hh:95
Definition: dep_spec.hh:345
Definition: sequence-fwd.hh:32
Definition: environment.hh:200
Definition: action.hh:268
Definition: set-fwd.hh:35
Definition: wrapped_forward_iterator-fwd.hh:26
Definition: wrapped_value-fwd.hh:29
Definition: package_id.hh:433
Definition: action.hh:618
Definition: metadata_key_holder.hh:38
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:53
#define PALUDIS_VISIBLE
Definition: attributes.hh:59
bool operator==(const PackageID &, const PackageID &) PALUDIS_ATTRIBUTE((warn_unused_result)) PALUDIS_VISIBLE