paludis  Version 2.6.0
dep_spec.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 2005, 2006, 2007, 2008, 2009, 2010, 2011 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_DEP_SPEC_HH
21 #define PALUDIS_GUARD_PALUDIS_DEP_SPEC_HH 1
22 
24 #include <paludis/util/clone.hh>
25 #include <paludis/util/pimp.hh>
26 #include <paludis/util/wrapped_forward_iterator.hh>
27 #include <paludis/util/fs_path.hh>
28 #include <paludis/util/named_value.hh>
29 
30 #include <paludis/changed_choices-fwd.hh>
31 #include <paludis/dep_label.hh>
32 #include <paludis/dep_spec-fwd.hh>
33 #include <paludis/name.hh>
37 #include <paludis/slot_requirement-fwd.hh>
40 #include <paludis/additional_package_dep_spec_requirement-fwd.hh>
41 #include <paludis/partially_made_package_dep_spec-fwd.hh>
42 #include <paludis/dep_spec_data-fwd.hh>
43 #include <paludis/dep_spec_annotations-fwd.hh>
44 
45 #include <memory>
46 
47 /** \file
48  * Declarations for dependency spec classes.
49  *
50  * \ingroup g_dep_spec
51  *
52  * \section Examples
53  *
54  * - \ref example_dep_spec.cc "example_dep_spec.cc" (for specifications)
55  * - \ref example_dep_label.cc "example_dep_label.cc" (for labels)
56  */
57 
58 namespace paludis
59 {
60  extern template class PALUDIS_VISIBLE Cloneable<DepSpec>;
61  extern template class Pimp<ConditionalDepSpec>;
62  extern template class PALUDIS_VISIBLE CloneUsingThis<DepSpec, ConditionalDepSpec>;
63  extern template class Pimp<PackageDepSpec>;
64  extern template class PALUDIS_VISIBLE CloneUsingThis<DepSpec, PackageDepSpec>;
65  extern template class Pimp<DependenciesLabelsDepSpec>;
66  extern template class Pimp<URILabelsDepSpec>;
67  extern template class Pimp<PlainTextLabelDepSpec>;
68 
69  /**
70  * Base class for a dependency spec.
71  *
72  * \ingroup g_dep_spec
73  * \nosubgrouping
74  */
76  public virtual Cloneable<DepSpec>
77  {
78  private:
79  Pimp<DepSpec> _imp;
80 
81  protected:
82  DepSpec();
83 
84  public:
85  ///\name Basic operations
86  ///\{
87 
88  virtual ~DepSpec();
89 
90  DepSpec(const DepSpec &) = delete;
91  DepSpec & operator= (const DepSpec &) = delete;
92 
93  ///\}
94 
95  /**
96  * Our annotations, may be null.
97  *
98  * \since 0.58
99  */
100  virtual const std::shared_ptr<const DepSpecAnnotations> maybe_annotations() const PALUDIS_ATTRIBUTE((warn_unused_result));
101 
102  /**
103  * Change our annotations, may be null.
104  *
105  * \since 0.58
106  */
107  virtual void set_annotations(const std::shared_ptr<const DepSpecAnnotations> &);
108  };
109 
110  /**
111  * Represents a "|| ( )" dependency block.
112  *
113  * \ingroup g_dep_spec
114  * \nosubgrouping
115  */
117  public DepSpec
118  {
119  public:
120  ///\name Basic operations
121  ///\{
122 
123  AnyDepSpec();
124 
125  ///\}
126 
127  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
128  };
129 
130  /**
131  * Represents a ( first second third ) or top level group of dependency
132  * specs.
133  *
134  * \ingroup g_dep_spec
135  * \nosubgrouping
136  */
138  public DepSpec
139  {
140  public:
141  ///\name Basic operations
142  ///\{
143 
144  AllDepSpec();
145 
146  ///\}
147 
148  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
149  };
150 
151  /**
152  * Represents a ^^ ( first second third ) group of requirements.
153  *
154  * \ingroup g_dep_spec
155  * \nosubgrouping
156  * \since 0.56
157  */
159  public DepSpec
160  {
161  public:
162  ///\name Basic operations
163  ///\{
164 
166 
167  ///\}
168 
169  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
170  };
171 
172  /**
173  * Represents a ?? ( first second third ) group of requirements.
174  *
175  * \ingroup g_dep_spec
176  * \nosubgrouping
177  * \since 0.56
178  */
180  public DepSpec
181  {
182  public:
183  ///\name Basic operations
184  ///\{
185 
187 
188  ///\}
189 
190  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
191  };
192 
193  /**
194  * Represents a dependency spec whose children should only be considered
195  * upon a certain condition (for example, a use dependency block).
196  *
197  * \ingroup g_dep_spec
198  * \since 0.26
199  * \nosubgrouping
200  */
202  public DepSpec,
203  public CloneUsingThis<DepSpec, ConditionalDepSpec>
204  {
205  friend std::ostream & operator<< (std::ostream &, const ConditionalDepSpec &);
206 
207  private:
209 
210  std::string _as_string() const;
211 
212  public:
213  ///\name Basic operations
214  ///\{
215 
216  ConditionalDepSpec(const std::shared_ptr<const ConditionalDepSpecData> &);
219 
220  ///\}
221 
222  /**
223  * Is our condition met?
224  *
225  * This takes into account inverses etc.
226  *
227  * \since 0.58 takes env, package_id
228  */
229  bool condition_met(
230  const Environment * const,
231  const std::shared_ptr<const PackageID> &) const PALUDIS_ATTRIBUTE((warn_unused_result));
232 
233  /**
234  * Would our condition met, if certain choices were changed?
235  *
236  * \since 0.58 takes env, package_id
237  */
238  bool condition_would_be_met_when(
239  const Environment * const,
240  const std::shared_ptr<const PackageID> &,
241  const ChangedChoices &) const PALUDIS_ATTRIBUTE((warn_unused_result));
242 
243  /**
244  * Is our condition meetable?
245  *
246  * This takes into account inverses, masks, forces etc.
247  *
248  * \since 0.58 takes env, package_id
249  */
250  bool condition_meetable(
251  const Environment * const,
252  const std::shared_ptr<const PackageID> &) const PALUDIS_ATTRIBUTE((warn_unused_result));
253 
254  /**
255  * Fetch our data.
256  *
257  * This shouldn't generally be used by clients, but some repositories use it
258  * to gain access to additional data stored in the ConditionalDepSpecData.
259  */
260  const std::shared_ptr<const ConditionalDepSpecData> data() const PALUDIS_ATTRIBUTE((warn_unused_result));
261  };
262 
263  /**
264  * A StringDepSpec represents a dep spec with an associated piece of text.
265  *
266  * \ingroup g_dep_spec
267  * \nosubgrouping
268  */
270  public DepSpec
271  {
272  private:
273  std::string _str;
274 
275  protected:
276  ///\name Basic operations
277  ///\{
278 
279  StringDepSpec(const std::string &);
280 
281  ~StringDepSpec();
282 
283  ///\}
284 
285  /**
286  * Change our text.
287  */
288  void set_text(const std::string &);
289 
290  public:
291  /**
292  * Fetch our text.
293  */
294  std::string text() const;
295  };
296 
297  namespace n
298  {
299  typedef Name<struct name_include_masked> include_masked;
300  typedef Name<struct name_path> path;
301  typedef Name<struct name_repository> repository;
302  }
303 
304  /**
305  * Data for PackageDepSpec.installable_to_repository_ptr() etc.
306  *
307  * \ingroup g_dep_spec
308  * \since 0.32
309  */
311  {
314  };
315 
316  /**
317  * Data for PackageDepSpec.installable_to_path_ptr() etc.
318  *
319  * \ingroup g_dep_spec
320  * \since 0.32
321  */
323  {
326  };
327 
328  /**
329  * A PackageDepSpec represents a package name (for example,
330  * 'app-editors/vim'), possibly with associated version and SLOT
331  * restrictions.
332  *
333  * A PackageDepSpec is implemented in terms of PackageDepSpecData. Individual
334  * repositories provide their own way of creating PackageDepSpec::Data that
335  * handle the native syntax for those repositories (e.g. CRAN uses
336  * "Blah (>= 1.23)" whilst E uses ">=cat/blah-1.23").
337  *
338  * To create a PackageDepSpec from user input, use
339  * parse_user_package_dep_spec(), and for programmer input, use
340  * make_package_dep_spec().
341  *
342  * \ingroup g_dep_spec
343  * \nosubgrouping
344  */
346  public StringDepSpec,
347  public CloneUsingThis<DepSpec, PackageDepSpec>
348  {
349  friend std::ostream & operator<< (std::ostream &, const PackageDepSpec &);
350 
351  private:
352  const PackageDepSpec & operator= (const PackageDepSpec &);
353  std::string _as_string() const;
354 
356 
357  public:
358  ///\name Basic operations
359  ///\{
360 
361  /**
362  * Constructor.
363  *
364  * Clients will usually use either parse_user_package_dep_spec() or
365  * make_package_dep_spec() rather than calling this method
366  * directly. Repositories will define their own way of creating
367  * a PackageDepSpec.
368  *
369  * \since 0.26
370  */
371  PackageDepSpec(const std::shared_ptr<const PackageDepSpecData> &);
372 
374 
375  ~PackageDepSpec();
376 
377  ///\}
378 
379  /**
380  * Fetch the package name (may be a zero pointer).
381  */
382  std::shared_ptr<const QualifiedPackageName> package_ptr() const;
383 
384  /**
385  * Fetch the package name part, if wildcarded, or a zero pointer otherwise.
386  */
387  std::shared_ptr<const PackageNamePart> package_name_part_ptr() const;
388 
389  /**
390  * Fetch the category name part, if wildcarded, or a zero pointer otherwise.
391  */
392  std::shared_ptr<const CategoryNamePart> category_name_part_ptr() const;
393 
394  /**
395  * Fetch the version requirements (may be a zero pointer).
396  */
397  std::shared_ptr<const VersionRequirements> version_requirements_ptr() const;
398 
399  /**
400  * Fetch the version requirements mode.
401  */
402  VersionRequirementsMode version_requirements_mode() const;
403 
404  /**
405  * Fetch the slot requirement (may be a zero pointer).
406  */
407  std::shared_ptr<const SlotRequirement> slot_requirement_ptr() const;
408 
409  /**
410  * Fetch the in-repository requirement (may be a zero pointer).
411  */
412  std::shared_ptr<const RepositoryName> in_repository_ptr() const;
413 
414  /**
415  * Fetch the installable-to-repository requirement (may be a zero pointer).
416  *
417  * \since 0.32
418  */
419  std::shared_ptr<const InstallableToRepository> installable_to_repository_ptr() const;
420 
421  /**
422  * Fetch the from-repository requirement (may be a zero pointer).
423  */
424  std::shared_ptr<const RepositoryName> from_repository_ptr() const;
425 
426  /**
427  * Fetch the installed-at-path requirement (may be a zero pointer).
428  *
429  * \since 0.32
430  */
431  std::shared_ptr<const FSPath> installed_at_path_ptr() const;
432 
433  /**
434  * Fetch the installable-to-path requirement (may be a zero pointer).
435  *
436  * \since 0.32
437  */
438  std::shared_ptr<const InstallableToPath> installable_to_path_ptr() const;
439 
440  /**
441  * Fetch any additional requirements (may be a zero pointer).
442  */
443  std::shared_ptr<const AdditionalPackageDepSpecRequirements> additional_requirements_ptr() const;
444 
445  /**
446  * Access to our data.
447  */
448  std::shared_ptr<const PackageDepSpecData> data() const;
449  };
450 
451  /**
452  * A PlainTextDepSpec represents a plain text entry.
453  *
454  * \ingroup g_dep_spec
455  * \nosubgrouping
456  */
458  public StringDepSpec
459  {
460  public:
461  ///\name Basic operations
462  ///\{
463 
464  PlainTextDepSpec(const std::string &);
465 
466  ///\}
467 
468  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
469  };
470 
471  /**
472  * A NamedSetDepSpec represents a named package set.
473  *
474  * \ingroup g_dep_spec
475  * \nosubgrouping
476  */
478  public StringDepSpec
479  {
480  private:
481  const SetName _name;
482 
483  public:
484  ///\name Basic operations
485  ///\{
486 
487  NamedSetDepSpec(const SetName &);
488 
489  ///\}
490 
491  /// Fetch the name of our set.
492  const SetName name() const PALUDIS_ATTRIBUTE((warn_unused_result));
493 
494  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
495  };
496 
497  /**
498  * A LicenseDepSpec represents a license entry.
499  *
500  * \ingroup g_dep_spec
501  * \since 0.26
502  * \nosubgrouping
503  */
505  public StringDepSpec
506  {
507  public:
508  ///\name Basic operations
509  ///\{
510 
511  LicenseDepSpec(const std::string &);
512 
513  ///\}
514 
515  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
516  };
517 
518  /**
519  * A FetchableURIDepSpec represents a fetchable URI part.
520  *
521  * It differs from a SimpleURIDepSpec in that it supports arrow notation. Arrows
522  * are used by exheres to allow downloading to a filename other than that used by
523  * the original URL.
524  *
525  * \ingroup g_dep_spec
526  * \since 0.26
527  * \nosubgrouping
528  */
530  public StringDepSpec
531  {
532  public:
533  ///\name Basic operations
534  ///\{
535 
536  FetchableURIDepSpec(const std::string &);
537 
538  ///\}
539 
540  /**
541  * The original URL (that is, the text to the left of the arrow, if present,
542  * or the entire text otherwise).
543  */
544  std::string original_url() const;
545 
546  /**
547  * The renamed URL filename (that is, the text to the right of the arrow,
548  * if present, or an empty string otherwise).
549  */
550  std::string renamed_url_suffix() const;
551 
552  /**
553  * The filename (that is, the renamed URL suffix, if present, or the text
554  * after the final / in the original URL otherwise).
555  */
556  std::string filename() const;
557 
558  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
559  };
560 
561  /**
562  * A SimpleURIDepSpec represents a simple URI part.
563  *
564  * Unlike FetchableURIDepSpec, arrow notation is not supported.
565  *
566  * \ingroup g_dep_spec
567  * \since 0.26
568  * \nosubgrouping
569  */
571  public StringDepSpec
572  {
573  public:
574  ///\name Basic operations
575  ///\{
576 
577  SimpleURIDepSpec(const std::string &);
578 
579  ///\}
580 
581  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
582  };
583 
584  /**
585  * Thrown if an invalid package dep spec specification is encountered.
586  *
587  * \ingroup g_exceptions
588  * \ingroup g_dep_spec
589  * \nosubgrouping
590  */
592  public Exception
593  {
594  public:
595  ///\name Basic operations
596  ///\{
597 
598  PackageDepSpecError(const std::string & msg) noexcept;
599 
600  ///\}
601  };
602 
603  /**
604  * A BlockDepSpec represents a block on a package name (for example,
605  * 'app-editors/vim'), possibly with associated version and SLOT
606  * restrictions.
607  *
608  * \ingroup g_dep_spec
609  * \nosubgrouping
610  */
612  public StringDepSpec
613  {
614  private:
615  PackageDepSpec _spec;
616 
617  public:
618  ///\name Basic operations
619  ///\{
620 
621  BlockDepSpec(const std::string & text, const PackageDepSpec & spec);
622 
623  BlockDepSpec(const BlockDepSpec &);
624 
625  ///\}
626 
627  /**
628  * Fetch the spec we're blocking.
629  *
630  * \since 0.41
631  */
632  const PackageDepSpec blocking() const PALUDIS_ATTRIBUTE((warn_unused_result));
633 
634  /**
635  * Our annotations, may be null. Forwards to the
636  * underlying PackageDepSpec.
637  *
638  * \since 0.73
639  */
640  virtual const std::shared_ptr<const DepSpecAnnotations> maybe_annotations() const PALUDIS_ATTRIBUTE((warn_unused_result));
641 
642  /**
643  * Change our annotations, may be null. Forwards to the
644  * underlying PackageDepSpec.
645  *
646  * \since 0.73
647  */
648  virtual void set_annotations(const std::shared_ptr<const DepSpecAnnotations> &);
649 
650  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
651  };
652 
653  /**
654  * A LabelsDepSpec represents a labels entry using a particular visitor
655  * types class.
656  *
657  * \see DependencyLabelsDepSpec
658  * \see URILabelsDepSpec
659  * \since 0.26
660  * \ingroup g_dep_spec
661  * \nosubgrouping
662  */
663  template <typename Labels_>
665  public DepSpec
666  {
667  private:
668  Pimp<LabelsDepSpec> _imp;
669 
670  public:
671  ///\name Basic operations
672  ///\{
673 
674  LabelsDepSpec();
675  ~LabelsDepSpec();
676 
677  ///\}
678 
679  ///\name Contained labels
680  ///\{
681 
682  void add_label(const std::shared_ptr<const Labels_> &);
683 
684  struct ConstIteratorTag;
685  typedef WrappedForwardIterator<ConstIteratorTag,
686  const std::shared_ptr<const Labels_> > ConstIterator;
687 
688  ConstIterator begin() const PALUDIS_ATTRIBUTE((warn_unused_result));
689  ConstIterator end() const PALUDIS_ATTRIBUTE((warn_unused_result));
690 
691  ///\}
692 
693  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
694  };
695 
697  public StringDepSpec
698  {
699  public:
700  ///\name Basic operations
701  ///\{
702 
703  PlainTextLabelDepSpec(const std::string &);
705 
706  ///\}
707 
708  virtual std::shared_ptr<DepSpec> clone() const PALUDIS_ATTRIBUTE((warn_unused_result));
709 
710  const std::string label() const PALUDIS_ATTRIBUTE((warn_unused_result));
711  };
712 
713  extern template class PALUDIS_VISIBLE WrappedForwardIterator<DependenciesLabelsDepSpec::ConstIteratorTag,
714  const std::shared_ptr<const DependenciesLabel> >;
715  extern template class PALUDIS_VISIBLE WrappedForwardIterator<URILabelsDepSpec::ConstIteratorTag,
716  const std::shared_ptr<const URILabel> >;
717 
718 }
719 
720 #endif
Definition: named_value-fwd.hh:29
Definition: pimp.hh:51
Definition: dep_spec.hh:158
Definition: about_metadata-fwd.hh:23
Definition: dep_spec.hh:529
Definition: dep_spec.hh:269
Definition: dep_spec.hh:477
Definition: dep_spec.hh:570
Definition: dep_spec-fwd.hh:50
Definition: changed_choices.hh:35
Definition: dep_spec.hh:611
Definition: dep_spec.hh:322
Definition: dep_spec.hh:179
Definition: exception.hh:74
Definition: dep_spec.hh:345
Definition: environment.hh:200
std::ostream & operator<<(std::ostream &, const WantPhase &) PALUDIS_VISIBLE
Definition: dep_spec.hh:116
VersionRequirementsMode
Definition: version_requirements-fwd.hh:54
Definition: dep_spec.hh:696
Definition: wrapped_forward_iterator-fwd.hh:26
Definition: wrapped_value-fwd.hh:29
Definition: dep_spec.hh:591
Definition: dep_spec.hh:310
Definition: dep_spec.hh:504
Definition: dep_spec.hh:457
Definition: dep_spec.hh:75
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:53
Definition: dep_spec.hh:201
#define PALUDIS_VISIBLE
Definition: attributes.hh:59
Definition: dep_spec.hh:137