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