paludis  Version 1.4.2
choice.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 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_CHOICE_HH
21 #define PALUDIS_GUARD_PALUDIS_CHOICE_HH 1
22 
23 #include <paludis/choice-fwd.hh>
24 #include <paludis/permitted_choice_value_parameter_values-fwd.hh>
26 #include <paludis/util/wrapped_forward_iterator.hh>
27 #include <paludis/util/pimp.hh>
29 #include <paludis/util/named_value.hh>
30 #include <paludis/util/wrapped_value.hh>
31 #include <paludis/util/set.hh>
32 #include <paludis/util/wrapped_forward_iterator.hh>
33 #include <paludis/util/wrapped_output_iterator.hh>
34 #include <memory>
35 #include <string>
36 
37 /** \file
38  * Declarations for choice-related classes.
39  *
40  * \ingroup g_choices
41  * \since 0.32
42  *
43  * \section Examples
44  *
45  * - None at this time.
46  */
47 
48 namespace paludis
49 {
50  namespace n
51  {
52  typedef Name<struct name_consider_added_or_changed> consider_added_or_changed;
53  typedef Name<struct name_contains_every_value> contains_every_value;
54  typedef Name<struct name_hidden> hidden;
55  typedef Name<struct name_human_name> human_name;
56  typedef Name<struct name_prefix> prefix;
57  typedef Name<struct name_raw_name> raw_name;
58  typedef Name<struct name_show_with_no_prefix> show_with_no_prefix;
59  }
60 
61  /**
62  * Thrown if a ChoicePrefixName is given an invalid value.
63  *
64  * \since 0.32
65  * \ingroup g_choices
66  * \ingroup g_exceptions
67  */
69  public NameError
70  {
71  public:
72  ChoicePrefixNameError(const std::string &) throw ();
73  };
74 
75  /**
76  * Thrown if a ChoiceNameWithPrefix is given an invalid value.
77  *
78  * \since 0.32
79  * \ingroup g_choices
80  * \ingroup g_exceptions
81  */
83  public NameError
84  {
85  public:
86  ChoiceNameWithPrefixError(const std::string &) throw ();
87  };
88 
89  /**
90  * Thrown if a UnprefixedChoiceName is given an invalid value.
91  *
92  * \since 0.32
93  * \ingroup g_choices
94  * \ingroup g_exceptions
95  */
97  public NameError
98  {
99  public:
100  UnprefixedChoiceNameError(const std::string &) throw ();
101  };
102 
103  template <>
104  struct WrappedValueTraits<ChoicePrefixNameTag>
105  {
106  typedef std::string UnderlyingType;
107  typedef void ValidationParamsType;
109 
110  static bool validate(const std::string &) PALUDIS_ATTRIBUTE((warn_unused_result));
111  };
112 
114 
115  template <>
117  {
118  typedef std::string UnderlyingType;
119  typedef void ValidationParamsType;
121 
122  static bool validate(const std::string &) PALUDIS_ATTRIBUTE((warn_unused_result));
123  };
124 
126 
127  template <>
129  {
130  typedef std::string UnderlyingType;
131  typedef void ValidationParamsType;
133 
134  static bool validate(const std::string &) PALUDIS_ATTRIBUTE((warn_unused_result));
135  };
136 
138 
139  /**
140  * Choices holds a collection of configurable values for a PackageID.
141  *
142  * A PackageID may have a choices_key holding a Choices object. This Choices object
143  * will hold a number of Choice objects. Examples of things held by Choice objects for
144  * ebuilds include USE, USE_EXPAND values (linguas, video_cards and so on), ARCH and
145  * build_options.
146  *
147  * \ingroup g_choices
148  * \since 0.32
149  */
151  {
152  private:
153  Pimp<Choices> _imp;
154 
155  public:
156  ///\name Basic operations
157  ///\{
158 
159  Choices();
160  ~Choices();
161 
162  ///\}
163 
164  /**
165  * Add a new Choice to our collection.
166  */
167  void add(const std::shared_ptr<const Choice> &);
168 
169  ///\name Iterate over Choice children
170  ///\{
171 
172  struct ConstIteratorTag;
174  ConstIterator begin() const PALUDIS_ATTRIBUTE((warn_unused_result));
175  ConstIterator end() const PALUDIS_ATTRIBUTE((warn_unused_result));
176 
177  ///\since 0.44
178  ConstIterator find(const ChoicePrefixName &) const PALUDIS_ATTRIBUTE((warn_unused_result));
179 
180  ///\}
181 
182  /**
183  * Find a ChoiceValue that has a particular prefix and name.
184  *
185  * Returns a zero pointer for no match.
186  *
187  * This is a convenient way of getting a particular use flag's details. Calling this
188  * method with, say, "nls" or "ruby" will get the value for that flag without having
189  * to hunt around in all the subkeys manually. Prefixes work too, e.g. "linguas_en" for
190  * 0-based EAPIs or "linguas:en" for exheres EAPIs.
191  */
192  const std::shared_ptr<const ChoiceValue> find_by_name_with_prefix(
193  const ChoiceNameWithPrefix &) const PALUDIS_ATTRIBUTE((warn_unused_result));
194 
195  /**
196  * Do we have a Choice subkey with contains_every_value true and a prefix matching
197  * this name?
198  *
199  * 0-based EAPIs don't require things like userland_GNU in IUSE. So if you're looking
200  * for a flag and don't find it, check this method before issuing a QA notice.
201  */
202  bool has_matching_contains_every_value_prefix(const ChoiceNameWithPrefix &) const PALUDIS_ATTRIBUTE((warn_unused_result));
203  };
204 
205  /**
206  * Named parameters for Choice::Choice.
207  *
208  * \since 0.38
209  * \ingroup g_choices
210  */
212  {
213  NamedValue<n::consider_added_or_changed, bool> consider_added_or_changed;
214  NamedValue<n::contains_every_value, bool> contains_every_value;
219  NamedValue<n::show_with_no_prefix, bool> show_with_no_prefix;
220  };
221 
222  /**
223  * An individual choice in a Choices collection.
224  *
225  * Examples of a choice include USE, individual USE_EXPAND values (linguas, video_cards etc)
226  * and build_options.
227  *
228  * \ingroup g_choices
229  * \since 0.32
230  */
232  {
233  private:
234  Pimp<Choice> _imp;
235 
236  public:
237  ///\name Basic operations
238  ///\{
239 
240  ///\since 0.38
241  Choice(const ChoiceParams &);
242  ~Choice();
243 
244  ///\}
245 
246  /**
247  * Add a new ChoiceValue.
248  */
249  void add(const std::shared_ptr<const ChoiceValue> &);
250 
251  ///\name Properties
252  ///\{
253 
254  /**
255  * Our raw name, for example 'USE' or 'LINGUAS'.
256  */
257  const std::string raw_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
258 
259  /**
260  * A human-readable name (often the same as raw_name).
261  */
262  const std::string human_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
263 
264  /**
265  * The prefix for our ChoiceValue children.
266  *
267  * An empty string for USE and ARCH, 'linguas' for LINGUAS etc.
268  */
269  const ChoicePrefixName prefix() const PALUDIS_ATTRIBUTE((warn_unused_result));
270 
271  /**
272  * If true, pretend that we contain every possible value and that any value not listed
273  * as a child exists and is not enabled.
274  *
275  * For pesky 0-based EAPIs that don't require things like userland_GNU in IUSE, and that
276  * don't have a comprehensive list of possible values.
277  */
278  bool contains_every_value() const PALUDIS_ATTRIBUTE((warn_unused_result));
279 
280  /**
281  * If true, this option should not usually be shown visually to a user.
282  */
283  bool hidden() const PALUDIS_ATTRIBUTE((warn_unused_result));
284 
285  /**
286  * If true, hint that we're better not displaying our prefix to the user.
287  *
288  * This is used by --pretend --install and --query to avoid showing a Use:
289  * prefix before a list of use flag names.
290  */
291  bool show_with_no_prefix() const PALUDIS_ATTRIBUTE((warn_unused_result));
292 
293  /**
294  * If false, do not consider flags in this section for 'added' or 'changed'
295  * detection.
296  *
297  * Used by build_options.
298  */
299  bool consider_added_or_changed() const PALUDIS_ATTRIBUTE((warn_unused_result));
300 
301  ///\}
302 
303  ///\name Iterate over ChoiceValue children
304  ///\{
305 
306  struct ConstIteratorTag;
308  ConstIterator begin() const PALUDIS_ATTRIBUTE((warn_unused_result));
309  ConstIterator end() const PALUDIS_ATTRIBUTE((warn_unused_result));
310 
311  ///\}
312  };
313 
314  /**
315  * An individial Value in a ChoiceValue.
316  *
317  * For example, the 'nls' flag in 'USE'.
318  *
319  * Some choice values have an associated parameter. For example,
320  * build_options:jobs=4.
321  *
322  * \ingroup g_choices
323  * \since 0.32
324  */
326  {
327  public:
328  ///\name Basic operations
329  ///\{
330 
331  virtual ~ChoiceValue() = 0;
332 
333  ///\}
334 
335  ///\name Properties
336  ///\{
337 
338  /**
339  * Our name, without an prefix (for example, 'nls' or 'en').
340  */
341  virtual const UnprefixedChoiceName unprefixed_name() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
342 
343  /**
344  * Our name, with prefix if there is one (for example, 'nls' or 'linguas_en').
345  */
346  virtual const ChoiceNameWithPrefix name_with_prefix() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
347 
348  /**
349  * Is this flag enabled?
350  */
351  virtual bool enabled() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
352 
353  /**
354  * Would this flag be enabled by default (i.e. before
355  * considering any overrides from the Environment)?
356  */
357  virtual bool enabled_by_default() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
358 
359  /**
360  * Does this flag have to be explicitly accepted when doing matching?
361  */
362  virtual bool presumed() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
363 
364  /**
365  * Is this flag locked (forced or masked)?
366  */
367  virtual bool locked() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
368 
369  /**
370  * The flag's description, or an empty string.
371  */
372  virtual const std::string description() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
373 
374  /**
375  * The origin of this choice.
376  *
377  * \since 0.66
378  *
379  * Use this to avoid showing things like LINGUAS values that aren't listed
380  * in IUSE but that end up as a ChoiceValue anyway.
381  */
382  virtual ChoiceOrigin origin() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
383 
384  /**
385  * This flag's parameter, or an empty string if it doesn't have one.
386  *
387  * \since 0.40
388  */
389  virtual const std::string parameter() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
390 
391  /**
392  * Permitted values for this flag's parameter, or null if there is no parameter.
393  *
394  * \since 0.59
395  */
396  virtual const std::shared_ptr<const PermittedChoiceValueParameterValues> permitted_parameter_values() const
397  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
398 
399  ///\}
400  };
401 
402  extern template class Pimp<Choices>;
403  extern template class Pimp<Choice>;
404 
405  extern template class PALUDIS_VISIBLE Set<UnprefixedChoiceName>;
408 
411 }
412 
413 #endif
Definition: pimp.hh:51
Definition: exception.hh:171
Definition: wrapped_output_iterator-fwd.hh:26
Definition: choice.hh:231
Definition: wrapped_value-fwd.hh:32
Definition: choice.hh:82
Definition: choice.hh:96
Definition: set-fwd.hh:35
Definition: wrapped_forward_iterator-fwd.hh:26
Definition: wrapped_value-fwd.hh:29
Definition: choice.hh:68
Definition: choice.hh:211
Definition: choice.hh:150
ChoiceOrigin
Definition: choice-fwd.hh:14
Definition: choice.hh:325
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:64
#define PALUDIS_VISIBLE
Definition: attributes.hh:71