Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • src/Actions/MapOfActions.hpp

    r326bbe r7e6b00  
    1111#include "Helpers/Assert.hpp"
    1212#include <boost/program_options.hpp>
    13 
    1413#include <map>
    1514#include <set>
    … …  
    2120namespace po = boost::program_options;
    2221
    23 /** Central class for adding functionality to the code.
    24  *
    25  * In Molecuilder everything that can be done - such as adding atoms,
    26  * translating molecules, saving bind information - is an Action.
    27  *
    28  * In order to reference Action's with what the user sees, this class is the
    29  * mediator.
    30  *
    31  * An Action is described to the user by:
    32  * -# a name (this is the most important information)
    33  * -# a description
    34  * -# a shortform (single letter for use on the command line)
    35  * -# a text menu it resides in
    36  * -# the type of its argument
    37  * -# the command line category
    38  *
    39  * The Action::NAME is the most important information because every Action
    40  * registers itself automatically with the ActionRegistry and can be retrieved
    41  * therefrom and from this MapOfActions simply by knowing its name alone.
    42  *
    43  * In the constructor of MapOfActions all this is set.
    44  *
    45  * Note that Action will require input from the user. This is done via class
    46  * Query.
    47  *
    48  * And note also that MapOfActions actually contains more than just all
    49  * Actions: There are a number of names that actually are just arguments to
    50  * actions (e.g. "output-file").
    51  *
    52  * <h1> Howto add an Action</h1>
    53  *
    54  * Let us assume your new action (class) is called SuperDuperAction, consisting
    55  * of two files SuperDuperAction.cpp and SuperDuperAction.hpp.
    56  *
    57  * Furthermore, let's say you Action needs two values: a double value as a
    58  * upper threshold and a string which is the name of the output file.
    59  *
    60  * <h2> Command Line preliminaries </h2>
    61  *
    62  * You have to decide whether (for the command line) it makes sense to have an
    63  * extra argument requesting the arguments, or one should be the argument of
    64  * your action. I.e. your action name is "super-duper", then the use may
    65  * call your action like this:
    66  *
    67  * ./molecuilder --super-duper 4 --output-file test.dat
    68  *
    69  * Here, we have picked the threshold as the value for your action and the
    70  * name of the output file is given by an additional argument. Of course,
    71  * it can be the other way round or by two arguments such as here:
    72  *
    73  * ./molecuilder --super-duper --threshold 4 --output-file test.dat
    74  *
    75  * It depends on what possible arguments are already there (don't make up
    76  * new ones if present ones actually make sense for your action) and which
    77  * argument is more natural or closer to what your action does.
    78  *
    79  * <h2> Menu preliminaries </h2>
    80  *
    81  * Whatever you decide, your action will need some Query dialogs to request
    82  * the necessary information from the user, either via a command line
    83  * argument (--output-file) via a text dialog (referenced by "output-file")
    84  * or via a graphical dialog (same reference). And therein, the names
    85  * of the arguments have to re-appear.
    86  *
    87  * Then, the following steps have to be done to incorporate your Action:
    88  * -# create a unique name for your action (no capital letters) to reference
    89  *    it, this name has to appear in the file SuperDuperAction.cpp, e.g.
    90  *    "super-duper"
    91  * -# pick names the other required arguments, best if they are already
    92  *    present in the MapOfActions. They have to appear in Query's in the
    93  *    code of your Action.
    94  * -# With this name create entries in the following maps for the action
    95  *    name and for each names of a desired addtional argument if not present:
    96  *   -# DescriptionMap, a catchy description of what your action does
    97  *   -# TypeMap, see MapOfActions::OptionTypes for possible types of the single
    98  *      argument it takes.
    99  *   -# MenuContainsActionMap, in which menu should your action appear
    100  *   -# ShortFormMap (optional), single letter for command line call
    101  *   -# DefaultValueMap (optional), the default value (always a string)
    102  * -# add to one of the command line sets by the following categories
    103  *   -# generic - generic options (i.e. not one of the others)
    104  *   -# config - action/argument only considers internal bevahior, user
    105  *      does not have to see it while still having full functionality
    106  *   -# hidden - this should be hidden from the user
    107  *   -# visible - this should be visible to the user
    108  *   -# inputfile - this should only be parsed from an input file, not
    109  *      from command line
    110  * -# add to a menu, i.e. make an entry in MenuContainsActionMap.
    111  * -# add header file SuperDuperAction.hpp to MapOfActions.cpp and instantiate
    112  *    your action in populateMenu() (mind the sorting: 1. menu,
    113  *    2. alphabetical)
    114  *
    115  *  And that's.
    116  *
    117  *  Now, your action can be called from the command line, within the text
    118  *  menu and the graphical user interface.
    119  *
    120  */
    12122class MapOfActions : public Singleton<MapOfActions> {
    12223  friend class Singleton<MapOfActions>;
    … …  
    12627
    12728  // getter for the action descriptions and short forms
    128   std::string getDescription(std::string actionname);
    129   std::string getKeyAndShortForm(std::string actionname);
    130   std::string getShortForm(std::string actionname);
    131   std::map <std::string, std::string> getShortFormToActionMap();
     29  std::string getDescription(string actionname);
     30  std::string getKeyAndShortForm(string actionname);
     31  std::string getShortForm(string actionname);
     32  map <std::string, std::string> getShortFormToActionMap();
    13233
    13334  void AddOptionsToParser();
    13435
    13536  // check presence and getter for action type
    136   bool hasValue(std::string actionname);
    137   bool isShortFormPresent(std::string shortform);
    138   enum OptionTypes getValueType(std::string actionname);
     37  bool hasValue(string actionname);
     38  bool isShortFormPresent(string shortform);
     39  enum OptionTypes getValueType(string actionname);
    13940
    140   std::set<std::string> generic;
    141   std::set<std::string> config;
    142   std::set<std::string> hidden;
    143   std::set<std::string> visible;
    144   std::set<std::string> inputfile;
    145 
    146   std::multimap <std::string, std::string> MenuContainsActionMap;
    147 
    148   // instantiates and puts all known actions into the ActionRegistry
    149   void populateActions();
     41  set<string> generic;
     42  set<string> config;
     43  set<string> hidden;
     44  set<string> visible;
     45  set<string> inputfile;
    15046
    15147private:
    … …  
    15551
    15652  // lookup list from our configs to the ones of CommandLineParser
    157   std::map< std::set<std::string> *, po::options_description *> CmdParserLookup;
     53  map< set<std::string> *, po::options_description *> CmdParserLookup;
    15854
    15955  // map of the action names and their description
    160   std::map<std::string, std::string> DefaultValue;
    161   std::map<std::string, std::string> DescriptionMap;
    162   std::map<std::string, std::string> ShortFormMap;
    163   std::map<std::string, enum OptionTypes > TypeMap;
     56  map<std::string, std::string> DefaultValue;
     57  map<std::string, std::string> DescriptionMap;
     58  map<std::string, std::string> ShortFormMap;
     59  map<std::string, enum OptionTypes > TypeMap;
    16460};
    16561
Note: See TracChangeset for help on using the changeset viewer.