metadata_key.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2007, 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_METADATA_KEY_HH
00021 #define PALUDIS_GUARD_PALUDIS_METADATA_KEY_HH 1
00022 
00023 #include <paludis/metadata_key-fwd.hh>
00024 #include <paludis/mask-fwd.hh>
00025 #include <paludis/package_id-fwd.hh>
00026 #include <paludis/name-fwd.hh>
00027 #include <paludis/dep_spec-fwd.hh>
00028 #include <paludis/spec_tree.hh>
00029 #include <paludis/contents-fwd.hh>
00030 #include <paludis/repository-fwd.hh>
00031 #include <paludis/formatter-fwd.hh>
00032 #include <paludis/metadata_key_holder.hh>
00033 #include <paludis/choice-fwd.hh>
00034 #include <paludis/util/fs_entry-fwd.hh>
00035 #include <paludis/util/attributes.hh>
00036 #include <paludis/util/instantiation_policy.hh>
00037 #include <paludis/util/remove_shared_ptr.hh>
00038 #include <paludis/util/simple_visitor.hh>
00039 #include <paludis/util/type_list.hh>
00040 #include <tr1/type_traits>
00041 #include <string>
00042 
00043 /** \file
00044  * Declarations for metadata key classes.
00045  *
00046  * \ingroup g_metadata_key
00047  *
00048  * \section Examples
00049  *
00050  * - \ref example_metadata_key.cc "example_metadata_key.cc" (for metadata keys)
00051  */
00052 
00053 namespace paludis
00054 {
00055     /**
00056      * A MetadataKey is a generic key that contains a particular piece of
00057      * information about a PackageID or Repository instance.
00058      *
00059      * A basic MetadataKey has:
00060      *
00061      * - A raw name. This is in a repository-defined format designed to closely
00062      *   represent the internal name. For example, ebuilds and VDB IDs use
00063      *   raw names like 'DESCRIPTION' and 'KEYWORDS', whereas CRAN uses names
00064      *   like 'Title' and 'BundleDescription'. The raw name is unique in a
00065      *   PackageID or Repository.
00066      *
00067      * - A human name. This is the name that should be used when outputting
00068      *   normally for a human to read.
00069      *
00070      * - A MetadataKeyType. This is a hint to clients as to whether the key
00071      *   should be displayed when outputting information about a package ID
00072      *   or Repository.
00073      *
00074      * Subclasses provide additional information, including the 'value' of the
00075      * key. A ConstVisitor using MetadataKeyVisitorTypes can be used to get more
00076      * detail.
00077      *
00078      * The header \ref paludis/literal_metadata_key.hh "literal_metadata_key.hh"
00079      * contains various concrete implementations of MetadataKey subclasses.
00080      *
00081      * \ingroup g_metadata_key
00082      * \since 0.26
00083      * \nosubgrouping
00084      */
00085     class PALUDIS_VISIBLE MetadataKey :
00086         private InstantiationPolicy<MetadataKey, instantiation_method::NonCopyableTag>,
00087         public virtual DeclareAbstractAcceptMethods<MetadataKey, MakeTypeList<
00088                 MetadataCollectionKey<KeywordNameSet>,
00089                 MetadataCollectionKey<Set<std::string> >,
00090                 MetadataCollectionKey<Sequence<std::string> >,
00091                 MetadataCollectionKey<PackageIDSequence>,
00092                 MetadataCollectionKey<FSEntrySequence>,
00093                 MetadataSpecTreeKey<DependencySpecTree>,
00094                 MetadataSpecTreeKey<LicenseSpecTree>,
00095                 MetadataSpecTreeKey<FetchableURISpecTree>,
00096                 MetadataSpecTreeKey<SimpleURISpecTree>,
00097                 MetadataSpecTreeKey<ProvideSpecTree>,
00098                 MetadataSpecTreeKey<PlainTextSpecTree>,
00099                 MetadataValueKey<std::string>,
00100                 MetadataValueKey<long>,
00101                 MetadataValueKey<bool>,
00102                 MetadataValueKey<FSEntry>,
00103                 MetadataValueKey<SlotName>,
00104                 MetadataValueKey<std::tr1::shared_ptr<const PackageID> >,
00105                 MetadataValueKey<std::tr1::shared_ptr<const Contents> >,
00106                 MetadataValueKey<std::tr1::shared_ptr<const RepositoryMaskInfo> >,
00107                 MetadataValueKey<std::tr1::shared_ptr<const Choices> >,
00108                 MetadataTimeKey,
00109                 MetadataSectionKey
00110                 >::Type>
00111     {
00112         public:
00113             ///\name Basic operations
00114             ///\{
00115 
00116             virtual ~MetadataKey() = 0;
00117 
00118             ///\}
00119 
00120             /**
00121              * Fetch our raw name.
00122              */
00123             virtual const std::string raw_name() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00124 
00125             /**
00126              * Fetch our human name.
00127              */
00128             virtual const std::string human_name() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00129 
00130             /**
00131              * Fetch our key type.
00132              */
00133             virtual MetadataKeyType type() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00134     };
00135 
00136     /**
00137      * A MetadataSectionKey is a MetadataKey that holds a number of other
00138      * MetadataKey instances.
00139      *
00140      * \ingroup g_metadata_key
00141      * \since 0.26
00142      * \nosubgrouping
00143      */
00144     class PALUDIS_VISIBLE MetadataSectionKey :
00145         public MetadataKey,
00146         public ImplementAcceptMethods<MetadataKey, MetadataSectionKey>,
00147         public MetadataKeyHolder
00148     {
00149         public:
00150             ///\name Basic operations
00151             ///\{
00152 
00153             virtual ~MetadataSectionKey() = 0;
00154 
00155             ///\}
00156     };
00157 
00158     /**
00159      * Extra methods for MetadataValueKey with certain item types.
00160      *
00161      * \ingroup g_metadata_key
00162      * \since 0.26
00163      */
00164     template <typename C_>
00165     class ExtraMetadataValueKeyMethods
00166     {
00167     };
00168 
00169     /**
00170      * Extra methods for MetadataValueKey with long value type.
00171      *
00172      * \ingroup g_metadata_key
00173      * \since 0.26
00174      */
00175     template <>
00176     class PALUDIS_VISIBLE ExtraMetadataValueKeyMethods<long>
00177     {
00178         public:
00179             virtual ~ExtraMetadataValueKeyMethods() = 0;
00180 
00181             /**
00182              * Return a formatted version of our value.
00183              */
00184             virtual std::string pretty_print() const
00185                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00186     };
00187 
00188     /**
00189      * Extra methods for MetadataValueKey with bool value type.
00190      *
00191      * \ingroup g_metadata_key
00192      * \since 0.26
00193      */
00194     template <>
00195     class PALUDIS_VISIBLE ExtraMetadataValueKeyMethods<bool>
00196     {
00197         public:
00198             virtual ~ExtraMetadataValueKeyMethods() = 0;
00199 
00200             /**
00201              * Return a formatted version of our value.
00202              */
00203             virtual std::string pretty_print() const
00204                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00205     };
00206 
00207     /**
00208      * Extra methods for MetadataValueKey with PackageID value type.
00209      *
00210      * \ingroup g_metadata_key
00211      * \since 0.26
00212      */
00213     template <>
00214     class PALUDIS_VISIBLE ExtraMetadataValueKeyMethods<std::tr1::shared_ptr<const PackageID> >
00215     {
00216         public:
00217             virtual ~ExtraMetadataValueKeyMethods() = 0;
00218 
00219             /**
00220              * Return a formatted version of our value, using the supplied Formatter to
00221              * format the item.
00222              */
00223             virtual std::string pretty_print(const Formatter<PackageID> &) const
00224                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00225     };
00226 
00227     /**
00228      * A MetadataValueKey is a MetadataKey that holds some simple type
00229      * as its value.
00230      *
00231      * \ingroup g_metadata_key
00232      * \since 0.26
00233      * \nosubgrouping
00234      */
00235     template <typename C_>
00236     class PALUDIS_VISIBLE MetadataValueKey :
00237         public MetadataKey,
00238         public ImplementAcceptMethods<MetadataKey, MetadataValueKey<C_> >,
00239         public virtual ExtraMetadataValueKeyMethods<C_>
00240     {
00241         public:
00242             virtual ~MetadataValueKey() = 0;
00243 
00244             /**
00245              * Fetch our value.
00246              */
00247             virtual const C_ value() const
00248                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00249     };
00250 
00251     /**
00252      * A MetadataTimeKey is a MetadataKey that has a time_t as its value.
00253      *
00254      * \ingroup g_metadata_key
00255      * \since 0.26
00256      * \nosubgrouping
00257      */
00258     class PALUDIS_VISIBLE MetadataTimeKey :
00259         public MetadataKey,
00260         public ImplementAcceptMethods<MetadataKey, MetadataTimeKey>
00261     {
00262         public:
00263             virtual ~MetadataTimeKey() = 0;
00264 
00265             /**
00266              * Fetch our value.
00267              */
00268             virtual time_t value() const
00269                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00270     };
00271 
00272     /**
00273      * A MetadataCollectionKey is a MetadataKey that holds a Set of some kind of item
00274      * as its value.
00275      *
00276      * \ingroup g_metadata_key
00277      * \since 0.26
00278      * \nosubgrouping
00279      */
00280     template <typename C_>
00281     class PALUDIS_VISIBLE MetadataCollectionKey :
00282         public MetadataKey,
00283         public ImplementAcceptMethods<MetadataKey, MetadataCollectionKey<C_> >
00284     {
00285         public:
00286             virtual ~MetadataCollectionKey() = 0;
00287 
00288             /**
00289              * Fetch our value.
00290              */
00291             virtual const std::tr1::shared_ptr<const C_> value() const
00292                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00293 
00294             /**
00295              * Return a single-line formatted version of our value, using the
00296              * supplied Formatter to format individual items.
00297              */
00298             virtual std::string pretty_print_flat(const Formatter<
00299                     typename std::tr1::remove_const<typename RemoveSharedPtr<typename C_::value_type>::Type>::type> &) const
00300                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00301     };
00302 
00303     /**
00304      * A MetadataSpecTreeKey<> is a MetadataKey that holds a spec tree of some
00305      * kind as its value.
00306      *
00307      * \ingroup g_metadata_key
00308      * \since 0.26
00309      * \nosubgrouping
00310      */
00311     template <typename C_>
00312     class PALUDIS_VISIBLE MetadataSpecTreeKey :
00313         public MetadataKey,
00314         public ImplementAcceptMethods<MetadataKey, MetadataSpecTreeKey<C_> >
00315     {
00316         public:
00317             virtual ~MetadataSpecTreeKey() = 0;
00318 
00319             /**
00320              * Fetch our value.
00321              */
00322             virtual const std::tr1::shared_ptr<const C_> value() const
00323                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00324 
00325             /**
00326              * Return a multiline-line indented and formatted version of our
00327              * value, using the supplied Formatter to format individual items.
00328              */
00329             virtual std::string pretty_print(const typename C_::ItemFormatter &) const
00330                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00331 
00332             /**
00333              * Return a single-line formatted version of our value, using the
00334              * supplied Formatter to format individual items.
00335              */
00336             virtual std::string pretty_print_flat(const typename C_::ItemFormatter &) const
00337                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00338     };
00339 
00340     /**
00341      * A MetadataSpecTreeKey<FetchableURISpecTree> is a MetadataKey that holds
00342      * a FetchableURISpecTree as its value.
00343      *
00344      * This specialisation of MetadataSpecTreeKey provides an additional
00345      * initial_label method.
00346      *
00347      * \ingroup g_metadata_key
00348      * \since 0.26
00349      * \nosubgrouping
00350      */
00351     template <>
00352     class PALUDIS_VISIBLE MetadataSpecTreeKey<FetchableURISpecTree> :
00353         public MetadataKey,
00354         public ImplementAcceptMethods<MetadataKey, MetadataSpecTreeKey<FetchableURISpecTree> >
00355     {
00356         public:
00357             virtual ~MetadataSpecTreeKey() = 0;
00358 
00359             /**
00360              * Fetch our value.
00361              */
00362             virtual const std::tr1::shared_ptr<const FetchableURISpecTree> value() const
00363                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00364 
00365             /**
00366              * Return a multiline-line indented and formatted version of our
00367              * value, using the supplied Formatter to format individual items.
00368              */
00369             virtual std::string pretty_print(const FetchableURISpecTree::ItemFormatter &) const
00370                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00371 
00372             /**
00373              * Return a single-line formatted version of our value, using the
00374              * supplied Formatter to format individual items.
00375              */
00376             virtual std::string pretty_print_flat(const FetchableURISpecTree::ItemFormatter &) const
00377                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00378 
00379             /**
00380              * Return a URILabel that represents the initial label to use when
00381              * deciding the behaviour of individual items in the heirarchy.
00382              */
00383             virtual const std::tr1::shared_ptr<const URILabel> initial_label() const
00384                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00385     };
00386 
00387     /**
00388      * A MetadataSpecTreeKey<DependencySpecTree> is a MetadataKey that holds
00389      * a FetchableURISpecTree as its value.
00390      *
00391      * This specialisation of MetadataSpecTreeKey provides an additional
00392      * initial_label method.
00393      *
00394      * \ingroup g_metadata_key
00395      * \since 0.26
00396      * \nosubgrouping
00397      */
00398     template <>
00399     class PALUDIS_VISIBLE MetadataSpecTreeKey<DependencySpecTree> :
00400         public MetadataKey,
00401         public ImplementAcceptMethods<MetadataKey, MetadataSpecTreeKey<DependencySpecTree> >
00402     {
00403         public:
00404             virtual ~MetadataSpecTreeKey() = 0;
00405 
00406             /**
00407              * Fetch our value.
00408              */
00409             virtual const std::tr1::shared_ptr<const DependencySpecTree> value() const
00410                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00411 
00412             /**
00413              * Return a multiline-line indented and formatted version of our
00414              * value, using the supplied Formatter to format individual items.
00415              */
00416             virtual std::string pretty_print(const DependencySpecTree::ItemFormatter &) const
00417                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00418 
00419             /**
00420              * Return a single-line formatted version of our value, using the
00421              * supplied Formatter to format individual items.
00422              */
00423             virtual std::string pretty_print_flat(const DependencySpecTree::ItemFormatter &) const
00424                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00425 
00426             /**
00427              * Return a DependencyLabelSequence that represents the initial labels to use when
00428              * deciding the behaviour of individual items in the heirarchy.
00429              */
00430             virtual const std::tr1::shared_ptr<const DependencyLabelSequence> initial_labels() const
00431                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00432     };
00433 }
00434 
00435 #endif

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