Line data    Source code

       1             : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
       2             :    Copyright (c) 2012-2023 The plumed team
       3             :    (see the PEOPLE file at the root of the distribution for a list of names)
       4             : 
       5             :    See http://www.plumed.org for more information.
       6             : 
       7             :    This file is part of plumed, version 2.
       8             : 
       9             :    plumed is free software: you can redistribute it and/or modify
      10             :    it under the terms of the GNU Lesser General Public License as published by
      11             :    the Free Software Foundation, either version 3 of the License, or
      12             :    (at your option) any later version.
      13             : 
      14             :    plumed is distributed in the hope that it will be useful,
      15             :    but WITHOUT ANY WARRANTY; without even the implied warranty of
      16             :    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      17             :    GNU Lesser General Public License for more details.
      18             : 
      19             :    You should have received a copy of the GNU Lesser General Public License
      20             :    along with plumed.  If not, see <http://www.gnu.org/licenses/>.
      21             : +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
      22             : #ifndef __PLUMED_tools_Keywords_h
      23             : #define __PLUMED_tools_Keywords_h
      24             : #include <vector>
      25             : #include <string>
      26             : #include <set>
      27             : #include <map>
      28             : 
      29             : #include "Exception.h"
      30             : 
      31             : namespace PLMD {
      32             : 
      33             : class Log;
      34             : 
      35             : /// This class holds the keywords and their documentation
      36             : class Keywords {
      37             : /// This class lets me pass keyword types easily
      38             :   class KeyType {
      39             :   public:
      40             :     enum {hidden,compulsory,flag,optional,atoms,vessel} style;
      41             :     explicit KeyType( const std::string& type );
      42             :     void setStyle( const std::string& type );
      43             :     bool isCompulsory() const {
      44       18388 :       return (style==compulsory);
      45             :     }
      46             :     bool isFlag() const {
      47       24181 :       return (style==flag);
      48             :     }
      49             :     bool isOptional() const {
      50       18906 :       return (style==optional);
      51             :     }
      52             :     bool isAtomList() const {
      53     1245063 :       return (style==atoms);
      54             :     }
      55             :     bool isVessel() const {
      56       13761 :       return (style==vessel);
      57             :     }
      58     1890167 :     std::string toString() const {
      59     1890167 :       if(style==compulsory) {
      60      127856 :         return "compulsory";
      61             :       } else if(style==optional) {
      62      677281 :         return "optional";
      63             :       } else if(style==atoms) {
      64      319853 :         return "atoms";
      65             :       } else if(style==flag) {
      66      654174 :         return "flag";
      67             :       } else if(style==hidden) {
      68      111003 :         return "hidden";
      69             :       } else if(style==vessel) {
      70           0 :         return "vessel";
      71             :       } else {
      72           0 :         plumed_assert(0);
      73             :       }
      74             :       return "";
      75             :     }
      76             :   };
      77             :   friend class Action;
      78             :   friend class ActionShortcut;
      79             :   friend class ActionRegister;
      80             : private:
      81             : /// Is this an action or driver (this bool affects what style==atoms does in print)
      82             :   bool isaction;
      83             : /// This allows us to overwrite the behavior of the atoms type in analysis actions
      84             :   bool isatoms;
      85             : /// The name of the action that has this set of keywords
      86             :   std::string thisactname;
      87             : /// The names of the allowed keywords
      88             :   std::vector<std::string> keys;
      89             : /// The names of the reserved keywords
      90             :   std::vector<std::string> reserved_keys;
      91             : /// Whether the keyword is compulsory, optional...
      92             :   std::map<std::string,KeyType> types;
      93             : /// Do we allow stuff like key1, key2 etc
      94             :   std::map<std::string,bool> allowmultiple;
      95             : /// The documentation for the keywords
      96             :   std::map<std::string,std::string> documentation;
      97             : /// The default values for the flags (are they on or of)
      98             :   std::map<std::string,bool> booldefs;
      99             : /// The default values (if there are default values) for compulsory keywords
     100             :   std::map<std::string,std::string> numdefs;
     101             : /// The tags for atoms - we use this so the manual can differentiate between different ways of specifying atoms
     102             :   std::map<std::string,std::string> atomtags;
     103             : /// The string that should be printed out to describe how the components work for this particular action
     104             :   std::string cstring;
     105             : /// The names of all the possible components for an action
     106             :   std::vector<std::string> cnames;
     107             : /// The keyword that turns on a particular component
     108             :   std::map<std::string,std::string> ckey;
     109             : /// The documentation for a particular component
     110             :   std::map<std::string,std::string> cdocs;
     111             : /// The list of actions that are needed by this action
     112             :   std::vector<std::string> neededActions;
     113             : /// List of suffixes that can be used with this action
     114             :   std::vector<std::string> actionNameSuffixes;
     115             : /// Print the documentation for the jth keyword in html
     116             :   void print_html_item( const std::string& ) const;
     117             : public:
     118             : /// Constructor
     119      188364 :   Keywords() : isaction(true), isatoms(true) {}
     120             : ///
     121             :   void isDriver() {
     122       10884 :     isaction=false;
     123             :   }
     124             : ///
     125             :   void isAnalysis() {
     126             :     isatoms=false;
     127             :   }
     128             : /// find out whether flag key is on or off by default.
     129             :   bool getLogicalDefault(const std::string & key, bool& def ) const ;
     130             : /// Get the value of the default for the keyword named key
     131             :   bool getDefaultValue(const std::string & key, std::string& def ) const ;
     132             : /// Return the number of defined keywords
     133             :   unsigned size() const;
     134             : /// Check if numbered keywords are allowed for this action
     135             :   bool numbered( const std::string & k ) const ;
     136             : /// Return the ith keyword
     137             :   std::string getKeyword( const unsigned i ) const ;
     138             : /// Get the documentation for a particular keyword
     139             :   std::string getKeywordDocs( const std::string& key ) const ;
     140             : /// Print the documentation to the log file (used by PLMD::Action::error)
     141             :   void print( Log& log ) const ;
     142             : /// Print the documentation to a file (use by PLUMED::CLTool::readCommandLineArgs)
     143             :   void print( FILE* out ) const ;
     144             : /// Get the help string
     145             :   std::string getHelpString() const ;
     146             : /// Print a file containing the list of keywords for a particular action (used for spell checking)
     147             :   void print_spelling() const ;
     148             : /// Reserve a keyword
     149             :   void reserve( const std::string & t, const std::string & k, const std::string & d );
     150             : /// Reserve a flag
     151             :   void reserveFlag( const std::string & k, const bool def, const std::string & d );
     152             : /// Use one of the reserved keywords
     153             :   void use( const std::string  & k );
     154             : /// Get the ith keyword
     155             :   std::string get( const unsigned k ) const ;
     156             : /// Add a new keyword of type t with name k and description d
     157             :   void add( const std::string & t, const std::string & k, const std::string & d );
     158             : /// Add a new compulsory keyword (t must equal compulsory) with name k, default value def and description d
     159             :   void add( const std::string & t, const std::string & k, const std::string & def, const std::string & d );
     160             : /// Add a falg with name k that is by default on if def is true and off if def is false.  d should provide a description of the flag
     161             :   void addFlag( const std::string & k, const bool def, const std::string & d );
     162             : /// Remove the keyword with name k
     163             :   void remove( const std::string & k );
     164             : /// Check if there is a keyword with name k
     165             :   bool exists( const std::string & k ) const ;
     166             : /// Check the keyword k has been reserved
     167             :   bool reserved( const std::string & k ) const ;
     168             : /// Get the type for the keyword with string k
     169             :   std::string getStyle( const std::string & k ) const ;
     170             : /// Check if the keyword with name k has style t
     171             :   bool style( const std::string & k, const std::string & t ) const ;
     172             : /// Print an html version of the documentation
     173             :   void print_html() const ;
     174             : /// Print keywords in form readable by vim
     175             :   void print_vim() const ;
     176             : /// Print the template version for the documentation
     177             :   void print_template( const std::string& actionname, bool include_optional) const ;
     178             : /// Change the style of a keyword
     179             :   void reset_style( const std::string & k, const std::string & style );
     180             : /// Add keywords from one keyword object to another
     181             :   void add( const Keywords& keys );
     182             : /// Copy the keywords data
     183             :   void copyData( std::vector<std::string>& kk, std::vector<std::string>& rk, std::map<std::string,KeyType>& tt, std::map<std::string,bool>& am,
     184             :                  std::map<std::string,std::string>& docs, std::map<std::string,bool>& bools, std::map<std::string,std::string>& nums,
     185             :                  std::map<std::string,std::string>& atags, std::vector<std::string>& cnam, std::map<std::string,std::string>& ck,
     186             :                  std::map<std::string,std::string>& cd ) const ;
     187             : /// Clear everything from the keywords object.
     188             : /// Not actually needed if your Keywords object is going out of scope.
     189             :   void destroyData();
     190             : /// Set the text that introduces how the components for this action are introduced
     191             :   void setComponentsIntroduction( const std::string& instr );
     192             : /// Add the description of the value
     193             :   void setValueDescription( const std::string& descr );
     194             : /// Add a potential component which can be output by this particular action
     195             :   void addOutputComponent( const std::string& name, const std::string& key, const std::string& descr );
     196             : /// Remove a component that can be output by this particular action
     197             :   void removeOutputComponent( const std::string& name );
     198             : /// Has a component with this name been added?
     199             :   bool outputComponentExists( const std::string& name ) const ;
     200             : /// Get the flag that forces this component to be calculated
     201             :   std::string getOutputComponentFlag( const std::string& name ) const ;
     202             : /// Get the description of this component
     203             :   std::string getOutputComponentDescription( const std::string& name ) const ;
     204             : /// Get the full list of output components
     205             :   std::vector<std::string> getOutputComponents() const ;
     206             : /// Get the description of a particular keyword
     207             :   std::string getKeywordDescription( const std::string& name ) const ;
     208             : /// Remove a component with a particular name from the keywords
     209             :   void removeComponent( const std::string& name );
     210             : /// Reference to keys
     211             :   std::vector<std::string> getKeys() const {
     212           0 :     return keys;
     213             :   }
     214             : /// Get the description of a particular keyword
     215             :   std::string getTooltip( const std::string& name ) const ;
     216             : /// Note that another actions is required to create this shortcut
     217             :   void needsAction( const std::string& name );
     218             : /// Add a suffix to the list of action name suffixes to test for
     219             :   void addActionNameSuffix( const std::string& suffix );
     220             : /// Get the list of keywords that are needed by this action
     221             :   const std::vector<std::string>& getNeededKeywords() const ;
     222             : /// Return the name of the action that has this set of keywords
     223             :   std::string getDisplayName() const ;
     224             : /// Set the display name
     225             :   void setDisplayName( const std::string& name );
     226             : };
     227             : 
     228             : }
     229             : 
     230             : #endif