paludis  Version 2.6.0
selection.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 2008, 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_SELECTION_HH
21 #define PALUDIS_GUARD_PALUDIS_SELECTION_HH 1
22 
23 #include <paludis/selection-fwd.hh>
24 #include <paludis/selection_handler-fwd.hh>
26 #include <paludis/filter-fwd.hh>
27 #include <paludis/generator-fwd.hh>
28 #include <paludis/dep_spec-fwd.hh>
29 #include <paludis/util/pimp.hh>
31 #include <paludis/name-fwd.hh>
34 
35 /** \file
36  * Declarations for the Selection class.
37  *
38  * \ingroup g_selections
39  *
40  * \section Examples
41  *
42  * - \ref example_selection.cc "example_selection.cc"
43  */
44 
45 namespace paludis
46 {
47  /**
48  * Thrown if selection::RequireExactlyOne does not get exactly one result.
49  *
50  * \ingroup g_selections
51  */
53  public Exception
54  {
55  public:
56  DidNotGetExactlyOneError(const std::string &,
57  const std::shared_ptr<const PackageIDSet> &) noexcept;
58  };
59 
60  /**
61  * A Selection subclass is passed to Environment::operator[] to obtain a set
62  * of PackageID instances with given properties.
63  *
64  * Most Selection subclasses take a FilteredGenerator as a constructor
65  * parameter that specifies the required properties; the Selection itself is
66  * merely responsible for determining the format of the results.
67  *
68  * \ingroup g_selections
69  */
71  {
72  private:
73  Pimp<Selection> _imp;
74 
75  protected:
76  Selection(const std::shared_ptr<const SelectionHandler> &);
77 
78  public:
79  ///\name Basic operations
80  ///\{
81 
82  /**
83  * Selection subclasses can be copied to a Selection without
84  * destroying information.
85  */
86  Selection(const Selection &);
87 
88  ~Selection();
89  Selection & operator= (const Selection &);
90 
91  ///\}
92 
93  /**
94  * Return a string representation of our selection query.
95  */
96  std::string as_string() const PALUDIS_ATTRIBUTE((warn_unused_result));
97 
98  /**
99  * For use by Environment, not to be called directly.
100  */
101  std::shared_ptr<PackageIDSequence> perform_select(const Environment * const) const
102  PALUDIS_ATTRIBUTE((warn_unused_result));
103  };
104 
105  namespace selection
106  {
107  /**
108  * Select some arbitrary version with the specified properties.
109  *
110  * Mostly used if you want to find out whether a PackageID with a
111  * particular property exists, but do not want to do anything in
112  * particular with the results.
113  *
114  * \ingroup g_selections
115  */
117  public Selection
118  {
119  public:
120  ///\name Basic operations
121  ///\{
122 
124 
125  ///\}
126  };
127 
128  /**
129  * Return only the best version of each matching package with the
130  * specified properties.
131  *
132  * \ingroup g_selections
133  */
135  public Selection
136  {
137  public:
138  ///\name Basic operations
139  ///\{
140 
142 
143  ///\}
144  };
145 
146  /**
147  * Return the best version in each slot of each matching package with
148  * the specified properties.
149  *
150  * \ingroup g_selections
151  */
153  public Selection
154  {
155  public:
156  ///\name Basic operations
157  ///\{
158 
160 
161  ///\}
162  };
163 
164  /**
165  * Return all versions with the specified properties, sorted from worst
166  * to best.
167  *
168  * \ingroup g_selections
169  */
171  public Selection
172  {
173  public:
174  ///\name Basic operations
175  ///\{
176 
178 
179  ///\}
180  };
181 
182  /**
183  * Return all versions with the specified properties, sorted from worst
184  * to best, but with like slots grouped together.
185  *
186  * \ingroup g_selections
187  */
189  public Selection
190  {
191  public:
192  ///\name Basic operations
193  ///\{
194 
196 
197  ///\}
198  };
199 
200  /**
201  * Return all versions with the specified properties, in no particular
202  * order.
203  *
204  * \ingroup g_selections
205  */
207  public Selection
208  {
209  public:
210  ///\name Basic operations
211  ///\{
212 
214 
215  ///\}
216  };
217 
218  /**
219  * Return the single version with the specified properties.
220  *
221  * If there is not exactly one version, throws DidNotGetExactlyOneError.
222  *
223  * \ingroup g_selections
224  */
226  public Selection
227  {
228  public:
229  ///\name Basic operations
230  ///\{
231 
233 
234  ///\}
235  };
236  }
237 
238  extern template class Pimp<Selection>;
239 }
240 
241 #endif
Definition: pimp.hh:51
Definition: selection.hh:225
Definition: about_metadata-fwd.hh:23
Definition: selection.hh:116
Definition: selection.hh:52
Definition: exception.hh:74
Definition: environment.hh:200
Definition: filtered_generator.hh:48
Definition: selection.hh:152
Definition: selection.hh:134
Definition: selection.hh:170
Definition: selection.hh:206
Definition: selection.hh:70
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:53
#define PALUDIS_VISIBLE
Definition: attributes.hh:59