aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-08 09:04:54 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-08 09:04:54 +0000
commitba60ed5885f0ba43151f4cf94da447bac9545728 (patch)
treee3652c1628e0a5fd27ee244bfa6110fc008913e1
parentbe4baf788345073b27f9307c64f412c6f43521c8 (diff)
downloadpaludis-ba60ed5885f0ba43151f4cf94da447bac9545728.tar.gz
paludis-ba60ed5885f0ba43151f4cf94da447bac9545728.tar.xz
More doxygen work.
-rw-r--r--doc/doc_main.doxygen59
-rw-r--r--doc/examples/Makefile.am37
-rw-r--r--doc/examples/example_formatter.cc247
-rw-r--r--doc/examples/example_mask.cc144
-rw-r--r--doc/examples/example_metadata_key.cc261
-rw-r--r--doc/examples/example_package_id.cc160
-rw-r--r--doc/examples/example_stringify_formatter.cc108
-rw-r--r--paludis/formatter-fwd.hh6
-rw-r--r--paludis/formatter.hh526
-rw-r--r--paludis/mask-fwd.hh6
-rw-r--r--paludis/mask.hh104
-rwxr-xr-xpaludis/mask.sr9
-rw-r--r--paludis/metadata_key-fwd.hh6
-rw-r--r--paludis/metadata_key.hh254
-rw-r--r--paludis/metadata_key.se3
-rw-r--r--paludis/package_id-fwd.hh27
-rw-r--r--paludis/package_id.hh258
-rw-r--r--paludis/package_id.se6
-rw-r--r--paludis/repository-fwd.hh11
-rw-r--r--paludis/repository.cc6
-rw-r--r--paludis/repository.hh65
-rw-r--r--paludis/repository.sr7
-rw-r--r--paludis/stringify_formatter-fwd.hh6
-rw-r--r--paludis/stringify_formatter-impl.hh57
-rw-r--r--paludis/stringify_formatter.hh39
25 files changed, 2371 insertions, 41 deletions
diff --git a/doc/doc_main.doxygen b/doc/doc_main.doxygen
index 001e120..5ac3650 100644
--- a/doc/doc_main.doxygen
+++ b/doc/doc_main.doxygen
@@ -20,7 +20,7 @@ using namespace paludis;
/** \defgroup g_actions Actions
*
- * \ingroup g_paludis
+ * \ingroup g_package_id
*
* Action-related classes are used to provide the information needed by a
* PackageID to perform operations such as installing, uninstalling and fetching.
@@ -32,7 +32,7 @@ using namespace paludis;
/** \defgroup g_contents Contents
*
- * \ingroup g_paludis
+ * \ingroup g_metadata_key
*
* Contents heirarchies can be used to iterate over the content of an installed
* or binary package.
@@ -80,3 +80,58 @@ using namespace paludis;
* \ingroup g_paludis
*/
+/** \defgroup g_formatters Formatters
+ *
+ * \ingroup g_metadata_key
+ *
+ * Formatters are used in various places (such as MetadataKey pretty_print methods)
+ * to apply user-defined formatting to parts of text generated for display. They
+ * allow clients to, for example, display accepted and unaccepted use flag names
+ * in different colours, without needing to rewrite the entire pretty printing
+ * system.
+ *
+ * \section Examples
+ *
+ * - \ref example_formatter.cc "example_formatter.cc"
+ * - \ref example_stringify_formatter.cc "example_stringify_formatter.cc"
+ */
+
+/** \defgroup g_package_id Package IDs
+ *
+ * \ingroup g_paludis
+ *
+ * A PackageID represents a particular package version in a Repository. It has
+ * various pieces of associated information, including a name, a version, an
+ * owning repository, a slot, a collection of metadata keys and a collection of
+ * masks.
+ *
+ * \section Examples
+ *
+ * - \ref example_package_id.cc "example_package_id.cc"
+ * - \ref example_action.cc "example_action.cc"
+ * - \ref example_mask.cc "example_mask.cc"
+ * - \ref example_metadata_key.cc "example_metadata_key.cc"
+ */
+
+/** \defgroup g_mask Masks
+ *
+ * \ingroup g_package_id
+ *
+ * A mask represents one reason why a PackageID is masked (not installable).
+ *
+ * \section Examples
+ *
+ * - \ref example_mask.cc "example_mask.cc"
+ */
+
+/** \defgroup g_metadata_key Metadata Keys
+ *
+ * \ingroup g_package_id
+ *
+ * A metadata key hold a piece of information about a PackageID.
+ *
+ * \section Examples
+ *
+ * - \ref example_metadata_key.cc "example_metadata_key.cc"
+ */
+
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index f3bcea6..2d8c5ec 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -18,7 +18,12 @@ noinst_PROGRAMS = \
example_dep_tag \
example_dep_tree \
example_dep_spec_flattener \
- example_environment
+ example_environment \
+ example_formatter \
+ example_stringify_formatter \
+ example_package_id \
+ example_metadata_key \
+ example_mask
EXTRA_DIST = $(noinst_SCRIPTS)
@@ -83,6 +88,36 @@ example_environment_LDFLAGS = \
$(top_builddir)/paludis/libpaludis.la \
$(top_builddir)/paludis/args/libpaludisargs.la
+example_formatter_SOURCES = example_formatter.cc
+example_formatter_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
+example_stringify_formatter_SOURCES = example_stringify_formatter.cc
+example_stringify_formatter_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
+example_package_id_SOURCES = example_package_id.cc
+example_package_id_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
+example_mask_SOURCES = example_mask.cc
+example_mask_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
+example_metadata_key_SOURCES = example_metadata_key.cc
+example_metadata_key_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
built-sources : $(BUILT_SOURCES)
for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
diff --git a/doc/examples/example_formatter.cc b/doc/examples/example_formatter.cc
new file mode 100644
index 0000000..20f0aef
--- /dev/null
+++ b/doc/examples/example_formatter.cc
@@ -0,0 +1,247 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_formatter.cc "example_formatter.cc" .
+ *
+ * \ingroup g_formatters
+ */
+
+/** \example example_formatter.cc
+ *
+ * This example demonstrates how to create a formatter. It outputs information
+ * about a package's dependencies in HTML.
+ *
+ * See \ref example_stringify_formatter.cc "example_stringify_formatter.cc" for
+ * StringifyFormatter, a premade formatter that uses stringify.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <cstdlib>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+
+namespace
+{
+ /* Utility function that replaces dodgy characters with HTML escapes. */
+ std::string escape_html(const std::string & s)
+ {
+ std::string result;
+ for (std::string::const_iterator i(s.begin()), i_end(s.end()) ;
+ i != i_end ; ++i)
+ switch (*i)
+ {
+ case '<':
+ result.append("&lt;");
+ break;
+
+ case '>':
+ result.append("&gt;");
+ break;
+
+ case '&':
+ result.append("&amp;");
+ break;
+
+ default:
+ result.append(std::string(1, *i));
+ }
+
+ return result;
+ }
+
+ /* Utility function that creates an HTML <span> with a colour. */
+ std::string span_colour(const std::string & s, const std::string & c)
+ {
+ return "<span style=\"color: " + c + "\">" + s + "</span>";
+ }
+
+ /* This formatter outputs information about dependencies in HTML. We need
+ * to implement CanFormat<> for all of the things that can be found in
+ * DependencySpecTree::Formatter, as well as CanSpace. */
+ class HTMLFormatter :
+ public CanSpace,
+ public CanFormat<PackageDepSpec>,
+ public CanFormat<DependencyLabelsDepSpec>,
+ public CanFormat<UseDepSpec>,
+ public CanFormat<NamedSetDepSpec>,
+ public CanFormat<BlockDepSpec>
+ {
+ public:
+ /* The second parameter to the format functions has no meaning
+ * beyond being used to overload to the appropriate function. */
+ std::string format(const PackageDepSpec & s, const format::Plain &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#666666");
+ }
+
+ std::string format(const PackageDepSpec & s, const format::Installed &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#6666ff");
+ }
+
+ std::string format(const PackageDepSpec & s, const format::Installable &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#66ff66");
+ }
+
+ std::string format(const DependencyLabelsDepSpec & s, const format::Plain &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#666666");
+ }
+
+ std::string format(const UseDepSpec & s, const format::Plain &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#666666");
+ }
+
+ std::string format(const UseDepSpec & s, const format::Enabled &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#66ff66");
+ }
+
+ std::string format(const UseDepSpec & s, const format::Disabled &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#ff6666");
+ }
+
+ std::string format(const UseDepSpec & s, const format::Forced &) const
+ {
+ return span_colour(escape_html("(" + stringify(s) + ")"), "#66ff66");
+ }
+
+ std::string format(const UseDepSpec & s, const format::Masked &) const
+ {
+ return span_colour(escape_html("(" + stringify(s) + ")"), "#ff6666");
+ }
+
+ std::string format(const NamedSetDepSpec & s, const format::Plain &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#666666");
+ }
+
+ std::string format(const BlockDepSpec & s, const format::Plain &) const
+ {
+ return span_colour(escape_html(stringify(s)), "#666666");
+ }
+
+ std::string newline() const
+ {
+ return "<br />\n";
+ }
+
+ std::string indent(const int i) const
+ {
+ std::string result;
+ for (int x(0) ; x < i ; ++x)
+ result.append("&nbsp; &nbsp; ");
+ return result;
+ }
+ };
+}
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_formatter", "EXAMPLE_FORMATTER_OPTIONS", "EXAMPLE_FORMATTER_CMDLINE");
+
+ /* We start with an Environment, respecting the user's '--environment' choice. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(
+ CommandLine::get_instance()->a_environment.argument()));
+
+ /* Fetch package IDs for installable 'sys-apps/paludis'. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::Matches(PackageDepSpec("sys-apps/paludis", pds_pm_permissive)) &
+ query::SupportsAction<InstallAction>(),
+ qo_order_by_version));
+
+ /* Write nice valid XHTML, because we're good like that. */
+ cout << "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\"" << endl;
+ cout << " \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">" << endl;
+ cout << "<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\">" << endl;
+ cout << "<head><title>Dependencies for sys-apps/paludis</title></head>" << endl;
+ cout << "<body>" << endl;
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ cout << "<h1>" << escape_html(stringify(**i)) << "</h1>" << endl;
+
+ /* Our formatter. It has no saved state, so we can use a single
+ * formatter for all of the keys. */
+ HTMLFormatter formatter;
+
+ /* We need to check that _key() methods don't return zero. */
+ if ((*i)->build_dependencies_key())
+ {
+ cout << "<h2>" << escape_html((*i)->build_dependencies_key()->human_name()) << "</h2>" << endl;
+ cout << "<div style=\"border: 1px solid #999999; background-color: #eeeeee; "
+ "margin-left: 1em; padding: 0.2em 0.5em; \">" << endl;
+ cout << (*i)->build_dependencies_key()->pretty_print(formatter);
+ cout << endl << "</div>" << endl;
+ }
+
+ if ((*i)->run_dependencies_key())
+ {
+ cout << "<h2>" << escape_html((*i)->run_dependencies_key()->human_name()) << "</h2>" << endl;
+ cout << "<div style=\"border: 1px solid #999999; background-color: #eeeeee; "
+ "margin-left: 1em; padding: 0.2em 0.5em; \">" << endl;
+ cout << (*i)->run_dependencies_key()->pretty_print(formatter);
+ cout << endl << "</div>" << endl;
+ }
+
+ if ((*i)->post_dependencies_key())
+ {
+ cout << "<h2>" << escape_html((*i)->post_dependencies_key()->human_name()) << "</h2>" << endl;
+ cout << "<div style=\"border: 1px solid #999999; background-color: #eeeeee; "
+ "margin-left: 1em; padding: 0.2em 0.5em; \">" << endl;
+ cout << (*i)->post_dependencies_key()->pretty_print(formatter);
+ cout << endl << "</div>" << endl;
+ }
+
+ cout << endl;
+ }
+
+ cout << "</body>" << endl;
+ cout << "</html>" << endl;
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return EXIT_SUCCESS;
+}
+
+
+
diff --git a/doc/examples/example_mask.cc b/doc/examples/example_mask.cc
new file mode 100644
index 0000000..1b60e77
--- /dev/null
+++ b/doc/examples/example_mask.cc
@@ -0,0 +1,144 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_mask.cc "example_mask.cc" .
+ *
+ * \ingroup g_mask
+ */
+
+/** \example example_mask.cc
+ *
+ * This example demonstrates how to use Mask. It displays all the
+ * mask keys for a particular PackageID.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <set>
+#include <time.h>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::left;
+using std::setw;
+
+namespace
+{
+ /* We use this visitor to display extra information about a Mask,
+ * depending upon its type. */
+ class MaskInformationVisitor :
+ public ConstVisitor<MaskVisitorTypes>
+ {
+ public:
+ void visit(const UserMask &)
+ {
+ cout << left << setw(30) << " Class:" << " " << "UserMask" << endl;
+ }
+
+ void visit(const UnacceptedMask & mask)
+ {
+ cout << left << setw(30) << " Class:" << " " << "UnacceptedMask" << endl;
+ if (mask.unaccepted_key())
+ cout << left << setw(30) << " Unaccepted key:" << " " << mask.unaccepted_key()->raw_name() << endl;
+ }
+
+ void visit(const RepositoryMask & mask)
+ {
+ cout << left << setw(30) << " Class:" << " " << "RepositoryMask" << endl;
+ if (mask.mask_key())
+ cout << left << setw(30) << " Mask key:" << " " << mask.mask_key()->raw_name() << endl;
+ }
+
+ void visit(const UnsupportedMask & mask)
+ {
+ cout << left << setw(30) << " Class:" << " " << "UnsupportedMask" << endl;
+ cout << left << setw(30) << " Explanation:" << " " << mask.explanation() << endl;
+ }
+
+ void visit(const AssociationMask & mask)
+ {
+ cout << left << setw(30) << " Class:" << " " << "AssociationMask" << endl;
+ if (mask.associated_package())
+ cout << left << setw(30) << " Associated package:" << " " << *mask.associated_package() << endl;
+ }
+ };
+}
+
+int main(int argc, char * argv[])
+{
+ int exit_status(0);
+
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_mask", "EXAMPLE_MASK_OPTIONS", "EXAMPLE_MASK_CMDLINE");
+
+ /* We start with an Environment, respecting the user's '--environment' choice. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(
+ CommandLine::get_instance()->a_environment.argument()));
+
+ /* Fetch package IDs for 'sys-apps/paludis'. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::Matches(PackageDepSpec("sys-apps/paludis", pds_pm_permissive)),
+ qo_order_by_version));
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ cout << **i << ":" << endl;
+
+ /* For each mask key: */
+ for (PackageID::MasksConstIterator m((*i)->begin_masks()), m_end((*i)->end_masks()) ;
+ m != m_end ; ++m)
+ {
+ /* All Mask instances have two basic bits of information: a one
+ * character short key, and a longer description. */
+ cout << left << setw(30) << " Key:" << " " << std::string(1, (*m)->key()) << endl;
+ cout << left << setw(30) << " Description:" << " " << (*m)->description() << endl;
+
+ /* To display more information about a Mask we create a visitor
+ * that visits the appropriate subtype. */
+ MaskInformationVisitor v;
+ (*m)->accept(v);
+
+ cout << endl;
+ }
+
+ cout << endl;
+ }
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return exit_status;
+}
+
diff --git a/doc/examples/example_metadata_key.cc b/doc/examples/example_metadata_key.cc
new file mode 100644
index 0000000..ea3a355
--- /dev/null
+++ b/doc/examples/example_metadata_key.cc
@@ -0,0 +1,261 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_metadata_key.cc "example_metadata_key.cc" .
+ *
+ * \ingroup g_metadata_key
+ */
+
+/** \example example_metadata_key.cc
+ *
+ * This example demonstrates how to use MetadataKey. It displays all the
+ * metadata keys for a particular PackageID.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <set>
+#include <time.h>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::left;
+using std::setw;
+
+namespace
+{
+ /* We use this visitor to display extra information about a MetadataKey,
+ * depending upon its type. */
+ class MetadataKeyInformationVisitor :
+ public ConstVisitor<MetadataKeyVisitorTypes>
+ {
+ private:
+ /* Various methods need a formatter. See \ref example_stringify_formatter.cc
+ * "example_stringify_formatter.cc" for more details. */
+ StringifyFormatter formatter;
+
+ public:
+ void visit(const MetadataStringKey & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataStringKey" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.value() << endl;
+ }
+
+ void visit(const MetadataFSEntryKey & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataFSEntryKey" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.value() << endl;
+ }
+
+ void visit(const MetadataPackageIDKey & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataPackageIDKey" << endl;
+ cout << left << setw(30) << " Value:" << " " << *key.value() << endl;
+ }
+
+ void visit(const MetadataTimeKey & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataTimeKey" << endl;
+
+ /* Yay horrible C formatting routines! */
+ time_t t(key.value());
+ char buf[255];
+ if (! strftime(buf, 254, "%c", gmtime(&t)))
+ buf[0] = '\0';
+ cout << left << setw(30) << " Value:" << " " << buf << endl;
+ }
+
+ void visit(const MetadataContentsKey &)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataContentsKey" << endl;
+ /* We won't display the contents of the contents key here, since
+ * it involves creating another visitor. See \ref
+ * example_contents.cc "example_contents.cc" for that. */
+ }
+
+ void visit(const MetadataRepositoryMaskInfoKey & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataRepositoryMaskInfoKey" << endl;
+
+ /* MetadataRepositoryMaskInfoKey::value() can return a zero
+ * pointer. Other keys can't. */
+ if (key.value())
+ {
+ cout << left << setw(30) << " Mask file:" << " " << key.value()->mask_file << endl;
+ /* Comment looks best if it's outputted over multiple lines,
+ * as that's how it tends to be stored in package.mask. */
+ cout << left << setw(30) << " Comment:" << " ";
+ bool first(true);
+ for (Sequence<std::string>::ConstIterator i(key.value()->comment->begin()),
+ i_end(key.value()->comment->end()) ;
+ i != i_end ; ++i)
+ {
+ if (! first)
+ cout << left << setw(30) << " ..." << " ";
+ cout << *i << endl;
+ first = false;
+ }
+ }
+ }
+
+ void visit(const MetadataSpecTreeKey<RestrictSpecTree> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<RestrictSpecTree>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSpecTreeKey<ProvideSpecTree> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<ProvideSpecTree>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSpecTreeKey<LicenseSpecTree> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<LicenseSpecTree>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSpecTreeKey<SimpleURISpecTree> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<SimpleURISpecTree>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSpecTreeKey<DependencySpecTree> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<DependencySpecTree>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSpecTreeKey<FetchableURISpecTree> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<FetchableURISpecTree>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ cout << left << setw(30) << " Initial label:" << " " << key.initial_label()->text() << endl;
+ }
+
+ void visit(const MetadataSetKey<IUseFlagSet> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<IUseFlagSet>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSetKey<KeywordNameSet> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<KeywordNameSet>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSetKey<UseFlagNameSet> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<UseFlagNameSet>" << endl;
+ cout << left << setw(30) << " Value:" << " " << key.pretty_print_flat(formatter) << endl;
+ }
+
+ void visit(const MetadataSetKey<Set<std::string> > & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<Set<std::string> >" << endl;
+ cout << left << setw(30) << " Value:" << " " << join(key.value()->begin(), key.value()->end(), " ") << endl;
+ }
+
+ void visit(const MetadataSetKey<PackageIDSequence> & key)
+ {
+ cout << left << setw(30) << " Class:" << " " << "MetadataSpecTreeKey<PackageIDSequence>" << endl;
+ /* Slight trickery: a PackageIDSequence stores shared pointers
+ * to PackageID instances, so we need indirect_iterator to get
+ * an extra level of dereferencing. */
+ cout << left << setw(30) << " Value:" << " " << join(indirect_iterator(key.value()->begin()),
+ indirect_iterator(key.value()->end()), " ") << endl;
+ }
+ };
+}
+
+int main(int argc, char * argv[])
+{
+ int exit_status(0);
+
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_metadata_key", "EXAMPLE_METADATA_KEY_OPTIONS", "EXAMPLE_METADATA_KEY_CMDLINE");
+
+ /* We start with an Environment, respecting the user's '--environment' choice. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(
+ CommandLine::get_instance()->a_environment.argument()));
+
+ /* Fetch package IDs for 'sys-apps/paludis'. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::Matches(PackageDepSpec("sys-apps/paludis", pds_pm_permissive)),
+ qo_order_by_version));
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ cout << **i << ":" << endl;
+
+ /* For each metadata key: */
+ for (PackageID::MetadataConstIterator k((*i)->begin_metadata()), k_end((*i)->end_metadata()) ;
+ k != k_end ; ++k)
+ {
+ /* All MetadataKey instances have a raw name, a human readable
+ * name and a type. The type is a hint to clients as to whether
+ * the key should be displayed when outputting the package (for
+ * example, 'paludis --query' shows mkt_significant keys first,
+ * then mkt_normal keys, and doesn't show mkt_dependencies
+ * without '--show-deps' or mkt_internal without
+ * '--show-metadata'. */
+ cout << left << setw(30) << " Raw name:" << " " << (*k)->raw_name() << endl;
+ cout << left << setw(30) << " Human name:" << " " << (*k)->human_name() << endl;
+ cout << left << setw(30) << " Type:" << " " << (*k)->type() << endl;
+
+ /* To get any more information out of a MetadataKey we have to
+ * use a visitor. This lets us write type-safe handling code for
+ * the appropriate MetadataKey subclass without the need for any
+ * runtime type information queries. */
+ MetadataKeyInformationVisitor v;
+ (*k)->accept(v);
+
+ cout << endl;
+ }
+
+ cout << endl;
+ }
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return exit_status;
+}
+
+
+
diff --git a/doc/examples/example_package_id.cc b/doc/examples/example_package_id.cc
new file mode 100644
index 0000000..b684e3a
--- /dev/null
+++ b/doc/examples/example_package_id.cc
@@ -0,0 +1,160 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_package_id.cc "example_package_id.cc" .
+ *
+ * \ingroup g_package_id
+ */
+
+/** \example example_package_id.cc
+ *
+ * This example demonstrates how to use PackageID.
+ *
+ * See \ref example_action.cc "example_action.cc" for more on actions. See \ref
+ * example_metadata_key.cc "example_metadata_key.cc" for more on metadata keys.
+ * See \ref example_mask.cc "example_mask.cc" for more on masks.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <set>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::left;
+using std::setw;
+using std::hex;
+using std::boolalpha;
+
+int main(int argc, char * argv[])
+{
+ int exit_status(0);
+
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_package_id", "EXAMPLE_PACKAGE_ID_OPTIONS", "EXAMPLE_PACKAGE_ID_CMDLINE");
+
+ /* We start with an Environment, respecting the user's '--environment' choice. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(
+ CommandLine::get_instance()->a_environment.argument()));
+
+ /* Fetch package IDs for 'sys-apps/paludis'. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::Matches(PackageDepSpec("sys-apps/paludis", pds_pm_permissive)),
+ qo_order_by_version));
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ /* IDs can be written to an ostream. */
+ cout << **i << ":" << endl;
+
+ /* Start by outputting some basic properties: */
+ cout << left << setw(30) << " Name:" << " " << (*i)->name() << endl;
+ cout << left << setw(30) << " Version:" << " " << (*i)->version() << endl;
+ cout << left << setw(30) << " Slot:" << " " << (*i)->slot() << endl;
+ cout << left << setw(30) << " Repository Name:" << " " << (*i)->repository()->name() << endl;
+
+ /* The PackageID::canonical_form method should be used when
+ * outputting a package (the ostream << operator uses this). */
+ cout << left << setw(30) << " idcf_full:" << " " << (*i)->canonical_form(idcf_full) << endl;
+ cout << left << setw(30) << " idcf_version:" << " " << (*i)->canonical_form(idcf_version) << endl;
+ cout << left << setw(30) << " idcf_no_version:" << " " << (*i)->canonical_form(idcf_no_version) << endl;
+
+ /* Let's see what keys we have. Other examples cover keys in depth,
+ * so we'll just use the basic methods here. */
+ cout << left << setw(30) << " Keys:" << " " << endl;
+ for (PackageID::MetadataConstIterator k((*i)->begin_metadata()), k_end((*i)->end_metadata()) ;
+ k != k_end ; ++k)
+ cout << left << setw(30) << (" " + (*k)->raw_name() + ":") << " " << (*k)->human_name() << endl;
+
+ /* And what about masks? Again, these are covered in depth
+ * elsewhere. */
+ if ((*i)->masked())
+ {
+ cout << left << setw(30) << " Masks:" << " " << endl;
+ for (PackageID::MasksConstIterator m((*i)->begin_masks()), m_end((*i)->end_masks()) ;
+ m != m_end ; ++m)
+ cout << left << setw(30) << (" " + stringify((*m)->key()) + ":") << " " << (*m)->description() << endl;
+ }
+
+ /* Let's see which actions we support. There's no particularly nice
+ * way of doing this, since it's not something we'd expect to be
+ * doing. */
+ std::set<std::string> actions;
+ {
+ SupportsActionTest<InstallAction> install_action;
+ if ((*i)->supports_action(install_action))
+ actions.insert("install");
+
+ SupportsActionTest<InstalledAction> installed_action;
+ if ((*i)->supports_action(installed_action))
+ actions.insert("installed");
+
+ SupportsActionTest<UninstallAction> uninstall_action;
+ if ((*i)->supports_action(uninstall_action))
+ actions.insert("uninstall");
+
+ SupportsActionTest<PretendAction> pretend_action;
+ if ((*i)->supports_action(pretend_action))
+ actions.insert("pretend");
+
+ SupportsActionTest<ConfigAction> config_action;
+ if ((*i)->supports_action(config_action))
+ actions.insert("config");
+
+ SupportsActionTest<UninstallAction> fetch_action;
+ if ((*i)->supports_action(fetch_action))
+ actions.insert("fetch");
+
+ SupportsActionTest<UninstallAction> info_action;
+ if ((*i)->supports_action(info_action))
+ actions.insert("info");
+ }
+ cout << left << setw(30) << " Actions:" << " " << join(actions.begin(), actions.end(), " ") << endl;
+
+ /* And various misc methods. Clients don't usually use these
+ * directly. */
+ cout << left << setw(30) << " breaks_portage:" << " " << boolalpha << (*i)->breaks_portage() << endl;
+ cout << left << setw(30) << " extra_hash_value:" << " " << "0x" << hex << (*i)->extra_hash_value() << endl;
+
+ cout << endl;
+ }
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return exit_status;
+}
+
+
diff --git a/doc/examples/example_stringify_formatter.cc b/doc/examples/example_stringify_formatter.cc
new file mode 100644
index 0000000..6f5d3b6
--- /dev/null
+++ b/doc/examples/example_stringify_formatter.cc
@@ -0,0 +1,108 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_stringify_formatter.cc "example_stringify_formatter.cc" .
+ *
+ * \ingroup g_formatters
+ */
+
+/** \example example_stringify_formatter.cc
+ *
+ * This example demonstrates how to use StringifyFormatter.
+ *
+ * See \ref example_formatter.cc "example_formatter.cc" for how to create
+ * a custom Formatter.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <cstdlib>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_stringify_formatter", "EXAMPLE_STRINGIFY_FORMATTER_OPTIONS", "EXAMPLE_STRINGIFY_FORMATTER_CMDLINE");
+
+ /* We start with an Environment, respecting the user's '--environment' choice. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(
+ CommandLine::get_instance()->a_environment.argument()));
+
+ /* Fetch package IDs for installable 'sys-apps/paludis'. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::Matches(PackageDepSpec("sys-apps/paludis", pds_pm_permissive)) &
+ query::SupportsAction<InstallAction>(),
+ qo_order_by_version));
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ cout << stringify(**i) << ":" << endl;
+
+ /* Our formatter. It has no saved state, so we can use a single
+ * formatter for all of the keys. */
+ StringifyFormatter formatter;
+
+ /* We need to check that _key() methods don't return zero. */
+ if ((*i)->iuse_key())
+ {
+ cout << " " << (*i)->iuse_key()->human_name() << ":" << endl;
+ cout << " " << (*i)->iuse_key()->pretty_print_flat(formatter) << endl;
+ }
+
+ if ((*i)->keywords_key())
+ {
+ cout << " " << (*i)->keywords_key()->human_name() << ":" << endl;
+ cout << " " << (*i)->keywords_key()->pretty_print_flat(formatter) << endl;
+ }
+
+ if ((*i)->homepage_key())
+ {
+ cout << " " << (*i)->homepage_key()->human_name() << ":" << endl;
+ cout << " " << (*i)->homepage_key()->pretty_print_flat(formatter) << endl;
+ }
+
+ cout << endl;
+ }
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return EXIT_SUCCESS;
+}
+
+
+
+
diff --git a/paludis/formatter-fwd.hh b/paludis/formatter-fwd.hh
index 0a02836..361e9fb 100644
--- a/paludis/formatter-fwd.hh
+++ b/paludis/formatter-fwd.hh
@@ -22,6 +22,12 @@
#include <paludis/util/no_type.hh>
+/** \file
+ * Forward declarations for paludis/formatter.hh .
+ *
+ * \ingroup g_formatters
+ */
+
namespace paludis
{
template <
diff --git a/paludis/formatter.hh b/paludis/formatter.hh
index ccbc6c0..78fca7b 100644
--- a/paludis/formatter.hh
+++ b/paludis/formatter.hh
@@ -27,135 +27,399 @@
#include <paludis/util/attributes.hh>
#include <string>
+/** \file
+ * Declarations for the Formatter class.
+ *
+ * \ingroup g_formatters
+ *
+ * \section Examples
+ *
+ * - \ref example_formatter.cc "example_formatter.cc"
+ * - \ref example_stringify_formatter.cc "example_stringify_formatter.cc"
+ */
+
namespace paludis
{
+ /** \namespace paludis::format
+ *
+ * The paludis::format:: namespace contains various Formatter related
+ * utilities.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ */
namespace format
{
+ /**
+ * Tag to indicate that an item should be formatted as 'plain'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Plain
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'enabled'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Enabled
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'disabled'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Disabled
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'masked'
+ * (and disabled -- see format::Forced for masked and enabled).
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Masked
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'forced'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Forced
{
};
+ /**
+ * Tag to indicate that an item should be decorated as 'changed'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Changed
{
};
+ /**
+ * Tag to indicate that an item should be decorated as 'added'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Added
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'accepted'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Accepted
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'unaccepted'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Unaccepted
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'installed'.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Installed
{
};
+ /**
+ * Tag to indicate that an item should be formatted as 'installable'
+ * (but not installed).
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct Installable
{
};
+ /**
+ * Used by CategorySelector<> to declare that format::Plain is the only
+ * role supported by a particular class.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct PlainRoles;
+
+ /**
+ * Used by CategorySelector<> to declare that format::Plain,
+ * format::Enabled, format::Disabled, format::Forced, format::Masked,
+ * format::Added and format::Changed are the roles supported by a
+ * particular class.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct IUseRoles;
+
+ /**
+ * Used by CategorySelector<> to declare that format::Plain,
+ * format::Enabled, format::Disabled, format::Forced and format::Masked
+ * are the roles supported by a particular class.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct UseRoles;
+
+ /**
+ * Used by CategorySelector<> to declare that format::Plain,
+ * format::Accepted and format::Unaccepted are the roles supported by a
+ * particular class.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct AcceptableRoles;
+
+ /**
+ * Used by CategorySelector<> to declare that format::Plain,
+ * format::Installed and format::Installable are the roles supported by
+ * a particular class.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct PackageRoles;
+
+ /**
+ * Used by CategorySelector<> to declare that no roles at all are
+ * supported by a particular class.
+ *
+ * This category is not used by any 'real' class. It is used for
+ * NoType<> to work around the lack of variadic templates in the current
+ * C++ standard.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
struct NoRoles;
+ /**
+ * By default, a type supports format::PlainRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
struct CategorySelector
{
+ /// The roles this type supports.
typedef PlainRoles Category;
};
+ /**
+ * IUseFlag supports IUseRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct CategorySelector<IUseFlag>
{
+ /// The roles this type supports.
typedef IUseRoles Category;
};
+ /**
+ * UseFlagName supports UseRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct CategorySelector<UseFlagName>
{
+ /// The roles this type supports.
typedef UseRoles Category;
};
+ /**
+ * UseDepSpec supports UseRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct CategorySelector<UseDepSpec>
{
+ /// The roles this type supports.
typedef UseRoles Category;
};
+ /**
+ * LicenseDepSpec supports AcceptableRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct CategorySelector<LicenseDepSpec>
{
+ /// The roles this type supports.
typedef AcceptableRoles Category;
};
+ /**
+ * KeywordName supports AcceptableRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct CategorySelector<KeywordName>
{
+ /// The roles this type supports.
typedef AcceptableRoles Category;
};
+ /**
+ * PackageDepSpec supports PackageRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct CategorySelector<PackageDepSpec>
{
+ /// The roles this type supports.
typedef PackageRoles Category;
};
+ /**
+ * PackageID supports PackageRoles.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct CategorySelector<PackageID>
{
+ /// The roles this type supports.
typedef PackageRoles Category;
};
+ /**
+ * A tr1::shared_ptr<T_> supports the same roles as T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
struct CategorySelector<tr1::shared_ptr<T_> >
{
+ /// The roles this type supports.
typedef typename CategorySelector<T_>::Category Category;
};
+ /**
+ * A const T_ supports the same roles as T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
struct CategorySelector<const T_>
{
+ /// The roles this type supports.
typedef typename CategorySelector<T_>::Category Category;
};
+ /**
+ * NoType<> doesn't support any format roles.
+ *
+ * Used to work around the lack of variadic templates in the current C++
+ * standard.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <unsigned u_>
struct CategorySelector<NoType<u_> >
{
+ /// The roles this type supports.
typedef NoRoles Category;
};
+
+ ///\}
}
template <typename T_, typename C_>
struct CanFormatBase;
+ /**
+ * Base class for anything that implements the format functions for
+ * format::PlainRoles on type T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
class PALUDIS_VISIBLE CanFormatBase<T_, format::PlainRoles>
{
public:
+ ///\name Basic operations
+ ///\{
+
CanFormatBase()
{
}
@@ -164,14 +428,30 @@ namespace paludis
{
}
+ ///\}
+
+ /**
+ * Format this item as 'Plain'.
+ */
virtual std::string format(const T_ &, const format::Plain &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * Base class for anything that implements the format functions for
+ * format::AcceptableRoles on type T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
class PALUDIS_VISIBLE CanFormatBase<T_, format::AcceptableRoles>
{
public:
+ ///\name Basic operations
+ ///\{
+
CanFormatBase()
{
}
@@ -180,20 +460,42 @@ namespace paludis
{
}
+ ///\}
+
+ /**
+ * Format this item as 'Plain'.
+ */
virtual std::string format(const T_ &, const format::Plain &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Accepted'.
+ */
virtual std::string format(const T_ &, const format::Accepted &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Unaccepted'.
+ */
virtual std::string format(const T_ &, const format::Unaccepted &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * Base class for anything that implements the format functions for
+ * format::UseRoles on type T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
class PALUDIS_VISIBLE CanFormatBase<T_, format::UseRoles>
{
public:
+ ///\name Basic operations
+ ///\{
+
CanFormatBase()
{
}
@@ -202,26 +504,54 @@ namespace paludis
{
}
+ ///\}
+
+ /**
+ * Format this item as 'Plain'.
+ */
virtual std::string format(const T_ &, const format::Plain &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Enabled'.
+ */
virtual std::string format(const T_ &, const format::Enabled &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Disabled'.
+ */
virtual std::string format(const T_ &, const format::Disabled &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Forced'.
+ */
virtual std::string format(const T_ &, const format::Forced &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Masked'.
+ */
virtual std::string format(const T_ &, const format::Masked &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * Base class for anything that implements the format functions for
+ * format::IUseRoles on type T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
class PALUDIS_VISIBLE CanFormatBase<T_, format::IUseRoles>
{
public:
+ ///\name Basic operations
+ ///\{
+
CanFormatBase()
{
}
@@ -230,32 +560,66 @@ namespace paludis
{
}
+ ///\}
+
+ /**
+ * Format this item as 'Plain'.
+ */
virtual std::string format(const T_ &, const format::Plain &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Enabled'.
+ */
virtual std::string format(const T_ &, const format::Enabled &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Disabled'.
+ */
virtual std::string format(const T_ &, const format::Disabled &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Forced'.
+ */
virtual std::string format(const T_ &, const format::Forced &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Masked'.
+ */
virtual std::string format(const T_ &, const format::Masked &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Decorate this item as 'Added'.
+ */
virtual std::string decorate(const T_ &, const std::string &, const format::Added &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Decorate this item as 'Changed'.
+ */
virtual std::string decorate(const T_ &, const std::string &, const format::Changed &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * Base class for anything that implements the format functions for
+ * format::PackageRoles on type T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
class PALUDIS_VISIBLE CanFormatBase<T_, format::PackageRoles>
{
public:
+ ///\name Basic operations
+ ///\{
+
CanFormatBase()
{
}
@@ -264,38 +628,89 @@ namespace paludis
{
}
+ ///\}
+
+ /**
+ * Format this item as 'Plain'.
+ */
virtual std::string format(const T_ &, const format::Plain &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Installed'.
+ */
virtual std::string format(const T_ &, const format::Installed &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Format this item as 'Installable'.
+ */
virtual std::string format(const T_ &, const format::Installable &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * Base class for anything that implements the format functions for
+ * format::NoRoles on type NoType<T_>.
+ *
+ * Used to work around the lack of variadic templates in the current C++
+ * standard.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <unsigned u_>
class PALUDIS_VISIBLE CanFormatBase<NoType<u_>, format::NoRoles>
{
public:
+ ///\name Basic operations
+ ///\{
+
CanFormatBase()
{
}
+
+ ///\}
};
+ /**
+ * Descendents of this class implement the necessary methods to format an
+ * item of type T_.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_>
class PALUDIS_VISIBLE CanFormat :
public CanFormatBase<T_, typename format::CategorySelector<T_>::Category>
{
public:
+ ///\name Basic operations
+ ///\{
+
CanFormat()
{
}
+
+ ///\}
};
+ /**
+ * Descendents of this class implement the necessary methods to format
+ * whitespace.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE CanSpace
{
public:
+ ///\name Basic operations
+ ///\{
+
CanSpace()
{
}
@@ -304,13 +719,29 @@ namespace paludis
{
}
+ ///\}
+
+ /**
+ * Output a newline.
+ */
virtual std::string newline() const = 0;
+
+ /**
+ * Output an indent marker of the specified indent level.
+ */
virtual std::string indent(const int) const = 0;
};
template <typename T_, typename C_, unsigned u_>
class FormatFunctionsByProxy;
+ /**
+ * Used by Formatter to implement the CanFormat<T_> interface.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_, unsigned u_>
class PALUDIS_VISIBLE FormatFunctionsByProxy<T_, format::PlainRoles, u_> :
public CanFormat<T_>
@@ -319,17 +750,29 @@ namespace paludis
const CanFormat<T_> * const _proxy;
public:
+ ///\name Basic operations
+ ///\{
+
FormatFunctionsByProxy(const CanFormat<T_> * const p) :
_proxy(p)
{
}
+ ///\}
+
virtual std::string format(const T_ & s, const format::Plain & p) const
{
return _proxy->format(s, p);
}
};
+ /**
+ * Used by Formatter to implement the CanFormat<T_> interface.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_, unsigned u_>
class PALUDIS_VISIBLE FormatFunctionsByProxy<T_, format::AcceptableRoles, u_> :
public CanFormat<T_>
@@ -338,11 +781,16 @@ namespace paludis
const CanFormat<T_> * const _proxy;
public:
+ ///\name Basic operations
+ ///\{
+
FormatFunctionsByProxy(const CanFormat<T_> * const p) :
_proxy(p)
{
}
+ ///\}
+
virtual std::string format(const T_ & s, const format::Plain & p) const
{
return _proxy->format(s, p);
@@ -359,6 +807,13 @@ namespace paludis
}
};
+ /**
+ * Used by Formatter to implement the CanFormat<T_> interface.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_, unsigned u_>
class PALUDIS_VISIBLE FormatFunctionsByProxy<T_, format::UseRoles, u_> :
public CanFormat<T_>
@@ -367,11 +822,16 @@ namespace paludis
const CanFormat<T_> * const _proxy;
public:
+ ///\name Basic operations
+ ///\{
+
FormatFunctionsByProxy(const CanFormat<T_> * const p) :
_proxy(p)
{
}
+ ///\}
+
virtual std::string format(const T_ & s, const format::Plain & p) const
{
return _proxy->format(s, p);
@@ -398,6 +858,13 @@ namespace paludis
}
};
+ /**
+ * Used by Formatter to implement the CanFormat<T_> interface.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_, unsigned u_>
class PALUDIS_VISIBLE FormatFunctionsByProxy<T_, format::IUseRoles, u_> :
public CanFormat<T_>
@@ -406,11 +873,16 @@ namespace paludis
const CanFormat<T_> * const _proxy;
public:
+ ///\name Basic operations
+ ///\{
+
FormatFunctionsByProxy(const CanFormat<T_> * const p) :
_proxy(p)
{
}
+ ///\}
+
virtual std::string format(const T_ & s, const format::Plain & p) const
{
return _proxy->format(s, p);
@@ -447,6 +919,13 @@ namespace paludis
}
};
+ /**
+ * Used by Formatter to implement the CanFormat<T_> interface.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename T_, unsigned u_>
class PALUDIS_VISIBLE FormatFunctionsByProxy<T_, format::PackageRoles, u_> :
public CanFormat<T_>
@@ -455,11 +934,16 @@ namespace paludis
const CanFormat<T_> * const _proxy;
public:
+ ///\name Basic operations
+ ///\{
+
FormatFunctionsByProxy(const CanFormat<T_> * const p) :
_proxy(p)
{
}
+ ///\}
+
virtual std::string format(const T_ & s, const format::Plain & p) const
{
return _proxy->format(s, p);
@@ -476,17 +960,49 @@ namespace paludis
}
};
+ /**
+ * Used by Formatter to implement the CanFormat<T_> interface.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <unsigned u_>
class PALUDIS_VISIBLE FormatFunctionsByProxy<NoType<u_>, format::NoRoles, u_>
{
public:
+ ///\name Basic operations
+ ///\{
+
FormatFunctionsByProxy(const void * const)
{
}
+ ///\}
+
void format(const NoType<u_> &) const;
};
+ /**
+ * A Formatter is a class that implements all the format routines for each
+ * of its template parameters.
+ *
+ * A Formatter is required by most MetadataKey pretty_print methods. Instead
+ * of requiring that formatters support every format method with every
+ * possible role for every class, scary template voodoo is used to ensure that
+ * only the format methods appropriate for the classes passed as template
+ * parameters with roles appropriate for those classes are required.
+ *
+ * A Formatter can be implicitly constructed from any type that implements
+ * CanFormat<> for every requested type, as well as the CanSpace interface.
+ *
+ * For a basic formatter that uses paludis::stringify() to do all
+ * formatting, see StringifyFormatter.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <
typename T1_,
typename T2_,
@@ -526,6 +1042,14 @@ namespace paludis
const CanSpace * const _proxy;
public:
+ ///\name Basic operations
+ ///\{
+
+ /**
+ * A Formatter is implicitly constructible from any type that
+ * supports all the relevant CanFormat<> interfaces, as well as the
+ * CanSpace interface.
+ */
template <typename T_>
Formatter(const T_ & t) :
FormatFunctionsByProxy<T1_, typename format::CategorySelector<T1_>::Category, 1>(&t),
@@ -568,6 +1092,8 @@ namespace paludis
{
}
+ ///\}
+
using FormatFunctionsByProxy<T1_, typename format::CategorySelector<T1_>::Category, 1>::format;
using FormatFunctionsByProxy<T2_, typename format::CategorySelector<T2_>::Category, 2>::format;
using FormatFunctionsByProxy<T3_, typename format::CategorySelector<T3_>::Category, 3>::format;
diff --git a/paludis/mask-fwd.hh b/paludis/mask-fwd.hh
index 63c5a17..e8f0b29 100644
--- a/paludis/mask-fwd.hh
+++ b/paludis/mask-fwd.hh
@@ -22,6 +22,12 @@
#include <paludis/util/visitor-fwd.hh>
+/** \file
+ * Forward declarations for paludis/mask.hh .
+ *
+ * \ingroup g_mask
+ */
+
namespace paludis
{
class Mask;
diff --git a/paludis/mask.hh b/paludis/mask.hh
index 29b660c..4681e91 100644
--- a/paludis/mask.hh
+++ b/paludis/mask.hh
@@ -29,11 +29,28 @@
#include <paludis/util/sequence-fwd.hh>
#include <string>
+/** \file
+ * Declarations for mask classes.
+ *
+ * \ingroup g_mask
+ *
+ * \section Examples
+ *
+ * - \ref example_mask.cc "example_mask.cc" (for masks)
+ */
+
namespace paludis
{
#include <paludis/mask-sr.hh>
+ /**
+ * Types for a visitor that can visit a Mask subclass.
+ *
+ * \ingroup g_mask
+ * \since 0.26
+ * \nosubgrouping
+ */
struct MaskVisitorTypes :
VisitorTypes<
MaskVisitorTypes,
@@ -47,51 +64,138 @@ namespace paludis
{
};
+ /**
+ * A Mask represents one reason why a PackageID is masked (not available to
+ * be installed).
+ *
+ * A basic Mask has:
+ *
+ * - A single character key, which can be used by clients if they need a
+ * very compact way of representing a mask.
+ *
+ * - A description.
+ *
+ * Subclasses provide additional information.
+ *
+ * \ingroup g_mask
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE Mask :
public virtual ConstAcceptInterface<MaskVisitorTypes>
{
public:
+ ///\name Basic operations
+ ///\{
+
virtual ~Mask() = 0;
+ ///\}
+
+ /**
+ * A single character key, which can be used by clients if they need
+ * a very compact way of representing a mask.
+ */
virtual const char key() const = 0;
+
+ /**
+ * A description of the mask.
+ */
virtual const std::string description() const = 0;
};
+ /**
+ * A UserMask is a Mask due to user configuration.
+ *
+ * \ingroup g_mask
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE UserMask :
public Mask,
public ConstAcceptInterfaceVisitsThis<MaskVisitorTypes, UserMask>
{
};
+ /**
+ * An UnacceptedMask is a Mask that signifies that a particular value or
+ * combination of values in (for example) a MetadataSetKey or
+ * MetadataSpecTreeKey is not accepted by user configuration.
+ *
+ * \ingroup g_mask
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE UnacceptedMask :
public Mask,
public ConstAcceptInterfaceVisitsThis<MaskVisitorTypes, UnacceptedMask>
{
public:
+ /**
+ * Fetch the metadata key that is not accepted.
+ */
virtual const tr1::shared_ptr<const MetadataKey> unaccepted_key() const = 0;
};
+ /**
+ * A RepositoryMask is a Mask that signifies that a PackageID has been
+ * marked as masked by a Repository.
+ *
+ * \ingroup g_mask
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE RepositoryMask :
public Mask,
public ConstAcceptInterfaceVisitsThis<MaskVisitorTypes, RepositoryMask>
{
public:
+ /**
+ * Fetch a metadata key explaining the mask. May return a zero
+ * pointer, if no more information is available.
+ */
virtual const tr1::shared_ptr<const MetadataKey> mask_key() const = 0;
};
+ /**
+ * An UnsupportedMask is a Mask that signifies that a PackageID is not
+ * supported, for example because it is broken or because it uses an
+ * unrecognised EAPI.
+ *
+ * \ingroup g_mask
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE UnsupportedMask :
public Mask,
public ConstAcceptInterfaceVisitsThis<MaskVisitorTypes, UnsupportedMask>
{
public:
+ /**
+ * An explanation of why we are unsupported.
+ */
virtual const std::string explanation() const = 0;
};
+ /**
+ * An AssociationMask is a Mask that signifies that a PackageID is masked
+ * because of its association with another PackageID that is itself masked.
+ *
+ * This is used by old-style virtuals. If the provider of a virtual is
+ * masked then the virtual itself is masked by association.
+ *
+ * \ingroup g_mask
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE AssociationMask :
public Mask,
public ConstAcceptInterfaceVisitsThis<MaskVisitorTypes, AssociationMask>
{
public:
+ /**
+ * Fetch the associated package.
+ */
virtual const tr1::shared_ptr<const PackageID> associated_package() const = 0;
};
}
diff --git a/paludis/mask.sr b/paludis/mask.sr
index c7d73a9..f754270 100755
--- a/paludis/mask.sr
+++ b/paludis/mask.sr
@@ -11,8 +11,15 @@ make_class_RepositoryMaskInfo()
doxygen_comment << "END"
/**
* Information about a RepositoryMask.
+ *
+ * The mask_file key holds the file whence the mask originates.
+ *
+ * The comment key is a sequence of lines explaining the mask.
+ *
+ * \ingroup g_package_id
+ * \since 0.26
+ * \nosubgrouping
*/
END
}
-
diff --git a/paludis/metadata_key-fwd.hh b/paludis/metadata_key-fwd.hh
index b71eb4d..758c98f 100644
--- a/paludis/metadata_key-fwd.hh
+++ b/paludis/metadata_key-fwd.hh
@@ -24,6 +24,12 @@
#include <paludis/name-fwd.hh>
#include <iosfwd>
+/** \file
+ * Forward declarations for paludis/metadata_key.hh .
+ *
+ * \ingroup g_metadata_key
+ */
+
namespace paludis
{
class MetadataKeyVisitorTypes;
diff --git a/paludis/metadata_key.hh b/paludis/metadata_key.hh
index 92c6e41..330b64e 100644
--- a/paludis/metadata_key.hh
+++ b/paludis/metadata_key.hh
@@ -36,8 +36,25 @@
#include <paludis/util/visitor.hh>
#include <string>
+/** \file
+ * Declarations for metadata key classes.
+ *
+ * \ingroup g_metadata_key
+ *
+ * \section Examples
+ *
+ * - \ref example_metadata_key.cc "example_metadata_key.cc" (for metadata keys)
+ */
+
namespace paludis
{
+ /**
+ * Types for a visitor that can visit a MetadataKey subclass.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
struct MetadataKeyVisitorTypes :
VisitorTypes<
MetadataKeyVisitorTypes,
@@ -63,125 +80,305 @@ namespace paludis
{
};
+ /**
+ * A MetadataKey is a generic key that contains a particular piece of
+ * information about a PackageID instance.
+ *
+ * A basic MetadataKey has:
+ *
+ * - A raw name. This is in a repository-defined format designed to closely
+ * represent the internal name. For example, ebuilds and VDB IDs use
+ * raw names like 'DESCRIPTION' and 'KEYWORDS', whereas CRAN uses names
+ * like 'Title' and 'BundleDescription'. The raw name is unique in a
+ * PackageID.
+ *
+ * - A human name. This is the name that should be used when outputting
+ * normally for a human to read.
+ *
+ * - A MetadataKeyType. This is a hint to clients as to whether the key
+ * should be displayed when outputting information about a package ID.
+ *
+ * Subclasses provide additional information, including the 'value' of the
+ * key. A ConstVisitor using MetadataKeyVisitorTypes can be used to get more
+ * detail.
+ */
class PALUDIS_VISIBLE MetadataKey :
private InstantiationPolicy<MetadataKey, instantiation_method::NonCopyableTag>,
private PrivateImplementationPattern<MetadataKey>,
public virtual ConstAcceptInterface<MetadataKeyVisitorTypes>
{
protected:
- MetadataKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\name Basic operations
+ ///\{
+
+ MetadataKey(const std::string & raw_name, const std::string & human_name, const MetadataKeyType);
public:
virtual ~MetadataKey() = 0;
+ ///\}
+
+ /**
+ * Fetch our raw name.
+ */
virtual const std::string raw_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
+
+ /**
+ * Fetch our human name.
+ */
virtual const std::string human_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
+
+ /**
+ * Fetch our key type.
+ */
virtual const MetadataKeyType type() const PALUDIS_ATTRIBUTE((warn_unused_result));
};
+ /**
+ * A MetadataPackageIDKey is a MetadataKey that has a PackageID as its
+ * value.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE MetadataPackageIDKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataPackageIDKey>
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataPackageIDKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const tr1::shared_ptr<const PackageID> value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataStringKey is a MetadataKey that has a std::string as its
+ * value.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE MetadataStringKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataStringKey>
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataStringKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const std::string value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataFSEntryKey is a MetadataKey that has an FSEntry as its value.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE MetadataFSEntryKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataFSEntryKey>
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataFSEntryKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const FSEntry value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataTimeKey is a MetadataKey that has a time_t as its value.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE MetadataTimeKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataTimeKey>
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataTimeKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const time_t value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataContentsKey is a MetadataKey that holds a Contents heirarchy.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE MetadataContentsKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataContentsKey>
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataContentsKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const tr1::shared_ptr<const Contents> value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataRepositoryMaskInfoKey is a MetadataKey that holds
+ * RepositoryMaskInfo as its value.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE MetadataRepositoryMaskInfoKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataRepositoryMaskInfoKey>
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataRepositoryMaskInfoKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const tr1::shared_ptr<const RepositoryMaskInfo> value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataSetKey is a MetadataKey that holds a Set of some kind of item
+ * as its value.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename C_>
class PALUDIS_VISIBLE MetadataSetKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataSetKey<C_> >
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataSetKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const tr1::shared_ptr<const C_> value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a single-line formatted version of our value, using the
+ * supplied Formatter to format individual items.
+ */
virtual std::string pretty_print_flat(const Formatter<typename C_::value_type> &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataSetKey<IUseFlagSet> is a MetadataKey that holds an IUseFlagSet
+ * as its value.
+ *
+ * This specialisation of MetadataSetKey provides an additional
+ * pretty_print_flat_with_comparison method.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
class PALUDIS_VISIBLE MetadataSetKey<IUseFlagSet> :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataSetKey<IUseFlagSet> >
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataSetKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const tr1::shared_ptr<const IUseFlagSet> value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a single-line formatted version of our value, using the
+ * supplied Formatter to format individual items.
+ */
virtual std::string pretty_print_flat(const Formatter<IUseFlag> &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a single-line formatted version of our value, using the
+ * supplied Formatter to format individual items, and the supplied
+ * PackageID to decorate using format::Added and format::Changed as
+ * appropriate.
+ */
virtual std::string pretty_print_flat_with_comparison(
const Environment * const,
const tr1::shared_ptr<const PackageID> &,
@@ -190,43 +387,98 @@ namespace paludis
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataSpecTreeKey<> is a MetadataKey that holds a spec tree of some
+ * kind as its value.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
template <typename C_>
class PALUDIS_VISIBLE MetadataSpecTreeKey :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataSpecTreeKey<C_> >
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataSpecTreeKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const tr1::shared_ptr<const typename C_::ConstItem> value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a multiline-line indented and formatted version of our
+ * value, using the supplied Formatter to format individual items.
+ */
virtual std::string pretty_print(const typename C_::Formatter &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a single-line formatted version of our value, using the
+ * supplied Formatter to format individual items.
+ */
virtual std::string pretty_print_flat(const typename C_::Formatter &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
+ /**
+ * A MetadataSpecTreeKey<FetchableURISpecTree> is a MetadataKey that holds
+ * a FetchableURISpecTree as its value.
+ *
+ * This specialisation of MetadataSpecTreeKey provides an additional
+ * initial_label method.
+ *
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
class PALUDIS_VISIBLE MetadataSpecTreeKey<FetchableURISpecTree> :
public MetadataKey,
public ConstAcceptInterfaceVisitsThis<MetadataKeyVisitorTypes, MetadataSpecTreeKey<FetchableURISpecTree> >
{
protected:
+ ///\name Basic operations
+ ///\{
+
MetadataSpecTreeKey(const std::string &, const std::string &, const MetadataKeyType);
+ ///\}
+
public:
+ /**
+ * Fetch our value.
+ */
virtual const tr1::shared_ptr<const FetchableURISpecTree::ConstItem> value() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a multiline-line indented and formatted version of our
+ * value, using the supplied Formatter to format individual items.
+ */
virtual std::string pretty_print(const FetchableURISpecTree::Formatter &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a single-line formatted version of our value, using the
+ * supplied Formatter to format individual items.
+ */
virtual std::string pretty_print_flat(const FetchableURISpecTree::Formatter &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ /**
+ * Return a URILabel that represents the initial label to use when
+ * deciding the behaviour of individual items in the heirarchy.
+ */
virtual const tr1::shared_ptr<const URILabel> initial_label() const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
};
diff --git a/paludis/metadata_key.se b/paludis/metadata_key.se
index 41c6564..c44df03 100644
--- a/paludis/metadata_key.se
+++ b/paludis/metadata_key.se
@@ -15,6 +15,9 @@ make_enum_MetadataKeyType()
* The significance of a MetadataKey to a user.
*
* \see MetadataKey
+ * \ingroup g_metadata_key
+ * \since 0.26
+ * \nosubgrouping
*/
END
}
diff --git a/paludis/package_id-fwd.hh b/paludis/package_id-fwd.hh
index 99dc8f1..6635f67 100644
--- a/paludis/package_id-fwd.hh
+++ b/paludis/package_id-fwd.hh
@@ -26,17 +26,44 @@
#include <paludis/util/sequence-fwd.hh>
#include <paludis/util/tr1_memory.hh>
+/** \file
+ * Forward declarations for paludis/package_id.hh .
+ *
+ * \ingroup g_package_id
+ */
+
namespace paludis
{
class PackageID;
class PackageIDSetComparator;
class PackageIDComparator;
+ /**
+ * A PackageIDSequence holds a collection of PackageID instances that may
+ * or may not have been ordered in a meaningful way.
+ *
+ * \ingroup g_package_id
+ * \since 0.26
+ */
typedef Sequence<tr1::shared_ptr<const PackageID> > PackageIDSequence;
+
+ /**
+ * A PackageIDSet holds a collection of PackageID instances that have no
+ * meaningful ordering.
+ *
+ * \ingroup g_package_id
+ * \since 0.26
+ */
typedef Set<tr1::shared_ptr<const PackageID>, PackageIDSetComparator> PackageIDSet;
#include <paludis/package_id-se.hh>
+ /**
+ * A PackageID can be written to a stream.
+ *
+ * \ingroup g_package_id
+ * \since 0.26
+ */
std::ostream & operator<< (std::ostream &, const PackageID &) PALUDIS_VISIBLE;
}
diff --git a/paludis/package_id.hh b/paludis/package_id.hh
index 9b835d5..e75f5fd 100644
--- a/paludis/package_id.hh
+++ b/paludis/package_id.hh
@@ -39,55 +39,249 @@
#include <libwrapiter/libwrapiter_forward_iterator-fwd.hh>
+/** \file
+ * Declarations for PackageID classes.
+ *
+ * \ingroup g_package_id
+ *
+ * \section Examples
+ *
+ * - \ref example_package_id.cc "example_package_id.cc" (for package IDs)
+ * - \ref example_action.cc "example_action.cc" (for actions)
+ * - \ref example_metadata_key.cc "example_metadata_key.cc" (for metadata keys)
+ * - \ref example_mask.cc "example_mask.cc" (for masks)
+ */
+
namespace paludis
{
class PackageDatabase;
+ /**
+ * A PackageID represents a unique package version in a particular
+ * Repository.
+ *
+ * All PackageID instances have some basic identification data:
+ *
+ * - A name
+ * - A version
+ * - A slot (which will be '0' if slots aren't used)
+ * - An owning repository
+ *
+ * It should be noted that the above together are not sufficient to uniquely
+ * identify a package. Some repositories support multiple slots per version
+ * of a package, and some repositories support additional affixes that
+ * prevent a package from being uniquely identifiable merely by the above.
+ *
+ * PackageID instances also have:
+ *
+ * - A collection of metadata keys. Some of these keys have a particular
+ * specific role in certain places. These can be fetched via blah_key()
+ * methods, all of which may return an empty pointer. Other keys have no
+ * meaningful global role, and can only be fetched using the iteration
+ * methods.
+ *
+ * - A collection (often empty) of masks. A masked package cannot be
+ * installed.
+ *
+ * A PackageID instance may support certain actions, which are represented
+ * via an Action subclass instance.
+ */
class PALUDIS_VISIBLE PackageID :
private InstantiationPolicy<PackageID, instantiation_method::NonCopyableTag>,
private PrivateImplementationPattern<PackageID>,
public equality_operators::HasEqualityOperators
{
protected:
+ /**
+ * Add a new MetadataKey, which must not use the same raw name as
+ * any previous MetadataKey added to this ID.
+ */
virtual void add_metadata_key(const tr1::shared_ptr<const MetadataKey> &) const;
+
+ /**
+ * Add a new Mask.
+ */
virtual void add_mask(const tr1::shared_ptr<const Mask> &) const;
+ /**
+ * This method will be called before any of the metadata key
+ * iteration methods does its work. It can be used by subclasses to
+ * implement as-needed loading of keys.
+ */
virtual void need_keys_added() const = 0;
+
+ /**
+ * This method will be called before any of the mask iteration
+ * methods does its work. It can be used by subclasses to implement
+ * as-needed loading of masks.
+ */
virtual void need_masks_added() const = 0;
public:
+ ///\name Basic operations
+ ///\{
+
PackageID();
virtual ~PackageID() = 0;
+ ///\}
+
+ /**
+ * Return our canonical string representation.
+ *
+ * This method (which is called by paludis::stringify()) should be
+ * used when outputting a PackageID or a PackageID's version. Some
+ * repositories need to display additional information to identify a
+ * package, so outputting merely the name and / or version may be
+ * insufficient.
+ */
virtual const std::string canonical_form(const PackageIDCanonicalForm) const = 0;
+ /**
+ * What is our package name?
+ *
+ * Use canonical_form instead for outputtting.
+ */
virtual const QualifiedPackageName name() const = 0;
+
+ /**
+ * What is our package version?
+ *
+ * Use canonical_form instead for outputtting.
+ */
virtual const VersionSpec version() const = 0;
+
+ /**
+ * What is our package's slot?
+ */
virtual const SlotName slot() const = 0;
+
+ /**
+ * What is our owning repository?
+ */
virtual const tr1::shared_ptr<const Repository> repository() const = 0;
///\name Specific metadata keys
///\{
+ /**
+ * The virtual_for_key, if non-zero, indicates that we are an
+ * (old-style) virtual for another package. This affects dependency
+ * resolution.
+ */
virtual const tr1::shared_ptr<const MetadataPackageIDKey> virtual_for_key() const = 0;
+
+ /**
+ * The keywords_key, if non-zero, is used by FindUnusedPackagesTask
+ * to determine whether a package is unused.
+ */
virtual const tr1::shared_ptr<const MetadataSetKey<KeywordNameSet> > keywords_key() const = 0;
+
+ /**
+ * The iuse_key, if non-zero, is used when displaying single-line
+ * install-pretend output, and when resolving where DepList's
+ * DepListReinstallOption is dl_reinstall_if_use_changed.
+ */
virtual const tr1::shared_ptr<const MetadataSetKey<IUseFlagSet> > iuse_key() const = 0;
+
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<LicenseSpecTree> > license_key() const = 0;
+
+ /**
+ * The provide_key, if non-zero, indicates that a package provides
+ * certain old-style virtuals. This affects dependency resolution.
+ */
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<ProvideSpecTree> > provide_key() const = 0;
+
+ /**
+ * The contains_key, if non-zero, indicates that a package contains
+ * other packages. This affects dependency resolution. */
virtual const tr1::shared_ptr<const MetadataSetKey<PackageIDSequence> > contains_key() const = 0;
+
+ /**
+ * The contained_in_key, if non-zero, indicates that a package is
+ * contained in another package. This affects dependency resolution.
+ */
virtual const tr1::shared_ptr<const MetadataPackageIDKey> contained_in_key() const = 0;
+
+ /**
+ * The build_dependencies_key, if non-zero, indicates a package's
+ * build-time dependencies.
+ */
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > build_dependencies_key() const = 0;
+
+ /**
+ * The run_dependencies_key, if non-zero, indicates a package's
+ * run-time dependencies.
+ */
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > run_dependencies_key() const = 0;
+
+ /**
+ * The post_dependencies_key, if non-zero, indicates a package's
+ * post-merge dependencies.
+ */
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > post_dependencies_key() const = 0;
+
+ /**
+ * The suggested_dependencies_key, if non-zero, indicates a package's
+ * suggested post-merge dependencies.
+ */
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<DependencySpecTree> > suggested_dependencies_key() const = 0;
+
+ /**
+ * The src_uri_key, if non-zero, indicates files that have to be fetched
+ * in order to install a package.
+ */
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<FetchableURISpecTree> > src_uri_key() const = 0;
+
+ /**
+ * The homepage_key, if non-zero, describes a package's homepages.
+ */
virtual const tr1::shared_ptr<const MetadataSpecTreeKey<SimpleURISpecTree> > homepage_key() const = 0;
+
+ /**
+ * The short_description_key, if non-zero, provides a short (no more
+ * than a few hundred characters) description of a package.
+ */
virtual const tr1::shared_ptr<const MetadataStringKey> short_description_key() const = 0;
+
+ /**
+ * The long_description_key, if non-zero, provides a long
+ * description of a package.
+ */
virtual const tr1::shared_ptr<const MetadataStringKey> long_description_key() const = 0;
+
+ /**
+ * The contents_key, if non-zero, contains the contents of a
+ * package. For installed packages, this means the files installed;
+ * for installable packages, this means the files that will be
+ * installed (if known, which it may be for some binary packages).
+ */
virtual const tr1::shared_ptr<const MetadataContentsKey> contents_key() const = 0;
+
+ /**
+ * The installed_time_key, if non-zero, contains the time a package
+ * was installed. It affects dependency resolution if DepList is
+ * using dl_reinstall_scm_daily or dl_reinstall_scm_weekly.
+ */
virtual const tr1::shared_ptr<const MetadataTimeKey> installed_time_key() const = 0;
+
+ /**
+ * The source_origin_key, if non-zero, contains a string describing
+ * the source repository whence a package originated.
+ */
virtual const tr1::shared_ptr<const MetadataStringKey> source_origin_key() const = 0;
+
+ /**
+ * The binary_origin_key, if non-zero, contains a string describing
+ * the binary repository whence a package originated.
+ */
virtual const tr1::shared_ptr<const MetadataStringKey> binary_origin_key() const = 0;
+
+ /**
+ * The fs_location_key, if non-zero, indicates the filesystem
+ * location (for example, the ebuild file or VDB directory) that
+ * best describes the location of a PackageID.
+ */
virtual const tr1::shared_ptr<const MetadataFSEntryKey> fs_location_key() const = 0;
///\}
@@ -105,7 +299,20 @@ namespace paludis
///\name Actions
///\{
+ /**
+ * Do we support a particular action?
+ *
+ * Attempting to call perform_action with an unsupported action type
+ * will lead to an UnsupportedActionError. However, in performance
+ * critical code and in situations where creating a full Action
+ * subclass instance is non-trivial, supports_action is much
+ * simpler.
+ */
virtual bool supports_action(const SupportsActionTestBase &) const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+
+ /**
+ * Perform the specified action.
+ */
virtual void perform_action(Action &) const = 0;
///\}
@@ -116,8 +323,19 @@ namespace paludis
typedef libwrapiter::ForwardIterator<PackageID, tr1::shared_ptr<const Mask> > MasksConstIterator;
MasksConstIterator begin_masks() const PALUDIS_ATTRIBUTE((warn_unused_result));
MasksConstIterator end_masks() const PALUDIS_ATTRIBUTE((warn_unused_result));
+
+ /**
+ * Do we have any masks? Equivalent to begin_masks() != end_masks().
+ */
bool masked() const PALUDIS_ATTRIBUTE((warn_unused_result));
+ /**
+ * Invalidate any masks.
+ *
+ * PackageID implementations may cache masks. This can cause
+ * problems if the operating environment changes. Calling this
+ * method will clear any masks held by the PackageID.
+ */
virtual void invalidate_masks() const;
/**
@@ -163,24 +381,64 @@ namespace paludis
///\}
};
+ /**
+ * PackageID instances are equality-comparable.
+ *
+ * \ingroup g_package_id
+ * \since 0.26
+ */
bool operator== (const PackageID &, const PackageID &) PALUDIS_ATTRIBUTE((warn_unused_result)) PALUDIS_VISIBLE;
+ /**
+ * A comparison functor that uses PackageID::arbitrary_less_than_comparison
+ * to provide a meaningless but stable ordering for PackageIDSet.
+ *
+ * \ingroup g_package_id
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE PackageIDSetComparator
{
public:
+ /**
+ * Perform an arbitrary less-than comparison.
+ */
bool operator() (const tr1::shared_ptr<const PackageID> &,
const tr1::shared_ptr<const PackageID> &) const;
};
+ /**
+ * A comparison functor that provides a less-than comparison on PackageID
+ * instances according to, in order, their name, their version, their
+ * repository's importance according to the supplied PackageDatabase,
+ * and PackageID::arbitrary_less_than_comparison.
+ *
+ * \ingroup g_package_id
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE PackageIDComparator :
private PrivateImplementationPattern<PackageIDComparator>
{
public:
+ ///\name Standard library typedefs
+ ///\{
+
typedef bool result_type;
+ ///\}
+
+ ///\name Basic operations
+ ///\{
+
PackageIDComparator(const PackageDatabase * const);
~PackageIDComparator();
+ ///\}
+
+ /**
+ * Perform the less-than comparison.
+ */
bool operator() (const tr1::shared_ptr<const PackageID> &,
const tr1::shared_ptr<const PackageID> &) const;
};
diff --git a/paludis/package_id.se b/paludis/package_id.se
index fd47190..841acba 100644
--- a/paludis/package_id.se
+++ b/paludis/package_id.se
@@ -11,9 +11,13 @@ make_enum_PackageIDCanonicalForm()
doxygen_comment << "END"
/**
- * How to generate paludis::PackageID::canonical_form().
+ * What to include when generating the string for
+ * paludis::PackageID::canonical_form().
*
* \see PackageID
+ * \ingroup g_package_id
+ * \since 0.26
+ * \nosubgrouping
*/
END
}
diff --git a/paludis/repository-fwd.hh b/paludis/repository-fwd.hh
index e6c0606..f04bce8 100644
--- a/paludis/repository-fwd.hh
+++ b/paludis/repository-fwd.hh
@@ -23,6 +23,12 @@
#include <paludis/util/set-fwd.hh>
#include <paludis/util/tr1_memory.hh>
+/** \file
+ * Forward declarations for paludis/repository.hh .
+ *
+ * \ingroup g_repository
+ */
+
namespace paludis
{
class Environment;
@@ -52,9 +58,10 @@ namespace paludis
class MergeOptions;
/**
- * A set of destinations.
+ * A set of destinations, used to decide whether a PackageID can be
+ * installed to a particular Repository.
*
- * \ingroup grpdepresolver
+ * \ingroup g_repository
*/
typedef Set<paludis::tr1::shared_ptr<Repository> > DestinationsSet;
}
diff --git a/paludis/repository.cc b/paludis/repository.cc
index 5f98cb87..6612809 100644
--- a/paludis/repository.cc
+++ b/paludis/repository.cc
@@ -38,12 +38,6 @@
#include <algorithm>
#include <ctype.h>
-/** \file
- * Implementation of Repository.
- *
- * \ingroup grprepository
- */
-
using namespace paludis;
#include <paludis/repository-sr.cc>
diff --git a/paludis/repository.hh b/paludis/repository.hh
index 020200a..9e1ddfc 100644
--- a/paludis/repository.hh
+++ b/paludis/repository.hh
@@ -39,9 +39,13 @@
#include <libwrapiter/libwrapiter_forward_iterator-fwd.hh>
/** \file
- * Declarations for the Repository class.
+ * Declarations for Repository classes.
*
- * \ingroup grprepository
+ * \ingroup g_repository
+ *
+ * \section Examples
+ *
+ * - \ref example_repository.cc "example_repository.cc" (for package IDs)
*/
namespace paludis
@@ -53,7 +57,7 @@ namespace paludis
* A Repository provides a representation of a physical repository to a
* PackageDatabase.
*
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE Repository :
@@ -246,7 +250,7 @@ namespace paludis
* Interface for handling USE flags for the Repository class.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryUseInterface
@@ -360,7 +364,7 @@ namespace paludis
* Interface for handling actions for installed repositories.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryInstalledInterface
@@ -384,7 +388,7 @@ namespace paludis
* Interface for package sets for repositories.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositorySetsInterface
@@ -428,7 +432,7 @@ namespace paludis
* Interface for syncing for repositories.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositorySyncableInterface
@@ -464,7 +468,7 @@ namespace paludis
* Interface for world handling for repositories.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryWorldInterface
@@ -502,7 +506,7 @@ namespace paludis
* Interface for environment variable querying for repositories.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryEnvironmentVariableInterface
@@ -528,7 +532,7 @@ namespace paludis
* Interface for mirror querying for repositories.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryMirrorsInterface
@@ -559,7 +563,7 @@ namespace paludis
* Interface for repositories that define virtuals.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryVirtualsInterface
@@ -570,8 +574,6 @@ namespace paludis
/**
* A collection of virtuals.
- *
- * \ingroup grprepository
*/
typedef Sequence<RepositoryVirtualsEntry> VirtualsSequence;
@@ -590,7 +592,7 @@ namespace paludis
* Interface for repositories that can make virtuals on the fly.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryMakeVirtualsInterface
@@ -607,7 +609,7 @@ namespace paludis
* Interface for repositories that provide packages.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryProvidesInterface
@@ -618,8 +620,6 @@ namespace paludis
/**
* A collection of provided packages.
- *
- * \ingroup grprepository
*/
typedef Sequence<RepositoryProvidesEntry> ProvidesSequence;
@@ -638,7 +638,7 @@ namespace paludis
* Interface for repositories that can be used as an install destination.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryDestinationInterface
@@ -684,7 +684,7 @@ namespace paludis
* Interface for handling actions relating to licenses.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryLicensesInterface
@@ -723,8 +723,7 @@ namespace paludis
* Interface for handling ERepository specific functionality.
*
* \see Repository
- * \see ERepository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryEInterface
@@ -771,12 +770,15 @@ namespace paludis
* Interface for handling QA tasks.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryQAInterface
{
public:
+ /**
+ * Perform QA checks on the repository.
+ */
virtual void check_qa(
QAReporter &,
const QACheckProperties &,
@@ -785,14 +787,19 @@ namespace paludis
const FSEntry &
) const = 0;
+ ///\name Basic operations
+ ///\{
+
virtual ~RepositoryQAInterface();
+
+ ///\}
};
/**
* Interface for making and verifying Manifest2-style manifests
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryManifestInterface
@@ -804,14 +811,19 @@ namespace paludis
*/
virtual void make_manifest(const QualifiedPackageName &) = 0;
+ ///\name Basic operations
+ ///\{
+
virtual ~RepositoryManifestInterface();
+
+ ///\}
};
/**
* Interface for handling hooks.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryHookInterface
@@ -823,7 +835,12 @@ namespace paludis
virtual HookResult perform_hook(const Hook & hook) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ ///\name Basic operations
+ ///\{
+
virtual ~RepositoryHookInterface();
+
+ ///\}
};
}
diff --git a/paludis/repository.sr b/paludis/repository.sr
index 748255b..c6f0664 100644
--- a/paludis/repository.sr
+++ b/paludis/repository.sr
@@ -27,7 +27,7 @@ make_class_RepositoryCapabilities()
* Optional interfaces that may be provided by a Repository.
*
* \see Repository
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
END
@@ -51,6 +51,7 @@ make_class_RepositoryEInterfaceProfilesDescLine()
*
* \see Repository
* \see RepositoryEInterface
+ * \ingroup g_repository
* \nosubgrouping
*/
END
@@ -71,6 +72,7 @@ make_class_RepositoryProvidesEntry()
*
* \see Repository
* \see RepositoryProvidesInterface
+ * \ingroup g_repository
* \nosubgrouping
*/
END
@@ -91,6 +93,7 @@ make_class_RepositoryVirtualsEntry()
*
* \see Repository
* \see RepositoryVirtualsInterface
+ * \ingroup g_repository
* \nosubgrouping
*/
END
@@ -111,7 +114,7 @@ make_class_MergeOptions()
* Parameters for RepositoryDestinationInterface::merge.
*
* \see RepositoryDestinationInterface
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
END
diff --git a/paludis/stringify_formatter-fwd.hh b/paludis/stringify_formatter-fwd.hh
index d867c6c..7140349 100644
--- a/paludis/stringify_formatter-fwd.hh
+++ b/paludis/stringify_formatter-fwd.hh
@@ -20,6 +20,12 @@
#ifndef PALUDIS_GUARD_PALUDIS_STRINGIFY_FORMATTER_FWD_HH
#define PALUDIS_GUARD_PALUDIS_STRINGIFY_FORMATTER_FWD_HH 1
+/** \file
+ * Forward declarations for paludis/stringify_formatter.hh .
+ *
+ * \ingroup g_formatters
+ */
+
namespace paludis
{
class StringifyFormatter;
diff --git a/paludis/stringify_formatter-impl.hh b/paludis/stringify_formatter-impl.hh
index e4fd166..e271db5 100644
--- a/paludis/stringify_formatter-impl.hh
+++ b/paludis/stringify_formatter-impl.hh
@@ -24,8 +24,21 @@
#include <paludis/util/tr1_type_traits.hh>
#include <paludis/util/private_implementation_pattern-impl.hh>
+/** \file
+ * Implementation for paludis/stringify_formatter.hh .
+ *
+ * \ingroup g_formatters
+ */
+
namespace paludis
{
+ /**
+ * Implementation data for StringifyFormatter.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
template <>
struct Implementation<StringifyFormatter>
{
@@ -78,36 +91,80 @@ namespace paludis
}
};
+ /**
+ * Internal use by StringifyFormatter: get a CanFormat<> interface, or 0 if
+ * not implemented.
+ *
+ * \ingroup g_formatters
+ * \nosubgrouping
+ * \since 0.26
+ */
template <bool b_, typename T_>
struct StringifyFormatterGetForwarder
{
+ /**
+ * Get a CanFormat<> interface, or 0 if not implemented.
+ */
static const CanFormat<T_> * get(const CanFormat<T_> * const t)
{
return t;
}
};
+ /**
+ * Internal use by StringifyFormatter: get a CanFormat<> interface, or 0 if
+ * not implemented.
+ *
+ * \ingroup g_formatters
+ * \nosubgrouping
+ * \since 0.26
+ */
template <typename T_>
struct StringifyFormatterGetForwarder<false, T_>
{
+ /**
+ * Get a CanFormat<> interface, or 0 if not implemented.
+ */
static const CanFormat<T_> * get(const void * const)
{
return 0;
}
};
+ /**
+ * Internal use by StringifyFormatter: get a CanSpace<> interface, or 0 if
+ * not implemented.
+ *
+ * \ingroup g_formatters
+ * \nosubgrouping
+ * \since 0.26
+ */
template <bool b_>
struct StringifyFormatterGetSpaceForwarder
{
+ /**
+ * Get a CanSpace interface, or 0 if not implemented.
+ */
static const CanSpace * get(const CanSpace * const t)
{
return t;
}
};
+ /**
+ * Internal use by StringifyFormatter: get a CanSpace<> interface, or 0 if
+ * not implemented.
+ *
+ * \ingroup g_formatters
+ * \nosubgrouping
+ * \since 0.26
+ */
template <>
struct StringifyFormatterGetSpaceForwarder<false>
{
+ /**
+ * Get a CanSpace interface, or 0 if not implemented.
+ */
static const CanSpace * get(const void * const)
{
return 0;
diff --git a/paludis/stringify_formatter.hh b/paludis/stringify_formatter.hh
index 7f231e2..d6c027e 100644
--- a/paludis/stringify_formatter.hh
+++ b/paludis/stringify_formatter.hh
@@ -26,8 +26,36 @@
#include <paludis/dep_spec-fwd.hh>
#include <paludis/util/private_implementation_pattern.hh>
+/** \file
+ * Declarations for the StringifyFormatter class.
+ *
+ * \ingroup g_formatters
+ *
+ * \section Examples
+ *
+ * - \ref example_stringify_formatter.cc "example_stringify_formatter.cc"
+ * - \ref example_formatter.cc "example_formatter.cc"
+ */
+
namespace paludis
{
+ /**
+ * A StringifyFormatter is a Formatter that implements every format function
+ * by calling paludis::stringify().
+ *
+ * A StringifyFormatter can also act as a wrapper class around another
+ * Formatter. Any CanFormat<> interface implemented by that other formatter
+ * is used; any not implemented by the other formatter is implemented using
+ * paludis::stringify().
+ *
+ * Indenting is done via simple spaces; newlines are done via a newline
+ * character. Again, when used as a wrapper, this can be overridden by the
+ * wrapped class.
+ *
+ * \ingroup g_formatters
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE StringifyFormatter :
private PrivateImplementationPattern<StringifyFormatter>,
public CanFormat<UseFlagName>,
@@ -49,12 +77,21 @@ namespace paludis
StringifyFormatter(const StringifyFormatter &);
public:
+ ///\name Basic operations
+ ///\{
+
StringifyFormatter();
- template <typename T_> StringifyFormatter(const T_ &);
+ /**
+ * StringifyFormatter can be constructed as a wrapper around another
+ * formatter.
+ */
+ template <typename T_> explicit StringifyFormatter(const T_ &);
~StringifyFormatter();
+ ///\}
+
virtual std::string format(const UseFlagName &, const format::Enabled &) const;
virtual std::string format(const UseFlagName &, const format::Disabled &) const;
virtual std::string format(const UseFlagName &, const format::Forced &) const;