action.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2007, 2008, 2009 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_ACTION_HH
00021 #define PALUDIS_GUARD_PALUDIS_ACTION_HH 1
00022 
00023 #include <paludis/action-fwd.hh>
00024 #include <paludis/repository-fwd.hh>
00025 #include <paludis/package_id-fwd.hh>
00026 #include <paludis/util/attributes.hh>
00027 #include <paludis/util/simple_visitor.hh>
00028 #include <paludis/util/exception.hh>
00029 #include <paludis/util/private_implementation_pattern.hh>
00030 #include <paludis/util/sequence-fwd.hh>
00031 #include <paludis/util/named_value.hh>
00032 #include <paludis/util/fs_entry-fwd.hh>
00033 #include <paludis/output_manager-fwd.hh>
00034 #include <paludis/util/type_list.hh>
00035 #include <tr1/functional>
00036 
00037 /** \file
00038  * Declarations for action-related classes.
00039  *
00040  * \ingroup g_actions
00041  *
00042  * \section Examples
00043  *
00044  * - \ref example_action.cc "example_action.cc"
00045  */
00046 
00047 namespace paludis
00048 {
00049     namespace n
00050     {
00051         struct config_protect;
00052         struct destination;
00053         struct exclude_unmirrorable;
00054         struct failed_automatic_fetching;
00055         struct failed_integrity_checks;
00056         struct fetch_unneeded;
00057         struct if_for_install_id;
00058         struct ignore_for_unmerge;
00059         struct ignore_unfetched;
00060         struct is_overwrite;
00061         struct make_output_manager;
00062         struct perform_uninstall;
00063         struct replacing;
00064         struct requires_manual_fetching;
00065         struct safe_resume;
00066         struct target_file;
00067         struct want_phase;
00068     }
00069 
00070     /**
00071      * Options for a FetchAction.
00072      *
00073      * \see FetchAction
00074      * \ingroup g_actions
00075      * \since 0.30
00076      */
00077     struct FetchActionOptions
00078     {
00079         /**
00080          * \since 0.32
00081          */
00082         NamedValue<n::exclude_unmirrorable, bool> exclude_unmirrorable;
00083 
00084         NamedValue<n::fetch_unneeded, bool> fetch_unneeded;
00085 
00086         /**
00087          * Ignore any unfetched packages. Verify digests for anything that's
00088          * already there, and if we know for sure manual fetching will be
00089          * required, raise the appropriate error.
00090          *
00091          * \since 0.36
00092          */
00093         NamedValue<n::ignore_unfetched, bool> ignore_unfetched;
00094 
00095         /**
00096          * This is a function to avoid chicken / egg problems when using
00097          * Environment::create_output_manager.
00098          *
00099          * \since 0.36
00100          */
00101         NamedValue<n::make_output_manager, std::tr1::function<std::tr1::shared_ptr<OutputManager> (
00102                 const FetchAction &)> > make_output_manager;
00103 
00104 
00105         NamedValue<n::safe_resume, bool> safe_resume;
00106     };
00107 
00108     /**
00109      * Options for an InstallAction.
00110      *
00111      * \see InstallAction
00112      * \ingroup g_actions
00113      * \since 0.30
00114      */
00115     struct InstallActionOptions
00116     {
00117         NamedValue<n::destination, std::tr1::shared_ptr<Repository> > destination;
00118 
00119         /**
00120          * This is a function to avoid chicken / egg problems when using
00121          * Environment::create_output_manager.
00122          *
00123          * \since 0.36
00124          */
00125         NamedValue<n::make_output_manager, std::tr1::function<std::tr1::shared_ptr<OutputManager> (
00126                 const InstallAction &)> > make_output_manager;
00127 
00128         /**
00129          * Callback to carry out an uninstall, for replacing.
00130          *
00131          * Won't necessarily be used. Some repositories have special code paths
00132          * for reinstalls, and in some cases (e.g. accounts) an upgrade doesn't
00133          * remove the old version at all.
00134          *
00135          * \since 0.36
00136          */
00137         NamedValue<n::perform_uninstall, std::tr1::function<void (
00138                 const std::tr1::shared_ptr<const PackageID> &,
00139                 const UninstallActionOptions &
00140                 )> > perform_uninstall;
00141 
00142         /**
00143          * We must replace these.
00144          *
00145          * \since 0.36
00146          */
00147         NamedValue<n::replacing, std::tr1::shared_ptr<const PackageIDSequence> > replacing;
00148 
00149         NamedValue<n::want_phase, std::tr1::function<WantPhase (const std::string &)> > want_phase;
00150     };
00151 
00152     /**
00153      * Options for an UninstallAction.
00154      *
00155      * \see UninstallAction
00156      * \ingroup g_actions
00157      * \since 0.30
00158      */
00159     struct UninstallActionOptions
00160     {
00161         NamedValue<n::config_protect, std::string> config_protect;
00162 
00163         /**
00164          * If we're being uninstalled as part of an install, this is the ID
00165          * that's being installed. Otherwise null.
00166          *
00167          * \since 0.36
00168          */
00169         NamedValue<n::if_for_install_id, std::tr1::shared_ptr<const PackageID> > if_for_install_id;
00170 
00171         /**
00172          * Sometimes we never want to unmerge certain files.
00173          *
00174          * \since 0,38
00175          */
00176         NamedValue<n::ignore_for_unmerge, std::tr1::function<bool (const FSEntry &)> > ignore_for_unmerge;
00177 
00178         /**
00179          * Some repositories need to do special handlings for direct overwrites
00180          * (foo-1.2 replacing foo-1.2). Clients should set this to false.
00181          *
00182          * \since 0.36
00183          */
00184         NamedValue<n::is_overwrite, bool> is_overwrite;
00185 
00186         /**
00187          * This is a function to avoid chicken / egg problems when using
00188          * Environment::create_output_manager.
00189          *
00190          * \since 0.36
00191          */
00192         NamedValue<n::make_output_manager, std::tr1::function<std::tr1::shared_ptr<OutputManager> (
00193                 const UninstallAction &)> > make_output_manager;
00194     };
00195 
00196     /**
00197      * A failed fetch action part.
00198      *
00199      * \see FetchActionError
00200      * \ingroup g_actions
00201      * \since 0.30
00202      */
00203     struct FetchActionFailure
00204     {
00205         NamedValue<n::failed_automatic_fetching, bool> failed_automatic_fetching;
00206         NamedValue<n::failed_integrity_checks, std::string> failed_integrity_checks;
00207         NamedValue<n::requires_manual_fetching, bool> requires_manual_fetching;
00208         NamedValue<n::target_file, std::string> target_file;
00209     };
00210 
00211     /**
00212      * An Action represents an action that can be executed by a PackageID via
00213      * PackageID::perform_action.
00214      *
00215      * \since 0.26
00216      * \ingroup g_actions
00217      * \nosubgrouping
00218      */
00219     class PALUDIS_VISIBLE Action :
00220         public virtual DeclareAbstractAcceptMethods<Action, MakeTypeList<
00221             InstallAction, InstalledAction, UninstallAction, PretendAction, ConfigAction, FetchAction,
00222             InfoAction, PretendFetchAction>::Type>
00223     {
00224         public:
00225             ///\name Basic operations
00226             ///\{
00227 
00228             virtual ~Action() = 0;
00229 
00230             ///\}
00231     };
00232 
00233     /**
00234      * An InstallAction is used by InstallTask to perform a build / install on a
00235      * PackageID.
00236      *
00237      * \since 0.26
00238      * \ingroup g_actions
00239      * \nosubgrouping
00240      */
00241     class PALUDIS_VISIBLE InstallAction :
00242         public Action,
00243         private PrivateImplementationPattern<InstallAction>,
00244         public ImplementAcceptMethods<Action, InstallAction>
00245     {
00246         public:
00247             ///\name Basic operations
00248             ///\{
00249 
00250             InstallAction(const InstallActionOptions &);
00251             ~InstallAction();
00252 
00253             ///\}
00254 
00255             /// Options for the action.
00256             const InstallActionOptions & options;
00257     };
00258 
00259     /**
00260      * A FetchAction can be used to fetch source files for a PackageID using
00261      * PackageID::perform_action.
00262      *
00263      * \since 0.26
00264      * \ingroup g_actions
00265      * \nosubgrouping
00266      */
00267     class PALUDIS_VISIBLE FetchAction :
00268         public Action,
00269         private PrivateImplementationPattern<FetchAction>,
00270         public ImplementAcceptMethods<Action, FetchAction>
00271     {
00272         public:
00273             ///\name Basic operations
00274             ///\{
00275 
00276             FetchAction(const FetchActionOptions &);
00277             ~FetchAction();
00278 
00279             ///\}
00280 
00281             /// Options for the action.
00282             const FetchActionOptions & options;
00283     };
00284 
00285     /**
00286      * An UninstallAction is used by UninstallTask to uninstall a PackageID.
00287      *
00288      * \since 0.26
00289      * \ingroup g_actions
00290      * \nosubgrouping
00291      */
00292     class PALUDIS_VISIBLE UninstallAction :
00293         public Action,
00294         private PrivateImplementationPattern<UninstallAction>,
00295         public ImplementAcceptMethods<Action, UninstallAction>
00296     {
00297         public:
00298             ///\name Basic operations
00299             ///\{
00300 
00301             UninstallAction(const UninstallActionOptions &);
00302             ~UninstallAction();
00303 
00304             ///\}
00305 
00306             /// Options for the action.
00307             const UninstallActionOptions & options;
00308     };
00309 
00310     /**
00311      * InstalledAction is a dummy action used by SupportsActionTest and
00312      * query::SupportsAction to determine whether a PackageID is installed.
00313      *
00314      * Performing an InstalledAction does not make sense and will do nothing.
00315      *
00316      * \since 0.26
00317      * \ingroup g_actions
00318      * \nosubgrouping
00319      */
00320     class PALUDIS_VISIBLE InstalledAction :
00321         public Action,
00322         public ImplementAcceptMethods<Action, InstalledAction>
00323     {
00324     };
00325 
00326     /**
00327      * Options for a PretendAction.
00328      *
00329      * \see PretendAction
00330      * \ingroup g_actions
00331      * \since 0.36
00332      */
00333     struct PretendActionOptions
00334     {
00335         /**
00336          * This is a function to avoid chicken / egg problems when using
00337          * Environment::create_output_manager.
00338          *
00339          * \since 0.36
00340          */
00341         NamedValue<n::make_output_manager, std::tr1::function<std::tr1::shared_ptr<OutputManager> (
00342                 const PretendAction &)> > make_output_manager;
00343     };
00344 
00345     /**
00346      * A PretendAction is used by InstallTask to handle install-pretend-phase
00347      * checks on a PackageID.
00348      *
00349      * \since 0.26
00350      * \ingroup g_actions
00351      * \nosubgrouping
00352      */
00353     class PALUDIS_VISIBLE PretendAction :
00354         public Action,
00355         private PrivateImplementationPattern<PretendAction>,
00356         public ImplementAcceptMethods<Action, PretendAction>
00357     {
00358         public:
00359             ///\name Basic operations
00360             ///\{
00361 
00362             /**
00363              * \since 0.36
00364              */
00365             PretendAction(const PretendActionOptions &);
00366             ~PretendAction();
00367 
00368             ///\}
00369 
00370             /// Did our pretend phase fail?
00371             bool failed() const PALUDIS_ATTRIBUTE((warn_unused_result));
00372 
00373             /// Mark the action as failed.
00374             void set_failed();
00375 
00376             /**
00377              * \since 0.36
00378              */
00379             const PretendActionOptions & options;
00380     };
00381 
00382     /**
00383      * A PretendFetchAction is used to get information about a fetch that will take
00384      * place on a PackageID.
00385      *
00386      * \since 0.26
00387      * \ingroup g_actions
00388      * \nosubgrouping
00389      */
00390     class PALUDIS_VISIBLE PretendFetchAction :
00391         public Action,
00392         private PrivateImplementationPattern<PretendFetchAction>,
00393         public ImplementAcceptMethods<Action, PretendFetchAction>
00394     {
00395         public:
00396             ///\name Basic operations
00397             ///\{
00398 
00399             PretendFetchAction(const FetchActionOptions &);
00400             ~PretendFetchAction();
00401 
00402             ///\}
00403 
00404             /// Options for the FetchAction we will use.
00405             const FetchActionOptions & options;
00406 
00407             /// Signal that we will fetch a particular file.
00408             virtual void will_fetch(const FSEntry & destination, const unsigned long size_in_bytes) = 0;
00409     };
00410 
00411     /**
00412      * Options for a ConfigAction.
00413      *
00414      * \see ConfigAction
00415      * \ingroup g_actions
00416      * \since 0.36
00417      */
00418     struct ConfigActionOptions
00419     {
00420         /**
00421          * This is a function to avoid chicken / egg problems when using
00422          * Environment::create_output_manager.
00423          *
00424          * \since 0.36
00425          */
00426         NamedValue<n::make_output_manager, std::tr1::function<std::tr1::shared_ptr<OutputManager> (
00427                 const ConfigAction &)> > make_output_manager;
00428     };
00429 
00430     /**
00431      * A ConfigAction is used via PackageID::perform_action to execute
00432      * post-install configuration (for example, via 'paludis --config')
00433      * on a PackageID.
00434      *
00435      * \since 0.26
00436      * \ingroup g_actions
00437      * \nosubgrouping
00438      */
00439     class PALUDIS_VISIBLE ConfigAction :
00440         public Action,
00441         private PrivateImplementationPattern<ConfigAction>,
00442         public ImplementAcceptMethods<Action, ConfigAction>
00443     {
00444         public:
00445             ///\name Basic operations
00446             ///\{
00447 
00448             /**
00449              * \since 0.36
00450              */
00451             ConfigAction(const ConfigActionOptions &);
00452             ~ConfigAction();
00453 
00454             ///\}
00455 
00456             /**
00457              * \since 0.36
00458              */
00459             const ConfigActionOptions & options;
00460     };
00461 
00462     /**
00463      * Options for an InfoAction.
00464      *
00465      * \see InfoAction
00466      * \ingroup g_actions
00467      * \since 0.36
00468      */
00469     struct InfoActionOptions
00470     {
00471         /**
00472          * This is a function to avoid chicken / egg problems when using
00473          * Environment::create_output_manager.
00474          *
00475          * \since 0.36
00476          */
00477         NamedValue<n::make_output_manager, std::tr1::function<std::tr1::shared_ptr<OutputManager> (
00478                 const InfoAction &)> > make_output_manager;
00479     };
00480 
00481     /**
00482      * An InfoAction is used via PackageID::perform_action to execute
00483      * additional information (for example, via 'paludis --info')
00484      * on a PackageID.
00485      *
00486      * This action potentially makes sense for both installed and
00487      * installable packages. Unlike Ebuild EAPI-0 'pkg_info', this
00488      * action is not specifically tied to installed packages.
00489      *
00490      * \since 0.26
00491      * \ingroup g_actions
00492      * \nosubgrouping
00493      */
00494     class PALUDIS_VISIBLE InfoAction:
00495         public Action,
00496         private PrivateImplementationPattern<InfoAction>,
00497         public ImplementAcceptMethods<Action, InfoAction>
00498     {
00499         public:
00500             ///\name Basic operations
00501             ///\{
00502 
00503             /**
00504              * \since 0.36
00505              */
00506             InfoAction(const InfoActionOptions &);
00507 
00508             ~InfoAction();
00509 
00510             ///\}
00511 
00512             /**
00513              * \since 0.36
00514              */
00515             const InfoActionOptions & options;
00516     };
00517 
00518     /**
00519      * Base class for SupportsActionTest<>.
00520      *
00521      * \see SupportsActionTest<>
00522      * \since 0.26
00523      * \ingroup g_actions
00524      * \nosubgrouping
00525      */
00526     class PALUDIS_VISIBLE SupportsActionTestBase :
00527         public virtual DeclareAbstractAcceptMethods<SupportsActionTestBase, MakeTypeList<
00528             SupportsActionTest<InstallAction>, SupportsActionTest<InstalledAction>, SupportsActionTest<UninstallAction>,
00529             SupportsActionTest<PretendAction>, SupportsActionTest<ConfigAction>, SupportsActionTest<FetchAction>,
00530             SupportsActionTest<InfoAction>, SupportsActionTest<PretendFetchAction> >::Type>
00531     {
00532         public:
00533             virtual ~SupportsActionTestBase() = 0;
00534     };
00535 
00536     /**
00537      * Instantiated with an Action subclass as its template parameter,
00538      * SupportsActionTest<> is used by PackageID::supports_action and
00539      * Repository::some_ids_might_support_action to query whether a
00540      * particular action is supported by that PackageID or potentially
00541      * supported by some IDs in that Repository.
00542      *
00543      * Use of a separate class, rather than a mere Action, avoids the
00544      * need to create bogus options for the more complicated Action
00545      * subclasses.
00546      *
00547      * \since 0.26
00548      * \ingroup g_actions
00549      * \nosubgrouping
00550      */
00551     template <typename A_>
00552     class PALUDIS_VISIBLE SupportsActionTest :
00553         public SupportsActionTestBase,
00554         public ImplementAcceptMethods<SupportsActionTestBase, SupportsActionTest<A_> >
00555     {
00556     };
00557 
00558     /**
00559      * An Action can be written to a std::ostream.
00560      *
00561      * \since 0.26
00562      * \ingroup g_actions
00563      * \nosubgrouping
00564      */
00565     std::ostream & operator<< (std::ostream &, const Action &) PALUDIS_VISIBLE;
00566 
00567     /**
00568      * Parent class for Action related errors.
00569      *
00570      * \ingroup g_actions
00571      * \ingroup g_exceptions
00572      * \since 0.26
00573      * \nosubgrouping
00574      */
00575     class PALUDIS_VISIBLE ActionError :
00576         public Exception
00577     {
00578         public:
00579             ///\name Basic operations
00580             ///\{
00581 
00582             ActionError(const std::string & msg) throw ();
00583 
00584             ///\}
00585     };
00586 
00587     /**
00588      * Thrown if a PackageID is asked to perform an Action that it does
00589      * not support.
00590      *
00591      * \ingroup g_exceptions
00592      * \ingroup g_actions
00593      * \since 0.26
00594      * \nosubgrouping
00595      */
00596     class PALUDIS_VISIBLE UnsupportedActionError :
00597         public ActionError
00598     {
00599         public:
00600             ///\name Basic operations
00601             ///\{
00602 
00603             UnsupportedActionError(const PackageID &, const Action &) throw ();
00604 
00605             ///\}
00606     };
00607 
00608     /**
00609      * Thrown if a PackageID fails to perform an InstallAction.
00610      *
00611      * \ingroup g_exceptions
00612      * \ingroup g_actions
00613      * \since 0.26
00614      * \nosubgrouping
00615      */
00616     class PALUDIS_VISIBLE InstallActionError : public ActionError
00617     {
00618         public:
00619             ///\name Basic operations
00620             ///\{
00621 
00622             InstallActionError(const std::string & msg) throw ();
00623 
00624             ///\}
00625     };
00626 
00627     /**
00628      * Thrown if a PackageID fails to perform a FetchAction.
00629      *
00630      * \ingroup g_exceptions
00631      * \ingroup g_actions
00632      * \since 0.26
00633      * \nosubgrouping
00634      */
00635     class PALUDIS_VISIBLE FetchActionError :
00636         public ActionError
00637     {
00638         private:
00639             const std::tr1::shared_ptr<const Sequence<FetchActionFailure> > _failures;
00640 
00641         public:
00642             ///\name Basic operations
00643             ///\{
00644 
00645             FetchActionError(const std::string &) throw ();
00646             FetchActionError(const std::string &, const std::tr1::shared_ptr<const Sequence<FetchActionFailure> > &) throw ();
00647             ~FetchActionError() throw ();
00648 
00649             ///\}
00650 
00651             /// More information about failed fetches.
00652             const std::tr1::shared_ptr<const Sequence<FetchActionFailure> > failures() const PALUDIS_ATTRIBUTE((warn_unused_result));
00653     };
00654 
00655     /**
00656      * Thrown if a PackageID fails to perform an UninstallAction.
00657      *
00658      * \ingroup g_exceptions
00659      * \ingroup g_actions
00660      * \since 0.26
00661      * \nosubgrouping
00662      */
00663     class PALUDIS_VISIBLE UninstallActionError : public ActionError
00664     {
00665         public:
00666             ///\name Basic operations
00667             ///\{
00668 
00669             UninstallActionError(const std::string & msg) throw ();
00670 
00671             ///\}
00672     };
00673 
00674     /**
00675      * Thrown if a PackageID fails to perform a ConfigAction.
00676      *
00677      * \ingroup g_exceptions
00678      * \ingroup g_actions
00679      * \since 0.26
00680      * \nosubgrouping
00681      */
00682     class PALUDIS_VISIBLE ConfigActionError : public ActionError
00683     {
00684         public:
00685             ///\name Basic operations
00686             ///\{
00687 
00688             ConfigActionError(const std::string & msg) throw ();
00689 
00690             ///\}
00691     };
00692 
00693     /**
00694      * Thrown if a PackageID fails to perform an InfoAction.
00695      *
00696      * \ingroup g_exceptions
00697      * \ingroup g_actions
00698      * \since 0.26
00699      * \nosubgrouping
00700      */
00701     class PALUDIS_VISIBLE InfoActionError : public ActionError
00702     {
00703         public:
00704             ///\name Basic operations
00705             ///\{
00706 
00707             InfoActionError(const std::string & msg) throw ();
00708 
00709             ///\}
00710     };
00711 
00712 #ifdef PALUDIS_HAVE_EXTERN_TEMPLATE
00713     extern template class PrivateImplementationPattern<FetchAction>;
00714     extern template class PrivateImplementationPattern<InstallAction>;
00715     extern template class PrivateImplementationPattern<PretendAction>;
00716     extern template class PrivateImplementationPattern<PretendFetchAction>;
00717     extern template class PrivateImplementationPattern<UninstallAction>;
00718     extern template class PrivateImplementationPattern<InfoAction>;
00719     extern template class PrivateImplementationPattern<ConfigAction>;
00720 #endif
00721 }
00722 
00723 #endif

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