choice.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2008, 2009 Ciaran McCreesh
00005  *
00006  * This file is part of the Paludis package manager. Paludis is free software;
00007  * you can redistribute it and/or modify it under the terms of the GNU General
00008  * Public License version 2, as published by the Free Software Foundation.
00009  *
00010  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
00011  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00012  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00013  * details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
00017  * Place, Suite 330, Boston, MA  02111-1307  USA
00018  */
00019 
00020 #ifndef PALUDIS_GUARD_PALUDIS_CHOICE_HH
00021 #define PALUDIS_GUARD_PALUDIS_CHOICE_HH 1
00022 
00023 #include <paludis/choice-fwd.hh>
00024 #include <paludis/util/attributes.hh>
00025 #include <paludis/util/wrapped_forward_iterator-fwd.hh>
00026 #include <paludis/util/private_implementation_pattern.hh>
00027 #include <paludis/util/exception.hh>
00028 #include <paludis/util/named_value.hh>
00029 #include <paludis/util/validated.hh>
00030 #include <tr1/memory>
00031 #include <string>
00032 
00033 /** \file
00034  * Declarations for choice-related classes.
00035  *
00036  * \ingroup g_choices
00037  * \since 0.32
00038  *
00039  * \section Examples
00040  *
00041  * - None at this time.
00042  */
00043 
00044 namespace paludis
00045 {
00046     namespace n
00047     {
00048         struct consider_added_or_changed;
00049         struct contains_every_value;
00050         struct hidden;
00051         struct human_name;
00052         struct prefix;
00053         struct raw_name;
00054         struct show_with_no_prefix;
00055     }
00056 
00057     /**
00058      * Thrown if a ChoicePrefixName is given an invalid value.
00059      *
00060      * \since 0.32
00061      * \ingroup g_choices
00062      * \ingroup g_exceptions
00063      */
00064     class PALUDIS_VISIBLE ChoicePrefixNameError :
00065         public NameError
00066     {
00067         public:
00068             ChoicePrefixNameError(const std::string &) throw ();
00069     };
00070 
00071     /**
00072      * Thrown if a ChoiceNameWithPrefix is given an invalid value.
00073      *
00074      * \since 0.32
00075      * \ingroup g_choices
00076      * \ingroup g_exceptions
00077      */
00078     class PALUDIS_VISIBLE ChoiceNameWithPrefixError :
00079         public NameError
00080     {
00081         public:
00082             ChoiceNameWithPrefixError(const std::string &) throw ();
00083     };
00084 
00085     /**
00086      * Thrown if a UnprefixedChoiceName is given an invalid value.
00087      *
00088      * \since 0.32
00089      * \ingroup g_choices
00090      * \ingroup g_exceptions
00091      */
00092     class PALUDIS_VISIBLE UnprefixedChoiceNameError :
00093         public NameError
00094     {
00095         public:
00096             UnprefixedChoiceNameError(const std::string &) throw ();
00097     };
00098 
00099     /**
00100      * A ChoicePrefixNameValidator handles validation for ChoicePrefixName.
00101      *
00102      * \ingroup g_choices
00103      * \since 0.32
00104      */
00105     struct PALUDIS_VISIBLE ChoicePrefixNameValidator :
00106         private InstantiationPolicy<ChoicePrefixNameValidator, instantiation_method::NonInstantiableTag>
00107     {
00108         /**
00109          * If the parameter is not a valid value for a ChoicePrefixName, throw
00110          * a ChoicePrefixNameError.
00111          */
00112         static void validate(const std::string &);
00113     };
00114 
00115     /**
00116      * A ChoiceNameWithPrefixValidator handles validation for ChoicePrefixName.
00117      *
00118      * \ingroup g_choices
00119      * \since 0.32
00120      */
00121     struct PALUDIS_VISIBLE ChoiceNameWithPrefixValidator :
00122         private InstantiationPolicy<ChoiceNameWithPrefixValidator, instantiation_method::NonInstantiableTag>
00123     {
00124         /**
00125          * If the parameter is not a valid value for a ChoiceNameWithPrefix, throw
00126          * a ChoiceNameWithPrefixError.
00127          */
00128         static void validate(const std::string &);
00129     };
00130 
00131     /**
00132      * A UnprefixedChoiceNameValidator handles validation for ChoicePrefixName.
00133      *
00134      * \ingroup g_choices
00135      * \since 0.32
00136      */
00137     struct PALUDIS_VISIBLE UnprefixedChoiceNameValidator :
00138         private InstantiationPolicy<UnprefixedChoiceNameValidator, instantiation_method::NonInstantiableTag>
00139     {
00140         /**
00141          * If the parameter is not a valid value for a UnprefixedChoiceName, throw
00142          * a UnprefixedChoiceNameError.
00143          */
00144         static void validate(const std::string &);
00145     };
00146 
00147     /**
00148      * Choices holds a collection of configurable values for a PackageID.
00149      *
00150      * A PackageID may have a choices_key holding a Choices object. This Choices object
00151      * will hold a number of Choice objects. Examples of things held by Choice objects for
00152      * ebuilds include USE, USE_EXPAND values (linguas, video_cards and so on), ARCH and
00153      * build_options.
00154      *
00155      * \ingroup g_choices
00156      * \since 0.32
00157      */
00158     class PALUDIS_VISIBLE Choices :
00159         private PrivateImplementationPattern<Choices>
00160     {
00161         public:
00162             ///\name Basic operations
00163             ///\{
00164 
00165             Choices();
00166             ~Choices();
00167 
00168             ///\}
00169 
00170             /**
00171              * Add a new Choice to our collection.
00172              */
00173             void add(const std::tr1::shared_ptr<const Choice> &);
00174 
00175             ///\name Iterate over Choice children
00176             ///\{
00177 
00178             struct ConstIteratorTag;
00179             typedef WrappedForwardIterator<ConstIteratorTag, const std::tr1::shared_ptr<const Choice> > ConstIterator;
00180             ConstIterator begin() const PALUDIS_ATTRIBUTE((warn_unused_result));
00181             ConstIterator end() const PALUDIS_ATTRIBUTE((warn_unused_result));
00182 
00183             ///\}
00184 
00185             /**
00186              * Find a ChoiceValue that has a particular prefix and name.
00187              *
00188              * Returns a zero pointer for no match.
00189              *
00190              * This is a convenient way of getting a particular use flag's details. Calling this
00191              * method with, say, "nls" or "ruby" will get the value for that flag without having
00192              * to hunt around in all the subkeys manually. Prefixes work too, e.g. "linguas_en" for
00193              * 0-based EAPIs or "linguas:en" for exheres EAPIs.
00194              */
00195             const std::tr1::shared_ptr<const ChoiceValue> find_by_name_with_prefix(
00196                     const ChoiceNameWithPrefix &) const PALUDIS_ATTRIBUTE((warn_unused_result));
00197 
00198             /**
00199              * Do we have a Choice subkey with contains_every_value true and a prefix matching
00200              * this name?
00201              *
00202              * 0-based EAPIs don't require things like userland_GNU in IUSE. So if you're looking
00203              * for a flag and don't find it, check this method before issuing a QA notice.
00204              */
00205             bool has_matching_contains_every_value_prefix(const ChoiceNameWithPrefix &) const PALUDIS_ATTRIBUTE((warn_unused_result));
00206     };
00207 
00208     /**
00209      * Named parameters for Choice::Choice.
00210      *
00211      * \since 0.38
00212      * \ingroup g_choices
00213      */
00214     struct ChoiceParams
00215     {
00216         NamedValue<n::consider_added_or_changed, bool> consider_added_or_changed;
00217         NamedValue<n::contains_every_value, bool> contains_every_value;
00218         NamedValue<n::hidden, bool> hidden;
00219         NamedValue<n::human_name, std::string> human_name;
00220         NamedValue<n::prefix, ChoicePrefixName> prefix;
00221         NamedValue<n::raw_name, std::string> raw_name;
00222         NamedValue<n::show_with_no_prefix, bool> show_with_no_prefix;
00223     };
00224 
00225     /**
00226      * An individual choice in a Choices collection.
00227      *
00228      * Examples of a choice include USE, individual USE_EXPAND values (linguas, video_cards etc)
00229      * and build_options.
00230      *
00231      * \ingroup g_choices
00232      * \since 0.32
00233      */
00234     class PALUDIS_VISIBLE Choice :
00235         private PrivateImplementationPattern<Choice>
00236     {
00237         public:
00238             ///\name Basic operations
00239             ///\{
00240 
00241             ///\since 0.38
00242             Choice(const ChoiceParams &);
00243             ~Choice();
00244 
00245             ///\}
00246 
00247             /**
00248              * Add a new ChoiceValue.
00249              */
00250             void add(const std::tr1::shared_ptr<const ChoiceValue> &);
00251 
00252             ///\name Properties
00253             ///\{
00254 
00255             /**
00256              * Our raw name, for example 'USE' or 'LINGUAS'.
00257              */
00258             const std::string raw_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
00259 
00260             /**
00261              * A human-readable name (often the same as raw_name).
00262              */
00263             const std::string human_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
00264 
00265             /**
00266              * The prefix for our ChoiceValue children.
00267              *
00268              * An empty string for USE and ARCH, 'linguas' for LINGUAS etc.
00269              */
00270             const ChoicePrefixName prefix() const PALUDIS_ATTRIBUTE((warn_unused_result));
00271 
00272             /**
00273              * If true, pretend that we contain every possible value and that any value not listed
00274              * as a child exists and is not enabled.
00275              *
00276              * For pesky 0-based EAPIs that don't require things like userland_GNU in IUSE, and that
00277              * don't have a comprehensive list of possible values.
00278              */
00279             bool contains_every_value() const PALUDIS_ATTRIBUTE((warn_unused_result));
00280 
00281             /**
00282              * If true, this option should not usually be shown visually to a user.
00283              */
00284             bool hidden() const PALUDIS_ATTRIBUTE((warn_unused_result));
00285 
00286             /**
00287              * If true, hint that we're better not displaying our prefix to the user.
00288              *
00289              * This is used by --pretend --install and --query to avoid showing a Use:
00290              * prefix before a list of use flag names.
00291              */
00292             bool show_with_no_prefix() const PALUDIS_ATTRIBUTE((warn_unused_result));
00293 
00294             /**
00295              * If false, do not consider flags in this section for 'added' or 'changed'
00296              * detection.
00297              *
00298              * Used by build_options.
00299              */
00300             bool consider_added_or_changed() const PALUDIS_ATTRIBUTE((warn_unused_result));
00301 
00302             ///\}
00303 
00304             ///\name Iterate over ChoiceValue children
00305             ///\{
00306 
00307             struct ConstIteratorTag;
00308             typedef WrappedForwardIterator<ConstIteratorTag, const std::tr1::shared_ptr<const ChoiceValue> > ConstIterator;
00309             ConstIterator begin() const PALUDIS_ATTRIBUTE((warn_unused_result));
00310             ConstIterator end() const PALUDIS_ATTRIBUTE((warn_unused_result));
00311 
00312             ///\}
00313     };
00314 
00315     /**
00316      * An individial Value in a ChoiceValue.
00317      *
00318      * For example, the 'nls' flag in 'USE'.
00319      *
00320      * Some choice values have an associated parameter. For example,
00321      * build_options:jobs=4.
00322      *
00323      * \ingroup g_choices
00324      * \since 0.32
00325      */
00326     class PALUDIS_VISIBLE ChoiceValue
00327     {
00328         public:
00329             ///\name Basic operations
00330             ///\{
00331 
00332             virtual ~ChoiceValue() = 0;
00333 
00334             ///\}
00335 
00336             ///\name Properties
00337             ///\{
00338 
00339             /**
00340              * Our name, without an prefix (for example, 'nls' or 'en').
00341              */
00342             virtual const UnprefixedChoiceName unprefixed_name() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00343 
00344             /**
00345              * Our name, with prefix if there is one (for example, 'nls' or 'linguas_en').
00346              */
00347             virtual const ChoiceNameWithPrefix name_with_prefix() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00348 
00349             /**
00350              * Is this flag enabled?
00351              */
00352             virtual bool enabled() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00353 
00354             /**
00355              * Would this flag be enabled by default (i.e. before
00356              * considering any overrides from the Environment)?
00357              */
00358             virtual bool enabled_by_default() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00359 
00360             /**
00361              * Is this flag locked (forced or masked)?
00362              */
00363             virtual bool locked() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00364 
00365             /**
00366              * The flag's description, or an empty string.
00367              */
00368             virtual const std::string description() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00369 
00370             /**
00371              * Is this flag explicitly listed?
00372              *
00373              * Use this to avoid showing things like LINGUAS values that aren't listed
00374              * in IUSE but that end up as a ChoiceValue anyway.
00375              */
00376             virtual bool explicitly_listed() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00377 
00378             /**
00379              * This flag's parameter, or an empty string if it doesn't have one.
00380              *
00381              * \since 0.40
00382              */
00383             virtual const std::string parameter() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00384 
00385             ///\}
00386     };
00387 
00388 #ifdef PALUDIS_HAVE_EXTERN_TEMPLATE
00389     extern template class PrivateImplementationPattern<Choices>;
00390     extern template class PrivateImplementationPattern<Choice>;
00391 #endif
00392 }
00393 
00394 #endif

Generated on Mon Sep 21 10:36:08 2009 for paludis by  doxygen 1.5.4