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