paludis  Version 2.0.0
metadata_key.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 2007, 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_METADATA_KEY_HH
21 #define PALUDIS_GUARD_PALUDIS_METADATA_KEY_HH 1
22 
24 #include <paludis/mask-fwd.hh>
26 #include <paludis/name-fwd.hh>
27 #include <paludis/dep_spec-fwd.hh>
28 #include <paludis/spec_tree.hh>
30 #include <paludis/metadata_key_holder.hh>
31 #include <paludis/choice-fwd.hh>
32 #include <paludis/pretty_printer-fwd.hh>
33 #include <paludis/pretty_print_options-fwd.hh>
34 #include <paludis/maintainer-fwd.hh>
35 #include <paludis/slot-fwd.hh>
36 
37 #include <paludis/util/fs_path-fwd.hh>
39 #include <paludis/util/remove_shared_ptr.hh>
40 #include <paludis/util/visitor.hh>
41 #include <paludis/util/type_list.hh>
42 #include <paludis/util/timestamp-fwd.hh>
43 #include <paludis/util/set.hh>
44 #include <paludis/util/map.hh>
45 
46 #include <type_traits>
47 #include <string>
48 
49 /** \file
50  * Declarations for metadata key classes.
51  *
52  * \ingroup g_metadata_key
53  *
54  * \section Examples
55  *
56  * - \ref example_metadata_key.cc "example_metadata_key.cc" (for metadata keys)
57  */
58 
59 namespace paludis
60 {
61  /**
62  * A MetadataKey is a generic key that contains a particular piece of
63  * information about a PackageID or Repository instance.
64  *
65  * A basic MetadataKey has:
66  *
67  * - A raw name. This is in a repository-defined format designed to closely
68  * represent the internal name. For example, ebuilds and VDB IDs use
69  * raw names like 'DESCRIPTION' and 'KEYWORDS', whereas CRAN uses names
70  * like 'Title' and 'BundleDescription'. The raw name is unique in a
71  * PackageID or Repository.
72  *
73  * - A human name. This is the name that should be used when outputting
74  * normally for a human to read.
75  *
76  * - A MetadataKeyType. This is a hint to clients as to whether the key
77  * should be displayed when outputting information about a package ID
78  * or Repository.
79  *
80  * Subclasses provide additional information, including the value of the
81  * key via a 'parse_value' method. A visitor can be used to get more detail.
82  *
83  * The header \ref paludis/literal_metadata_key.hh "literal_metadata_key.hh"
84  * contains various concrete implementations of MetadataKey subclasses.
85  *
86  * \ingroup g_metadata_key
87  * \since 0.26
88  * \nosubgrouping
89  */
91  public virtual DeclareAbstractAcceptMethods<MetadataKey, MakeTypeList<
92  MetadataCollectionKey<KeywordNameSet>,
93  MetadataCollectionKey<Set<std::string> >,
94  MetadataCollectionKey<Sequence<std::string> >,
95  MetadataCollectionKey<PackageIDSequence>,
96  MetadataCollectionKey<FSPathSequence>,
97  MetadataCollectionKey<Map<std::string, std::string> >,
98  MetadataCollectionKey<Maintainers>,
99  MetadataSpecTreeKey<DependencySpecTree>,
100  MetadataSpecTreeKey<LicenseSpecTree>,
101  MetadataSpecTreeKey<FetchableURISpecTree>,
102  MetadataSpecTreeKey<SimpleURISpecTree>,
103  MetadataSpecTreeKey<PlainTextSpecTree>,
104  MetadataSpecTreeKey<RequiredUseSpecTree>,
105  MetadataValueKey<std::string>,
106  MetadataValueKey<long>,
107  MetadataValueKey<bool>,
108  MetadataValueKey<FSPath>,
109  MetadataValueKey<Slot>,
110  MetadataValueKey<std::shared_ptr<const PackageID> >,
111  MetadataValueKey<std::shared_ptr<const Choices> >,
112  MetadataTimeKey,
113  MetadataSectionKey
114  >::Type>
115  {
116  public:
117  ///\name Basic operations
118  ///\{
119 
120  MetadataKey() = default;
121  virtual ~MetadataKey() = 0;
122 
123  MetadataKey(const MetadataKey &) = delete;
124  MetadataKey & operator= (const MetadataKey &) = delete;
125 
126  ///\}
127 
128  /**
129  * Fetch our raw name.
130  */
131  virtual const std::string raw_name() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
132 
133  /**
134  * Fetch our human name.
135  */
136  virtual const std::string human_name() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
137 
138  /**
139  * Fetch our key type.
140  */
141  virtual MetadataKeyType type() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
142  };
143 
144  /**
145  * A PrettyPrintableMetadataKey is a MetadataKey with a pretty printable value.
146  *
147  * \since 0.58
148  * \ingroup g_metadata_key
149  */
151  public MetadataKey
152  {
153  public:
154  /**
155  * Pretty print our value.
156  *
157  * \since 0.58
158  */
159  virtual const std::string pretty_print_value(
160  const PrettyPrinter &,
161  const PrettyPrintOptions &) const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
162  };
163 
164  /**
165  * A MetadataSectionKey is a MetadataKey that holds a number of other
166  * MetadataKey instances.
167  *
168  * \ingroup g_metadata_key
169  * \since 0.26
170  * \nosubgrouping
171  */
173  public MetadataKey,
174  public ImplementAcceptMethods<MetadataKey, MetadataSectionKey>,
175  public MetadataKeyHolder
176  {
177  public:
178  ///\name Basic operations
179  ///\{
180 
181  virtual ~MetadataSectionKey() = 0;
182 
183  ///\}
184  };
185 
186  /**
187  * Selects whether a MetadataValueKey instantiation is a
188  * PrettyPrintableMetadataKey.
189  *
190  * \since 0.58
191  * \ingroup g_metadata_key
192  */
193  template <typename C_>
195  {
196  enum { value = false };
197  };
198 
199  template <>
200  struct MetadataValueKeyIsPrettyPrintable<std::shared_ptr<const PackageID> >
201  {
202  enum { value = true };
203  };
204 
205  template <>
207  {
208  enum { value = true };
209  };
210 
211  template <>
213  {
214  enum { value = true };
215  };
216 
217  /**
218  * A MetadataValueKey is a MetadataKey that holds some simple type
219  * as its value.
220  *
221  * \ingroup g_metadata_key
222  * \since 0.26
223  * \nosubgrouping
224  */
225  template <typename C_>
227  public std::conditional<MetadataValueKeyIsPrettyPrintable<C_>::value, PrettyPrintableMetadataKey, MetadataKey>::type,
228  public ImplementAcceptMethods<MetadataKey, MetadataValueKey<C_> >
229  {
230  public:
231  virtual ~MetadataValueKey() = 0;
232 
233  /**
234  * Fetch our value.
235  *
236  * \since 0.61 is called parse_value
237  */
238  virtual const C_ parse_value() const
239  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
240  };
241 
242  /**
243  * A MetadataTimeKey is a MetadataKey that has a Timestamp as its value.
244  *
245  * \ingroup g_metadata_key
246  * \since 0.26
247  * \since 0.44 Timestamp instead of time_t
248  * \nosubgrouping
249  */
251  public MetadataKey,
252  public ImplementAcceptMethods<MetadataKey, MetadataTimeKey>
253  {
254  public:
255  virtual ~MetadataTimeKey() = 0;
256 
257  /**
258  * Fetch our value.
259  *
260  * \since 0.44 Timestamp instead of time_t
261  * \since 0.61 is called parse_value
262  */
263  virtual Timestamp parse_value() const
264  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
265  };
266 
267  /**
268  * A MetadataCollectionKey is a MetadataKey that holds a container of some kind of item
269  * as its value.
270  *
271  * \ingroup g_metadata_key
272  * \since 0.26
273  * \nosubgrouping
274  */
275  template <typename C_>
278  public ImplementAcceptMethods<MetadataKey, MetadataCollectionKey<C_> >
279  {
280  public:
281  virtual ~MetadataCollectionKey() = 0;
282 
283  /**
284  * Fetch our value, parse not necessarily cached (so
285  * multiple calls may return different shared_ptrs).
286  *
287  * \since 0.61
288  */
289  virtual const std::shared_ptr<const C_> parse_value() const
290  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
291  };
292 
293  /**
294  * A MetadataSpecTreeKey<> is a MetadataKey that holds a spec tree of some
295  * kind as its value.
296  *
297  * \ingroup g_metadata_key
298  * \since 0.26
299  * \nosubgrouping
300  */
301  template <typename C_>
305  {
306  public:
307  virtual ~MetadataSpecTreeKey() = 0;
308 
309  /**
310  * Fetch our value, parse not necessarily cached (so
311  * multiple calls may return different shared_ptrs).
312  *
313  * \since 0.61
314  */
315  virtual const std::shared_ptr<const C_> parse_value() const
316  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
317  };
318 
319  /**
320  * A MetadataSpecTreeKey<FetchableURISpecTree> is a MetadataKey that holds
321  * a FetchableURISpecTree as its value.
322  *
323  * This specialisation of MetadataSpecTreeKey provides an additional
324  * initial_label method.
325  *
326  * \ingroup g_metadata_key
327  * \since 0.26
328  * \nosubgrouping
329  */
330  template <>
332  public PrettyPrintableMetadataKey,
334  {
335  public:
336  virtual ~MetadataSpecTreeKey() = 0;
337 
338  /**
339  * Fetch our value, parse not necessarily cached (so
340  * multiple calls may return different shared_ptrs).
341  *
342  * \since 0.61
343  */
344  virtual const std::shared_ptr<const FetchableURISpecTree> parse_value() const
345  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
346 
347  /**
348  * Return a URILabel that represents the initial label to use when
349  * deciding the behaviour of individual items in the heirarchy.
350  */
351  virtual const std::shared_ptr<const URILabel> initial_label() const
352  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
353  };
354 
355  /**
356  * A MetadataSpecTreeKey<DependencySpecTree> is a MetadataKey that holds
357  * a FetchableURISpecTree as its value.
358  *
359  * This specialisation of MetadataSpecTreeKey provides an additional
360  * initial_label method.
361  *
362  * \ingroup g_metadata_key
363  * \since 0.26
364  * \nosubgrouping
365  */
366  template <>
368  public PrettyPrintableMetadataKey,
369  public ImplementAcceptMethods<MetadataKey, MetadataSpecTreeKey<DependencySpecTree> >
370  {
371  public:
372  virtual ~MetadataSpecTreeKey() = 0;
373 
374  /**
375  * Fetch our value, parse not necessarily cached (so
376  * multiple calls may return different shared_ptrs).
377  *
378  * \since 0.61
379  */
380  virtual const std::shared_ptr<const DependencySpecTree> parse_value() const
381  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
382 
383  /**
384  * Return a DependenciesLabelSequence that represents the initial labels to use when
385  * deciding the behaviour of individual items in the heirarchy.
386  */
387  virtual const std::shared_ptr<const DependenciesLabelSequence> initial_labels() const
388  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
389  };
390 }
391 
392 #endif
Definition: spec_tree-fwd.hh:71
Definition: metadata_key.hh:250
Definition: visitor-fwd.hh:52
Definition: metadata_key.hh:194
MetadataKeyType
Definition: metadata_key-fwd.hh:16
Definition: pretty_printer.hh:35
Definition: metadata_key-fwd.hh:41
Definition: metadata_key.hh:150
Definition: timestamp.hh:40
Definition: metadata_key-fwd.hh:39
Definition: metadata_key-fwd.hh:40
Definition: options-fwd.hh:34
Definition: metadata_key.hh:172
Definition: visitor-fwd.hh:49
Definition: metadata_key_holder.hh:38
Definition: metadata_key.hh:90
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:64
#define PALUDIS_VISIBLE
Definition: attributes.hh:71