Changeset 0c5eeb for src/Actions/MapOfActions.hpp

Timestamp:

Jun 25, 2010, 2:27:26 PM (15 years ago)

Author:

Tillmann Crueger <crueger@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

33d774, daa5f1

Parents:

0d1ad0 (diff), 326bbe (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'stable' into StructureRefactoring

File:

• src/Actions/MapOfActions.hpp (modified) (4 diffs)

src/Actions/MapOfActions.hpp ¶

@@ -11 +11 @@
 #include "Helpers/Assert.hpp"
 #include <boost/program_options.hpp>
+
 #include <map>
 #include <set>
@@ -20 +21 @@
 namespace po = boost::program_options;
 
+/** Central class for adding functionality to the code.
+ *
+ * In Molecuilder everything that can be done - such as adding atoms,
+ * translating molecules, saving bind information - is an Action.
+ *
+ * In order to reference Action's with what the user sees, this class is the
+ * mediator.
+ *
+ * An Action is described to the user by:
+ * -# a name (this is the most important information)
+ * -# a description
+ * -# a shortform (single letter for use on the command line)
+ * -# a text menu it resides in
+ * -# the type of its argument
+ * -# the command line category
+ *
+ * The Action::NAME is the most important information because every Action
+ * registers itself automatically with the ActionRegistry and can be retrieved
+ * therefrom and from this MapOfActions simply by knowing its name alone.
+ *
+ * In the constructor of MapOfActions all this is set.
+ *
+ * Note that Action will require input from the user. This is done via class
+ * Query.
+ *
+ * And note also that MapOfActions actually contains more than just all
+ * Actions: There are a number of names that actually are just arguments to
+ * actions (e.g. "output-file").
+ *
+ * <h1> Howto add an Action</h1>
+ *
+ * Let us assume your new action (class) is called SuperDuperAction, consisting
+ * of two files SuperDuperAction.cpp and SuperDuperAction.hpp.
+ *
+ * Furthermore, let's say you Action needs two values: a double value as a
+ * upper threshold and a string which is the name of the output file.
+ *
+ * <h2> Command Line preliminaries </h2>
+ *
+ * You have to decide whether (for the command line) it makes sense to have an
+ * extra argument requesting the arguments, or one should be the argument of
+ * your action. I.e. your action name is "super-duper", then the use may
+ * call your action like this:
+ *
+ * ./molecuilder --super-duper 4 --output-file test.dat
+ *
+ * Here, we have picked the threshold as the value for your action and the
+ * name of the output file is given by an additional argument. Of course,
+ * it can be the other way round or by two arguments such as here:
+ *
+ * ./molecuilder --super-duper --threshold 4 --output-file test.dat
+ *
+ * It depends on what possible arguments are already there (don't make up
+ * new ones if present ones actually make sense for your action) and which
+ * argument is more natural or closer to what your action does.
+ *
+ * <h2> Menu preliminaries </h2>
+ *
+ * Whatever you decide, your action will need some Query dialogs to request
+ * the necessary information from the user, either via a command line
+ * argument (--output-file) via a text dialog (referenced by "output-file")
+ * or via a graphical dialog (same reference). And therein, the names
+ * of the arguments have to re-appear.
+ *
+ * Then, the following steps have to be done to incorporate your Action:
+ * -# create a unique name for your action (no capital letters) to reference
+ *    it, this name has to appear in the file SuperDuperAction.cpp, e.g.
+ *    "super-duper"
+ * -# pick names the other required arguments, best if they are already
+ *    present in the MapOfActions. They have to appear in Query's in the
+ *    code of your Action.
+ * -# With this name create entries in the following maps for the action
+ *    name and for each names of a desired addtional argument if not present:
+ *   -# DescriptionMap, a catchy description of what your action does
+ *   -# TypeMap, see MapOfActions::OptionTypes for possible types of the single
+ *      argument it takes.
+ *   -# MenuContainsActionMap, in which menu should your action appear
+ *   -# ShortFormMap (optional), single letter for command line call
+ *   -# DefaultValueMap (optional), the default value (always a string)
+ * -# add to one of the command line sets by the following categories
+ *   -# generic - generic options (i.e. not one of the others)
+ *   -# config - action/argument only considers internal bevahior, user
+ *      does not have to see it while still having full functionality
+ *   -# hidden - this should be hidden from the user
+ *   -# visible - this should be visible to the user
+ *   -# inputfile - this should only be parsed from an input file, not
+ *      from command line
+ * -# add to a menu, i.e. make an entry in MenuContainsActionMap.
+ * -# add header file SuperDuperAction.hpp to MapOfActions.cpp and instantiate
+ *    your action in populateMenu() (mind the sorting: 1. menu,
+ *    2. alphabetical)
+ *
+ *  And that's.
+ *
+ *  Now, your action can be called from the command line, within the text
+ *  menu and the graphical user interface.
+ *
+ */
 class MapOfActions : public Singleton<MapOfActions> {
   friend class Singleton<MapOfActions>;
@@ -27 +126 @@
 
   // getter for the action descriptions and short forms
-  std::string getDescription(string actionname);
-  std::string getKeyAndShortForm(string actionname);
-  std::string getShortForm(string actionname);
-  map <std::string, std::string> getShortFormToActionMap();
+  std::string getDescription(std::string actionname);
+  std::string getKeyAndShortForm(std::string actionname);
+  std::string getShortForm(std::string actionname);
+  std::map <std::string, std::string> getShortFormToActionMap();
 
   void AddOptionsToParser();
 
   // check presence and getter for action type
-  bool hasValue(string actionname);
-  bool isShortFormPresent(string shortform);
-  enum OptionTypes getValueType(string actionname);
+  bool hasValue(std::string actionname);
+  bool isShortFormPresent(std::string shortform);
+  enum OptionTypes getValueType(std::string actionname);
 
-  set<string> generic;
-  set<string> config;
-  set<string> hidden;
-  set<string> visible;
-  set<string> inputfile;
+  std::set<std::string> generic;
+  std::set<std::string> config;
+  std::set<std::string> hidden;
+  std::set<std::string> visible;
+  std::set<std::string> inputfile;
+
+  std::multimap <std::string, std::string> MenuContainsActionMap;
+
+  // instantiates and puts all known actions into the ActionRegistry
+  void populateActions();
 
 private:
@@ -51 +155 @@
 
   // lookup list from our configs to the ones of CommandLineParser
-  map< set<std::string> *, po::options_description *> CmdParserLookup;
+  std::map< std::set<std::string> *, po::options_description *> CmdParserLookup;
 
   // map of the action names and their description
-  map<std::string, std::string> DefaultValue;
-  map<std::string, std::string> DescriptionMap;
-  map<std::string, std::string> ShortFormMap;
-  map<std::string, enum OptionTypes > TypeMap;
+  std::map<std::string, std::string> DefaultValue;
+  std::map<std::string, std::string> DescriptionMap;
+  std::map<std::string, std::string> ShortFormMap;
+  std::map<std::string, enum OptionTypes > TypeMap;
 };