aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-04 01:36:48 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-04 01:36:48 +0000
commitc042cb97554ed926b61dae5ca8f956c1fe80122d (patch)
tree09f12b15b5f04be550986aa2a82257c1d17b5758
parentf5410cba716ac552b6d6deebd8d4c3a2330cd149 (diff)
downloadpaludis-c042cb97554ed926b61dae5ca8f956c1fe80122d.tar.gz
paludis-c042cb97554ed926b61dae5ca8f956c1fe80122d.tar.xz
More doxygen work
-rw-r--r--doc/examples/Makefile.am10
-rw-r--r--doc/examples/example_dep_label.cc3
-rw-r--r--doc/examples/example_dep_tree.cc242
-rw-r--r--paludis/dep_tree-fwd.hh6
-rw-r--r--paludis/dep_tree.hh146
5 files changed, 388 insertions, 19 deletions
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index 2a4d453..645c085 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -14,7 +14,8 @@ noinst_PROGRAMS = \
example_action \
example_contents \
example_dep_label \
- example_dep_spec
+ example_dep_spec \
+ example_dep_tree
EXTRA_DIST = $(noinst_SCRIPTS)
@@ -59,6 +60,13 @@ example_dep_spec_LDFLAGS = \
$(top_builddir)/paludis/args/libpaludisargs.la \
$(top_builddir)/paludis/environments/libpaludisenvironments.la
+example_dep_tree_SOURCES = example_dep_tree.cc
+example_dep_tree_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la \
+ $(top_builddir)/paludis/environments/libpaludisenvironments.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_dep_label.cc b/doc/examples/example_dep_label.cc
index 920cd1e..344a8b6 100644
--- a/doc/examples/example_dep_label.cc
+++ b/doc/examples/example_dep_label.cc
@@ -12,6 +12,9 @@
* This example demonstrates how to handle dependency labels. It produces a
* summary of distfiles for all installed packages, together with a notice of
* whether that distfile is fetch-restricted.
+ *
+ * See \ref example_dep_tree.cc "example_dep_tree.cc" for trees.
+ * See \ref example_dep_spec.cc "example_dep_spec.cc" for specs.
*/
#include <paludis/paludis.hh>
diff --git a/doc/examples/example_dep_tree.cc b/doc/examples/example_dep_tree.cc
new file mode 100644
index 0000000..3d6c7ae
--- /dev/null
+++ b/doc/examples/example_dep_tree.cc
@@ -0,0 +1,242 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_dep_tree.cc "example_dep_tree.cc" .
+ *
+ * \ingroup g_dep_spec
+ */
+
+/** \example example_dep_tree.cc
+ *
+ * This example demonstrates how to handle dependency specs. It looks through
+ * all installed packages, and picks out any package whose dependencies include
+ * 'app-arch/unzip', or whose fetchable files includes any with a '.zip'
+ * extension.
+ *
+ * See \ref example_dep_label.cc "example_dep_label.cc" for labels.
+ * See \ref example_dep_spec.cc "example_dep_spec.cc" for specs.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <algorithm>
+#include <cstdlib>
+#include <list>
+#include <map>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::setw;
+using std::left;
+
+/* We use this map to store accumulated results. The first item in the pair
+ * is whether we see a dependency, the second whether we see an extension. */
+typedef std::map<std::string, std::pair<bool, bool> > ResultsMap;
+
+namespace
+{
+ /* This visitor handles collection of packages with interesting
+ * dependencies. We use the ConstVisitor<>::VisitConstSequence helper mixin
+ * for AllDepSpec and AnyDepSpec, rather than explicitly visiting all the
+ * children manually. */
+ class DependenciesCollector :
+ public ConstVisitor<DependencySpecTree>,
+ public ConstVisitor<DependencySpecTree>::VisitConstSequence<DependenciesCollector, AllDepSpec>,
+ public ConstVisitor<DependencySpecTree>::VisitConstSequence<DependenciesCollector, AnyDepSpec>
+ {
+ private:
+ const tr1::shared_ptr<const Environment> _env;
+ const tr1::shared_ptr<const PackageID> _id;
+ ResultsMap & _results;
+
+ public:
+ DependenciesCollector(
+ const tr1::shared_ptr<const Environment> & e,
+ const tr1::shared_ptr<const PackageID> & i,
+ ResultsMap & r) :
+ _env(e),
+ _id(i),
+ _results(r)
+ {
+ }
+
+ using ConstVisitor<DependencySpecTree>::VisitConstSequence<DependenciesCollector, AllDepSpec>::visit_sequence;
+ using ConstVisitor<DependencySpecTree>::VisitConstSequence<DependenciesCollector, AnyDepSpec>::visit_sequence;
+
+ void visit_sequence(const UseDepSpec & u,
+ DependencySpecTree::ConstSequenceIterator cur,
+ DependencySpecTree::ConstSequenceIterator end)
+ {
+ /* Was this use flag enabled (or, if we're inverse, disabled)
+ * when we built this package? */
+ if (_env->query_use(u.flag(), *_id) ^ u.inverse())
+ std::for_each(cur, end, accept_visitor(*this));
+ }
+
+ void visit_leaf(const PackageDepSpec & spec)
+ {
+ /* spec.package_ptr() may return a zero pointer if it's a
+ * wildcarded dep. */
+ if (spec.package_ptr() && *spec.package_ptr() == QualifiedPackageName("app-arch/unzip"))
+ _results[stringify(*_id)].first = true;
+ }
+
+ void visit_leaf(const BlockDepSpec &)
+ {
+ /* Not interested */
+ }
+
+ void visit_leaf(const DependencyLabelsDepSpec &)
+ {
+ /* Not interested */
+ }
+ };
+
+ /* This visitor handles collection of packages with interesting
+ * filenames. Again, we use the ConstVisitor<>::VisitConstSequence helper mixin
+ * for AllDepSpec (AnyDepSpec is not allowed in a FetchableURISpecTree). */
+ class FileExtensionsCollector :
+ public ConstVisitor<FetchableURISpecTree>,
+ public ConstVisitor<FetchableURISpecTree>::VisitConstSequence<FileExtensionsCollector, AllDepSpec>
+ {
+ private:
+ const tr1::shared_ptr<const Environment> _env;
+ const tr1::shared_ptr<const PackageID> _id;
+ ResultsMap & _results;
+
+ public:
+ FileExtensionsCollector(
+ const tr1::shared_ptr<const Environment> & e,
+ const tr1::shared_ptr<const PackageID> & i,
+ ResultsMap & r) :
+ _env(e),
+ _id(i),
+ _results(r)
+ {
+ }
+
+ using ConstVisitor<FetchableURISpecTree>::VisitConstSequence<FileExtensionsCollector, AllDepSpec>::visit_sequence;
+
+ void visit_sequence(const UseDepSpec & u,
+ FetchableURISpecTree::ConstSequenceIterator cur,
+ FetchableURISpecTree::ConstSequenceIterator end)
+ {
+ /* Was this use flag enabled (or, if we're inverse, disabled)
+ * when we built this package? */
+ if (_env->query_use(u.flag(), *_id) ^ u.inverse())
+ std::for_each(cur, end, accept_visitor(*this));
+ }
+
+ void visit_leaf(const FetchableURIDepSpec & spec)
+ {
+ /* We need to be careful not to assume that the filename has
+ * an extension. */
+ std::string::size_type p(spec.filename().rfind('.'));
+ if ((std::string::npos != p) && (".zip" == spec.filename().substr(p)))
+ _results[stringify(*_id)].second = true;
+ }
+
+ void visit_leaf(const URILabelsDepSpec &)
+ {
+ /* Not interested */
+ }
+ };
+}
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_action", "EXAMPLE_ACTION_OPTIONS", "EXAMPLE_ACTION_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 all installed packages. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::SupportsAction<InstalledAction>(),
+ qo_order_by_version));
+
+ ResultsMap results;
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ /* Ignore old-style virtuals. */
+ if ((*i)->virtual_for_key())
+ continue;
+
+ /* Insert a default result for this ID */
+ results[stringify(**i)] = std::make_pair(false, false);
+
+ /* Create a visitor that collects 'app-arch/unzip' dependencies. */
+ DependenciesCollector dependencies_collector(env, *i, results);
+
+ /* IDs can potentially have four dependency-related keys. Each of
+ * these keys may return a zero pointer. If it doesn't, visit its
+ * value with our collector. */
+ if ((*i)->build_dependencies_key())
+ (*i)->build_dependencies_key()->value()->accept(dependencies_collector);
+ if ((*i)->run_dependencies_key())
+ (*i)->run_dependencies_key()->value()->accept(dependencies_collector);
+ if ((*i)->post_dependencies_key())
+ (*i)->post_dependencies_key()->value()->accept(dependencies_collector);
+ if ((*i)->suggested_dependencies_key())
+ (*i)->suggested_dependencies_key()->value()->accept(dependencies_collector);
+
+ /* Create a visitor that collects '.zip' file extenstions. */
+ FileExtensionsCollector extensions_collector(env, *i, results);
+
+ /* Again, we check for a zero pointer and visit otherwise: */
+ if ((*i)->src_uri_key())
+ (*i)->src_uri_key()->value()->accept(extensions_collector);
+ }
+
+ /* Display our results */
+ cout << left << setw(60) << "Package" << "| " << left << setw(4) << "Dep" << "| " << "Ext" << endl;
+ cout << std::string(60, '-') << "+" << std::string(4, '-') << "+" << std::string(4, '-') << endl;
+ for (ResultsMap::const_iterator r(results.begin()), r_end(results.end()) ;
+ r != r_end ; ++r)
+ cout << left << setw(60) << r->first << "| "
+ << left << setw(4) << (r->second.first ? "yes" : "no") << "| "
+ << left << setw(4) << (r->second.second ? "yes" : "no") << 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/dep_tree-fwd.hh b/paludis/dep_tree-fwd.hh
index 567a992..77bc988 100644
--- a/paludis/dep_tree-fwd.hh
+++ b/paludis/dep_tree-fwd.hh
@@ -20,6 +20,12 @@
#ifndef PALUDIS_GUARD_PALUDIS_DEP_TREE_FWD_HH
#define PALUDIS_GUARD_PALUDIS_DEP_TREE_FWD_HH 1
+/** \file
+ * Forward declarations for paludis/dep_tree.hh .
+ *
+ * \ingroup g_dep_spec
+ */
+
namespace paludis
{
struct GenericSpecTree;
diff --git a/paludis/dep_tree.hh b/paludis/dep_tree.hh
index 8aac3c3..43fc135 100644
--- a/paludis/dep_tree.hh
+++ b/paludis/dep_tree.hh
@@ -24,12 +24,30 @@
#include <paludis/dep_spec-fwd.hh>
#include <paludis/util/visitor.hh>
+/** \file
+ * Declarations for dependency spec trees.
+ *
+ * \ingroup g_dep_spec
+ *
+ * \section Examples
+ *
+ * - \ref example_dep_tree.cc "example_dep_tree.cc" (for specification trees)
+ * - \ref example_dep_spec.cc "example_dep_spec.cc" (for specifications)
+ * - \ref example_dep_label.cc "example_dep_label.cc" (for labels)
+ */
+
namespace paludis
{
/**
- * A generic DepSpec heirarchy.
+ * A generic dep tree heirarchy.
+ *
+ * Heirarchies conforming to this type will likely not ever be created.
+ * However, the heirarchy is useful for creating generic visitors that can
+ * handle any of the subheirarchies.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct GenericSpecTree :
VisitorTypes<
@@ -48,6 +66,14 @@ namespace paludis
ConstTreeSequence<GenericSpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * GenericSpecTree.
+ *
+ * \since 0.26
+ * \ingroup g_dep_spec
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
PlainTextDepSpec,
@@ -62,9 +88,11 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things meaningful for licenses.
+ * A heirarchy for licence specifications.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct LicenseSpecTree :
VisitorTypes<
@@ -76,6 +104,14 @@ namespace paludis
ConstTreeSequence<LicenseSpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * LicenseSpecTree.
+ *
+ * \since 0.26
+ * \ingroup g_dep_spec
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
LicenseDepSpec
@@ -83,9 +119,11 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things meaningful for fetchable URIs.
+ * A heirarchy for fetchable URI heirarchies.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct FetchableURISpecTree :
VisitorTypes<
@@ -97,6 +135,14 @@ namespace paludis
ConstTreeSequence<FetchableURISpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * FetchableURIDepSpec.
+ *
+ * \since 0.26
+ * \ingroup g_dep_spec
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
FetchableURIDepSpec,
@@ -105,9 +151,11 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things meaningful for simple URIs.
+ * A heirarchy for simple URI heirarchies.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct SimpleURISpecTree :
VisitorTypes<
@@ -118,6 +166,14 @@ namespace paludis
ConstTreeSequence<SimpleURISpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * SimpleURISpecTree.
+ *
+ * \since 0.26
+ * \ingroup g_dep_spec
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
SimpleURIDepSpec
@@ -125,9 +181,15 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things that can be flattened.
+ * A heirarchy of things that can be flattened.
+ *
+ * This heirarchy is not constructed; it is only used for declaring
+ * certain visitors (e.g. DepSpecFlattener).
*
- * \ingroup grpdepspecs
+ * \see DepSpecFlattener
+ * \since 0.26
+ * \ingroup g_dep_spec
+ * \nosubgrouping
*/
struct FlattenableSpecTree :
VisitorTypes<
@@ -143,6 +205,14 @@ namespace paludis
ConstTreeSequence<FlattenableSpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * FlattenableSpecTree.
+ *
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
PlainTextDepSpec,
@@ -155,9 +225,11 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things meaningful for provides.
+ * A heirarchy of provided packages.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct ProvideSpecTree :
VisitorTypes<
@@ -168,6 +240,14 @@ namespace paludis
ConstTreeSequence<ProvideSpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * ProvideSpecTree.
+ *
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
PackageDepSpec
@@ -175,9 +255,11 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things meaningful for restricts.
+ * A heirarchy of restrict keywords.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct RestrictSpecTree :
VisitorTypes<
@@ -188,6 +270,14 @@ namespace paludis
ConstTreeSequence<RestrictSpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * RestrictSpecTree.
+ *
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
PlainTextDepSpec
@@ -195,9 +285,11 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things meaningful for dependencies.
+ * A heirarchy for dependencies.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct DependencySpecTree :
VisitorTypes<
@@ -211,6 +303,14 @@ namespace paludis
ConstTreeSequence<DependencySpecTree, UseDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * DependencySpecTree.
+ *
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
+ */
typedef Formatter<
UseDepSpec,
PackageDepSpec,
@@ -220,9 +320,11 @@ namespace paludis
};
/**
- * A DepSpec heirarchy containing things meaningful for sets.
+ * A heirarchy for things that can be found in package sets.
*
- * \ingroup grpdepspecs
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
*/
struct SetSpecTree :
VisitorTypes<
@@ -232,6 +334,14 @@ namespace paludis
ConstTreeSequence<SetSpecTree, AllDepSpec>
>
{
+ /**
+ * A formatter that can handle any formattable type found in a
+ * SetSpecTree.
+ *
+ * \ingroup g_dep_spec
+ * \since 0.26
+ * \nosubgrouping
+ */
typedef Formatter<
PackageDepSpec
> Formatter;