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       18312 :     bool isCompulsory() const { return (style==compulsory); }
      44       24086 :     bool isFlag() const { return (style==flag); }
      45       18830 :     bool isOptional() const { return (style==optional); }
      46     1232471 :     bool isAtomList() const { return (style==atoms); }
      47       13664 :     bool isVessel() const { return (style==vessel); }
      48     1818345 :     std::string toString() const {
      49     1818345 :       if(style==compulsory) return "compulsory";
      50      618802 :       else if(style==optional) return "optional";
      51      313996 :       else if(style==atoms) return "atoms";
      52      652631 :       else if(style==flag) return "flag";
      53      108394 :       else if(style==hidden) return "hidden";
      54           0 :       else if(style==vessel) return "vessel";
      55           0 :       else plumed_assert(0);
      56             :       return "";
      57             :     }
      58             :   };
      59             :   friend class Action;
      60             :   friend class ActionShortcut;
      61             :   friend class ActionRegister;
      62             : private:
      63             : /// Is this an action or driver (this bool affects what style==atoms does in print)
      64             :   bool isaction;
      65             : /// This allows us to overwrite the behavior of the atoms type in analysis actions
      66             :   bool isatoms;
      67             : /// The name of the action that has this set of keywords
      68             :   std::string thisactname;
      69             : /// The names of the allowed keywords
      70             :   std::vector<std::string> keys;
      71             : /// The names of the reserved keywords
      72             :   std::vector<std::string> reserved_keys;
      73             : /// Whether the keyword is compulsory, optional...
      74             :   std::map<std::string,KeyType> types;
      75             : /// Do we allow stuff like key1, key2 etc
      76             :   std::map<std::string,bool> allowmultiple;
      77             : /// The documentation for the keywords
      78             :   std::map<std::string,std::string> documentation;
      79             : /// The default values for the flags (are they on or of)
      80             :   std::map<std::string,bool> booldefs;
      81             : /// The default values (if there are default values) for compulsory keywords
      82             :   std::map<std::string,std::string> numdefs;
      83             : /// The tags for atoms - we use this so the manual can differentiate between different ways of specifying atoms
      84             :   std::map<std::string,std::string> atomtags;
      85             : /// The string that should be printed out to describe how the components work for this particular action
      86             :   std::string cstring;
      87             : /// The names of all the possible components for an action
      88             :   std::vector<std::string> cnames;
      89             : /// The keyword that turns on a particular component
      90             :   std::map<std::string,std::string> ckey;
      91             : /// The documentation for a particular component
      92             :   std::map<std::string,std::string> cdocs;
      93             : /// The list of actions that are needed by this action
      94             :   std::vector<std::string> neededActions;
      95             : /// List of suffixes that can be used with this action
      96             :   std::vector<std::string> actionNameSuffixes;
      97             : /// Print the documentation for the jth keyword in html
      98             :   void print_html_item( const std::string& ) const;
      99             : public:
     100             : /// Constructor
     101      186070 :   Keywords() : isaction(true), isatoms(true) {}
     102             : ///
     103       10632 :   void isDriver() { isaction=false; }
     104             : ///
     105             :   void isAnalysis() { isatoms=false; }
     106             : /// find out whether flag key is on or off by default.
     107             :   bool getLogicalDefault(const std::string & key, bool& def ) const ;
     108             : /// Get the value of the default for the keyword named key
     109             :   bool getDefaultValue(const std::string & key, std::string& def ) const ;
     110             : /// Return the number of defined keywords
     111             :   unsigned size() const;
     112             : /// Check if numbered keywords are allowed for this action
     113             :   bool numbered( const std::string & k ) const ;
     114             : /// Return the ith keyword
     115             :   std::string getKeyword( const unsigned i ) const ;
     116             : /// Get the documentation for a particular keyword
     117             :   std::string getKeywordDocs( const std::string& key ) const ;
     118             : /// Print the documentation to the log file (used by PLMD::Action::error)
     119             :   void print( Log& log ) const ;
     120             : /// Print the documentation to a file (use by PLUMED::CLTool::readCommandLineArgs)
     121             :   void print( FILE* out ) const ;
     122             : /// Get the help string
     123             :   std::string getHelpString() const ;
     124             : /// Print a file containing the list of keywords for a particular action (used for spell checking)
     125             :   void print_spelling() const ;
     126             : /// Reserve a keyword
     127             :   void reserve( const std::string & t, const std::string & k, const std::string & d );
     128             : /// Reserve a flag
     129             :   void reserveFlag( const std::string & k, const bool def, const std::string & d );
     130             : /// Use one of the reserved keywords
     131             :   void use( const std::string  & k );
     132             : /// Get the ith keyword
     133             :   std::string get( const unsigned k ) const ;
     134             : /// Add a new keyword of type t with name k and description d
     135             :   void add( const std::string & t, const std::string & k, const std::string & d );
     136             : /// Add a new compulsory keyword (t must equal compulsory) with name k, default value def and description d
     137             :   void add( const std::string & t, const std::string & k, const std::string & def, const std::string & d );
     138             : /// 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
     139             :   void addFlag( const std::string & k, const bool def, const std::string & d );
     140             : /// Remove the keyword with name k
     141             :   void remove( const std::string & k );
     142             : /// Check if there is a keyword with name k
     143             :   bool exists( const std::string & k ) const ;
     144             : /// Check the keyword k has been reserved
     145             :   bool reserved( const std::string & k ) const ;
     146             : /// Get the type for the keyword with string k
     147             :   std::string getStyle( const std::string & k ) const ;
     148             : /// Check if the keyword with name k has style t
     149             :   bool style( const std::string & k, const std::string & t ) const ;
     150             : /// Print an html version of the documentation
     151             :   void print_html() const ;
     152             : /// Print keywords in form readable by vim
     153             :   void print_vim() const ;
     154             : /// Print the template version for the documentation
     155             :   void print_template( const std::string& actionname, bool include_optional) const ;
     156             : /// Change the style of a keyword
     157             :   void reset_style( const std::string & k, const std::string & style );
     158             : /// Add keywords from one keyword object to another
     159             :   void add( const Keywords& keys );
     160             : /// Copy the keywords data
     161             :   void copyData( std::vector<std::string>& kk, std::vector<std::string>& rk, std::map<std::string,KeyType>& tt, std::map<std::string,bool>& am,
     162             :                  std::map<std::string,std::string>& docs, std::map<std::string,bool>& bools, std::map<std::string,std::string>& nums,
     163             :                  std::map<std::string,std::string>& atags, std::vector<std::string>& cnam, std::map<std::string,std::string>& ck,
     164             :                  std::map<std::string,std::string>& cd ) const ;
     165             : /// Clear everything from the keywords object.
     166             : /// Not actually needed if your Keywords object is going out of scope.
     167             :   void destroyData();
     168             : /// Set the text that introduces how the components for this action are introduced
     169             :   void setComponentsIntroduction( const std::string& instr );
     170             : /// Add the description of the value
     171             :   void setValueDescription( const std::string& descr );
     172             : /// Add a potential component which can be output by this particular action
     173             :   void addOutputComponent( const std::string& name, const std::string& key, const std::string& descr );
     174             : /// Remove a component that can be output by this particular action
     175             :   void removeOutputComponent( const std::string& name );
     176             : /// Has a component with this name been added?
     177             :   bool outputComponentExists( const std::string& name ) const ;
     178             : /// Get the flag that forces this component to be calculated
     179             :   std::string getOutputComponentFlag( const std::string& name ) const ;
     180             : /// Get the description of this component
     181             :   std::string getOutputComponentDescription( const std::string& name ) const ;
     182             : /// Get the full list of output components
     183             :   std::vector<std::string> getOutputComponents() const ;
     184             : /// Get the description of a particular keyword
     185             :   std::string getKeywordDescription( const std::string& name ) const ;
     186             : /// Remove a component with a particular name from the keywords
     187             :   void removeComponent( const std::string& name );
     188             : /// Reference to keys
     189           0 :   std::vector<std::string> getKeys() const { return keys; }
     190             : /// Get the description of a particular keyword
     191             :   std::string getTooltip( const std::string& name ) const ;
     192             : /// Note that another actions is required to create this shortcut
     193             :   void needsAction( const std::string& name );
     194             : /// Add a suffix to the list of action name suffixes to test for
     195             :   void addActionNameSuffix( const std::string& suffix );
     196             : /// Get the list of keywords that are needed by this action
     197             :   const std::vector<std::string>& getNeededKeywords() const ;
     198             : /// Return the name of the action that has this set of keywords
     199             :   std::string getDisplayName() const ;
     200             : /// Set the display name
     201             :   void setDisplayName( const std::string& name );
     202             : };
     203             : 
     204             : }
     205             : 
     206             : #endif