package_database.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2005, 2006, 2007, 2008 Ciaran McCreesh
00005  *
00006  * This file is part of the Paludis package manager. Paludis is free software;
00007  * you can redistribute it and/or modify it under the terms of the GNU General
00008  * Public License version 2, as published by the Free Software Foundation.
00009  *
00010  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
00011  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00012  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00013  * details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
00017  * Place, Suite 330, Boston, MA  02111-1307  USA
00018  */
00019 
00020 #ifndef PALUDIS_GUARD_PALUDIS_PACKAGE_DATABASE_HH
00021 #define PALUDIS_GUARD_PALUDIS_PACKAGE_DATABASE_HH 1
00022 
00023 #include <paludis/package_database-fwd.hh>
00024 #include <paludis/dep_spec.hh>
00025 #include <paludis/name.hh>
00026 #include <paludis/repository.hh>
00027 #include <paludis/selection-fwd.hh>
00028 #include <paludis/filter-fwd.hh>
00029 #include <paludis/util/exception.hh>
00030 #include <paludis/util/instantiation_policy.hh>
00031 #include <paludis/util/join.hh>
00032 #include <paludis/util/private_implementation_pattern.hh>
00033 #include <paludis/util/stringify.hh>
00034 #include <paludis/util/wrapped_forward_iterator-fwd.hh>
00035 #include <paludis/version_spec.hh>
00036 #include <paludis/contents.hh>
00037 
00038 #include <iosfwd>
00039 
00040 /** \file
00041  * Declarations for PackageDatabase.
00042  *
00043  * \ingroup g_package_database
00044  *
00045  * \section Examples
00046  *
00047  * - \ref example_package_database.cc "example_package_database.cc"
00048  */
00049 
00050 namespace paludis
00051 {
00052     /**
00053      * A PackageDatabaseError is an error that occurs when performing some
00054      * operation upon a PackageDatabase.
00055      *
00056      * \ingroup g_exceptions
00057      * \ingroup g_package_database
00058      */
00059     class PALUDIS_VISIBLE PackageDatabaseError :
00060         public Exception
00061     {
00062         protected:
00063             /**
00064              * Constructor.
00065              */
00066             PackageDatabaseError(const std::string & message) throw ();
00067     };
00068 
00069     /**
00070      * A PackageDatabaseLookupError descendent is thrown if an error occurs
00071      * when looking for something in a PackageDatabase.
00072      *
00073      * \ingroup g_exceptions
00074      * \ingroup g_package_database
00075      */
00076     class PALUDIS_VISIBLE PackageDatabaseLookupError :
00077         public PackageDatabaseError
00078     {
00079         protected:
00080             /**
00081              * Constructor.
00082              */
00083             PackageDatabaseLookupError(const std::string & message) throw ();
00084     };
00085 
00086     /**
00087      * Thrown if a PackageDatabase query results in more than one matching
00088      * Package.
00089      *
00090      * \ingroup g_exceptions
00091      * \ingroup g_package_database
00092      * \nosubgrouping
00093      */
00094     class PALUDIS_VISIBLE AmbiguousPackageNameError :
00095         public PackageDatabaseLookupError
00096     {
00097         private:
00098             struct NameData;
00099             NameData * const _name_data;
00100 
00101             std::string _name;
00102 
00103         public:
00104             ///\name Basic operations
00105             ///\{
00106 
00107             template <typename I_>
00108             AmbiguousPackageNameError(const std::string & name,
00109                     I_ begin, const I_ end) throw ();
00110 
00111             AmbiguousPackageNameError(const AmbiguousPackageNameError &);
00112 
00113             virtual ~AmbiguousPackageNameError() throw ();
00114 
00115             ///\}
00116 
00117             /**
00118              * The name of the package.
00119              */
00120             const std::string & name() const PALUDIS_ATTRIBUTE((warn_unused_result));
00121 
00122             ///\name Iterate over possible matches
00123             ///\{
00124 
00125             struct OptionsConstIteratorTag;
00126             typedef WrappedForwardIterator<OptionsConstIteratorTag,
00127                     const std::string> OptionsConstIterator;
00128 
00129             OptionsConstIterator begin_options() const PALUDIS_ATTRIBUTE((warn_unused_result));
00130             OptionsConstIterator end_options() const PALUDIS_ATTRIBUTE((warn_unused_result));
00131 
00132             ///\}
00133     };
00134 
00135     /**
00136      * Thrown if a Repository with the same name as an existing member is added
00137      * to a PackageDatabase.
00138      *
00139      * \ingroup g_exceptions
00140      * \ingroup g_package_database
00141      * \nosubgrouping
00142      */
00143     class PALUDIS_VISIBLE DuplicateRepositoryError :
00144         public PackageDatabaseError
00145     {
00146         public:
00147             /**
00148              * Constructor.
00149              */
00150             DuplicateRepositoryError(const std::string & name) throw ();
00151     };
00152 
00153     /**
00154      * Thrown if there is no Package in a PackageDatabase with the given
00155      * name.
00156      *
00157      * \ingroup g_exceptions
00158      * \ingroup g_package_database
00159      */
00160     class PALUDIS_VISIBLE NoSuchPackageError :
00161         public PackageDatabaseLookupError
00162     {
00163         private:
00164             std::string _name;
00165 
00166         public:
00167             ///\name Basic operations
00168             ///\{
00169 
00170             NoSuchPackageError(const std::string & name) throw ();
00171 
00172             virtual ~NoSuchPackageError() throw ()
00173             {
00174             }
00175 
00176             ///\}
00177 
00178             /**
00179              * Name of the package.
00180              */
00181             const std::string & name() const
00182             {
00183                 return _name;
00184             }
00185     };
00186 
00187     /**
00188      * Thrown if there is no Repository in a RepositoryDatabase with the given
00189      * name.
00190      *
00191      * \ingroup g_exceptions
00192      * \ingroup g_package_database
00193      */
00194     class PALUDIS_VISIBLE NoSuchRepositoryError : public PackageDatabaseLookupError
00195     {
00196         private:
00197             const RepositoryName _name;
00198 
00199         public:
00200             ///\name Basic operations
00201             ///\{
00202 
00203             NoSuchRepositoryError(const RepositoryName &) throw ();
00204 
00205             ~NoSuchRepositoryError() throw ();
00206 
00207             ///\}
00208 
00209             /**
00210              * The name of our repository.
00211              */
00212             RepositoryName name() const;
00213     };
00214 
00215     /**
00216      * A PackageDatabase, which is owned by an Environment, contains a number of
00217      * Repository instances and supports various querying methods.
00218      *
00219      * \ingroup g_package_database
00220      */
00221     class PALUDIS_VISIBLE PackageDatabase :
00222         private PrivateImplementationPattern<PackageDatabase>,
00223         private InstantiationPolicy<PackageDatabase, instantiation_method::NonCopyableTag>
00224     {
00225         private:
00226             static const Filter & all_filter() PALUDIS_ATTRIBUTE((warn_unused_result));
00227 
00228         public:
00229             ///\name Basic operations
00230             ///\{
00231 
00232             explicit PackageDatabase(const Environment * const);
00233 
00234             ~PackageDatabase();
00235 
00236             ///\}
00237 
00238             /**
00239              * Add a repository.
00240              *
00241              * \exception DuplicateRepositoryError if a Repository with the
00242              * same name as the new Repository already exists in our
00243              * collection.
00244              */
00245             void add_repository(int importance, const std::tr1::shared_ptr<Repository>);
00246 
00247             /**
00248              * Fetch a named repository.
00249              */
00250             std::tr1::shared_ptr<const Repository> fetch_repository(const RepositoryName &) const
00251                 PALUDIS_ATTRIBUTE((warn_unused_result));
00252 
00253             /**
00254              * Fetch a named repository.
00255              */
00256             std::tr1::shared_ptr<Repository> fetch_repository(const RepositoryName &)
00257                 PALUDIS_ATTRIBUTE((warn_unused_result));
00258 
00259             /**
00260              * Do we have a named repository?
00261              */
00262             bool has_repository_named(const RepositoryName &) const
00263                 PALUDIS_ATTRIBUTE((warn_unused_result));
00264 
00265             /**
00266              * Fetch the name of our 'favourite' repository (if a repository's
00267              * name matches this when doing a graphical display, the repository
00268              * name part may be omitted).
00269              *
00270              * Note that this is the repository with the <i>lowest</i> importance
00271              * that is not a virtuals or installed_virtuals repository.
00272              */
00273             RepositoryName favourite_repository() const
00274                 PALUDIS_ATTRIBUTE((warn_unused_result));
00275 
00276             /**
00277              * Disambiguate a package name.  If a filter is specified,
00278              * limit the potential results to packages that match.
00279              *
00280              * \throw AmbiguousPackageNameError if there is no unambiguous
00281              * disambiguation.
00282              */
00283             QualifiedPackageName fetch_unique_qualified_package_name(
00284                     const PackageNamePart &, const Filter & = all_filter()) const
00285                 PALUDIS_ATTRIBUTE((warn_unused_result));
00286 
00287             /**
00288              * Return true if the first repository is more important than the second.
00289              */
00290             bool more_important_than(const RepositoryName &, const RepositoryName &) const
00291                 PALUDIS_ATTRIBUTE((warn_unused_result));
00292 
00293             ///\name Iterate over our repositories
00294             ///\{
00295 
00296             struct RepositoryConstIteratorTag;
00297             typedef WrappedForwardIterator<RepositoryConstIteratorTag, const std::tr1::shared_ptr<Repository> > RepositoryConstIterator;
00298 
00299             RepositoryConstIterator begin_repositories() const
00300                 PALUDIS_ATTRIBUTE((warn_unused_result));
00301 
00302             RepositoryConstIterator end_repositories() const
00303                 PALUDIS_ATTRIBUTE((warn_unused_result));
00304 
00305             ///\}
00306     };
00307 }
00308 
00309 #endif

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