Line data Source code
1 : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 : Copyright (c) 2022,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 : #include "CLTool.h"
23 : #include "core/CLToolRegister.h"
24 : #include "tools/Tools.h"
25 : #include "config/Config.h"
26 : #include "core/ActionRegister.h"
27 : #include "core/CLToolRegister.h"
28 : #include "core/GenericMolInfo.h"
29 : #include "core/ModuleMap.h"
30 : #include <cstdio>
31 : #include <string>
32 : #include <iostream>
33 :
34 : namespace PLMD {
35 : namespace cltools {
36 :
37 : //+PLUMEDOC TOOLS gen_json
38 : /*
39 : gen_json constructs a json file that includes a dictionary of actions, the keywords for those actions and the components and outputs this to standard output
40 :
41 : This command is used during the build process of plumed. It constructs a json file that contains documentation information on all actions and cltools. This json
42 : file is then used by the python package [PlumedToHTML](https://github.com/plumed/PlumedToHTML). This package is used to construct the example input files that
43 : appear in [the plumed nest](https://www.plumed-nest.org), [plumed tutorials](https://www.plumed-tutorials.org) and this manual.
44 :
45 : You will likely not ever need to run this command. When it runs during the build proess we use the following command:
46 :
47 : ```plumed
48 : plumed --no-mpi gen_json --actions action_list > syntax.json
49 : ```
50 :
51 : You can find the syntax json file that is generated by this comamnd as `plumed2/json/syntax.json`.
52 :
53 : */
54 : //+ENDPLUMEDOC
55 :
56 : class GenJson : public CLTool {
57 : private:
58 : std::string version;
59 : void printHyperlink( const std::string& action );
60 : void printKeywordDocs( const std::string& k, const std::string& action, const Keywords& keys );
61 : public:
62 : static void registerKeywords( Keywords& keys );
63 : explicit GenJson(const CLToolOptions& co );
64 : int main(FILE* in, FILE*out,Communicator& pc) override;
65 7 : std::string description()const override {
66 7 : return "print out a json file that contains the pluemd syntax";
67 : }
68 : };
69 :
70 21973 : PLUMED_REGISTER_CLTOOL(GenJson,"gen_json")
71 :
72 7321 : void GenJson::registerKeywords( Keywords& keys ) {
73 7321 : CLTool::registerKeywords( keys );
74 7321 : keys.add("compulsory","--actions","a file containing one line descriptions of the various actions");
75 7321 : }
76 :
77 10 : GenJson::GenJson(const CLToolOptions& co ):
78 : CLTool(co),
79 10 : version("master") {
80 10 : inputdata=inputType::commandline;
81 20 : if( config::getVersionLong().find("dev")==std::string::npos ) {
82 0 : version="v"+config::getVersion();
83 : }
84 10 : }
85 :
86 1620 : void GenJson::printHyperlink( const std::string& action ) {
87 4860 : std::cout<<" \"hyperlink\" : \"https://www.plumed.org/doc-"<<version<<"/user-doc/html/"<<action<<"\","<<std::endl;
88 1620 : }
89 :
90 17556 : void GenJson::printKeywordDocs( const std::string& k, const std::string& action, const Keywords& keys ) {
91 17556 : std::string defa = "", desc = keys.getKeywordDescription( k );
92 17556 : if( desc.find("default=")!=std::string::npos ) {
93 5904 : std::size_t defstart = desc.find_first_of("="), brac=desc.find_first_of(")");
94 5904 : defa = desc.substr(defstart+1,brac-defstart-2);
95 11808 : desc = desc.substr(brac+1);
96 : }
97 17556 : std::size_t dot=desc.find_first_of(".");
98 17556 : std::string mydescrip = desc.substr(0,dot);
99 17556 : if( mydescrip.find("\\")!=std::string::npos ) {
100 0 : error("found invalid backslash character documentation for keyword " + k + " in action " + action );
101 : }
102 70224 : std::cout<<" \""<<k<<"\" : { \"type\": \""<<keys.getStyle(k)<<"\", \"description\": \""<<mydescrip<<"\", \"multiple\": "<<keys.numbered(k);
103 17556 : std::string actlink=keys.getLinkedActions(k);
104 17556 : if( actlink.length()>0 ) {
105 35112 : std::cout<<", \"actionlink\": \""<<actlink<<"\"";
106 : }
107 17556 : std::string doclink=keys.getLinkedPages(k);
108 17556 : if( doclink.length()>0 ) {
109 1260 : std::cout<<", \"pagelink\": \""<<doclink<<"\"";
110 : }
111 17556 : std::string argtype = keys.getArgumentType( k );
112 17556 : if( argtype.length()>0 ) {
113 1890 : std::cout<<", \"argtype\": \""<<argtype<<"\"}";
114 16611 : } else if( defa.length()>0 ) {
115 11772 : std::cout<<", \"default\": \""<<defa<<"\"}";
116 : } else {
117 10725 : std::cout<<"}";
118 : }
119 17556 : }
120 :
121 3 : int GenJson::main(FILE* in, FILE*out,Communicator& pc) {
122 3 : std::string line(""), actionfile;
123 3 : parse("--actions",actionfile);
124 3 : IFile myfile;
125 3 : myfile.open(actionfile);
126 : bool stat;
127 : std::map<std::string,std::string> action_map;
128 407 : while((stat=myfile.getline(line))) {
129 404 : std::size_t col = line.find_first_of(":");
130 404 : std::string docs = line.substr(col+1);
131 404 : if( docs.find("\\")!=std::string::npos ) {
132 0 : error("found invalid backslash character in first line of documentation for action " + line.substr(0,col) );
133 : }
134 808 : action_map.insert(std::pair<std::string,std::string>( line.substr(0,col), docs ) );
135 : }
136 3 : myfile.close();
137 :
138 : // Cycle over all the action names
139 3 : std::cout<<"{"<<std::endl;
140 : // Get the vimlink
141 6 : std::cout<<" \"vimlink\" : \"https://www.plumed.org/doc-"<<version<<"/user-doc/html/vim\","<<std::endl;
142 : // And the replicas link
143 6 : std::cout<<" \"replicalink\" : \"https://www.plumed.org/doc-"<<version<<"/user-doc/html/parsing.html\","<<std::endl;
144 : // Get the names of all the actions
145 3 : std::vector<std::string> action_names( actionRegister().getActionNames() );
146 3 : std::vector<std::string> allmodules;
147 1416 : for(const auto & action : action_names) {
148 2826 : std::cout<<" \""<<action<<'"'<<": {"<<std::endl;
149 : // Handle conversion of action names to links
150 1413 : printHyperlink( action );
151 2826 : std::cout<<" \"description\" : \""<<action_map[action]<<"\",\n";
152 : bool found=false;
153 2826 : plumed_massert( getModuleMap().find(action)!=getModuleMap().end(), "could not find action named " + action + " in module map");
154 2826 : std::string thismodule = getModuleMap().find(action)->second;
155 1413 : found = std::find(allmodules.begin(),allmodules.end(),thismodule)!=allmodules.end();
156 1413 : if( !found ) {
157 150 : allmodules.push_back( thismodule );
158 : }
159 2826 : std::cout<<" \"module\" : \""<<thismodule<<"\",\n";
160 : // Now output keyword information
161 1413 : Keywords keys;
162 1413 : actionRegister().getKeywords( action, keys );
163 2826 : std::cout<<" \"displayname\" : \""<<keys.getDisplayName()<<"\",\n";
164 : // This is used for noting actions that have been deprecated
165 1413 : std::string replacement = keys.getReplacementAction();
166 1413 : if( replacement!="none" ) {
167 : bool found_replacement=false;
168 20313 : for(unsigned j=0; j<action_names.size(); ++j) {
169 20313 : if( action_names[j]==replacement ) {
170 : found_replacement=true;
171 : break;
172 : }
173 : }
174 93 : if( !found_replacement ) {
175 0 : error("could not find action named " + replacement + " that is supposed to be used to replace " + action );
176 : }
177 186 : std::cout<<" \"replacement\" : \""<<replacement<<"\",\n";
178 : }
179 1413 : std::cout<<" \"dois\" : [";
180 1413 : unsigned ndoi = keys.getDOIList().size();
181 1413 : if( ndoi>0 ) {
182 426 : std::cout<<"\"" + keys.getDOIList()[0] + "\"";
183 804 : for(unsigned j=1; j<ndoi; ++j) {
184 756 : std::cout<<", \"" + keys.getDOIList()[j] + "\"";
185 : }
186 : }
187 1413 : std::cout<<"],\n";
188 1413 : std::cout<<" \"syntax\" : {"<<std::endl;
189 18198 : for(unsigned j=0; j<keys.size(); ++j) {
190 16785 : printKeywordDocs( keys.getKeyword(j), action, keys );
191 16785 : if( j==keys.size()-1 && !keys.exists("HAS_VALUES") ) {
192 : std::cout<<std::endl;
193 : } else {
194 16569 : std::cout<<","<<std::endl;
195 : }
196 : }
197 1413 : if( keys.exists("HAS_VALUES") ) {
198 1197 : std::cout<<" \"output\" : {"<<std::endl;
199 1197 : std::vector<std::string> components( keys.getOutputComponents() );
200 : // Check if we have a value
201 : bool hasvalue=true;
202 2484 : for(unsigned k=0; k<components.size(); ++k) {
203 2451 : if( keys.getOutputComponentFlag( components[k] )=="default" ) {
204 : hasvalue=false;
205 : break;
206 : }
207 : }
208 5208 : for(unsigned k=0; k<components.size(); ++k) {
209 4011 : std::string compname=components[k];
210 4011 : if( components[k]==".#!value" ) {
211 : hasvalue=false;
212 : compname="value";
213 : }
214 8022 : std::cout<<" \""<<compname<<"\" : {"<<std::endl;
215 8022 : std::cout<<" \"flag\": \""<<keys.getOutputComponentFlag( components[k] )<<"\","<<std::endl;
216 12033 : std::cout<<" \"type\": \""<<keys.getOutputComponentType( components[k] )<<"\","<<std::endl;
217 4011 : std::string desc=keys.getOutputComponentDescription( components[k] );
218 4011 : std::size_t dot=desc.find_first_of(".");
219 4011 : std::string mydescrip = desc.substr(0,dot);
220 4011 : if( mydescrip.find("\\")!=std::string::npos ) {
221 0 : error("found invalid backslash character documentation for output component " + compname + " in action " + action );
222 : }
223 8022 : std::cout<<" \"description\": \""<<mydescrip<<"\""<<std::endl;
224 4011 : if( k==components.size()-1 ) {
225 1197 : std::cout<<" }"<<std::endl;
226 : } else {
227 2814 : std::cout<<" },"<<std::endl;
228 : }
229 : }
230 1197 : if( hasvalue && components.size()==0 ) {
231 0 : std::cerr<<"WARNING: no components have been registered for action "<<action<<"\n";
232 : }
233 1197 : std::cout<<" }"<<std::endl;
234 :
235 1197 : }
236 1413 : std::cout<<" },"<<std::endl;
237 1413 : if( keys.getNeededKeywords().size()>0 ) {
238 393 : std::vector<std::string> neededActions( keys.getNeededKeywords() );
239 786 : std::cout<<" \"needs\" : ["<<"\""<<neededActions[0]<<"\"";
240 3144 : for(unsigned j=1; j<neededActions.size(); ++j) {
241 5502 : std::cout<<", \""<<neededActions[j]<<"\"";
242 : }
243 393 : std::cout<<"],"<<std::endl;
244 393 : }
245 : // This ensures that \n is replaced by \\n
246 1413 : std::string unsafen="\n", safen="\\n", helpstr = keys.getHelpString();
247 1413 : for( std::size_t pos = helpstr.find("\n");
248 32460 : pos != std::string::npos;
249 31047 : pos = helpstr.find("\n", pos)
250 : ) {
251 : helpstr.replace(pos, unsafen.size(), safen);
252 31047 : pos += safen.size();
253 : }
254 2826 : std::cout<<" \"help\" : \""<<helpstr<<"\"\n";
255 1413 : std::cout<<" },"<<std::endl;
256 1413 : }
257 : // Get all the special groups
258 3 : std::cout<<" \"groups\" : {"<<std::endl;
259 3 : std::cout<<" \"@allatoms\" : { \n"<<std::endl;
260 3 : std::cout<<" \"description\" : \"refers to all the MD codes atoms and PLUMEDs vatoms\","<<std::endl;
261 6 : std::cout<<" \"link\" : \"https://www.plumed.org/doc-"<<version<<"/user-doc/html/specifying_atoms\""<<std::endl;
262 3 : std::cout<<" },"<<std::endl;
263 3 : std::cout<<" \"@mdatoms\" : { \n"<<std::endl;
264 3 : std::cout<<" \"description\" : \"refers to all the MD codes atoms but not PLUMEDs vatoms\","<<std::endl;
265 6 : std::cout<<" \"link\" : \"https://www.plumed.org/doc-"<<version<<"/user-doc/html/specifying_atoms\""<<std::endl;
266 3 : std::cout<<" },"<<std::endl;
267 3 : std::cout<<" \"@ndx:\" : { \n"<<std::endl;
268 3 : std::cout<<" \"description\" : \"load a group from a GROMACS index file\","<<std::endl;
269 6 : std::cout<<" \"link\" : \"https://www.plumed.org/doc-"<<version<<"/user-doc/html/specifying_atoms.html\""<<std::endl;
270 : // Now print all the special keywords in molinfo
271 3 : std::map<std::string,std::string> specials( GenericMolInfo::getSpecialKeywords() );
272 108 : for(auto const& s : specials ) {
273 105 : std::cout<<" },"<<std::endl;
274 210 : std::cout<<" \""<<s.first<<"\" : { \n"<<std::endl;
275 210 : std::cout<<" \"description\" : \""<<s.second<<"\","<<std::endl;
276 210 : std::cout<<" \"link\" : \"https://www.plumed.org/doc-"<<version<<"/user-doc/html/MOLINFO\""<<std::endl;
277 : }
278 3 : std::cout<<" }"<<std::endl;
279 3 : std::cout<<" },"<<std::endl;
280 3 : std::cout<<" \"modules\" : {"<<std::endl;
281 6 : std::cout<<" \""<<allmodules[0]<<"\" : { "<<std::endl;
282 3 : printHyperlink( "module_" + allmodules[0] );
283 3 : std::cout<<" \"description\" : \"A module that will be used for something\""<<std::endl;
284 150 : for(unsigned i=1; i<allmodules.size(); ++i) {
285 147 : std::cout<<" },"<<std::endl;
286 294 : std::cout<<" \""<<allmodules[i]<<"\" : { "<<std::endl;
287 147 : printHyperlink( "module_" + allmodules[i] );
288 147 : std::cout<<" \"description\" : \"A module that will be used for something\""<<std::endl;
289 : }
290 3 : std::cout<<" }"<<std::endl;
291 3 : std::cout<<" },"<<std::endl;
292 3 : std::cout<<" \"cltools\" : {"<<std::endl;
293 3 : std::vector<std::string> cltool_names( cltoolRegister().list() );
294 60 : for(unsigned i=0; i<cltool_names.size(); ++i) {
295 114 : std::cout<<" \""<<cltool_names[i]<<'"'<<": {"<<std::endl;
296 57 : std::string cltool=cltool_names[i];
297 : // Handle converstion to link
298 57 : printHyperlink( cltool );
299 114 : plumed_massert( getModuleMap().find(cltool)!=getModuleMap().end(), "could not find cltool named " + cltool + " in module map" );
300 114 : std::string thismodule = getModuleMap().find(cltool_names[i])->second;
301 114 : std::cout<<" \"module\" : \""<<thismodule<<"\",\n";
302 57 : auto mytool = cltoolRegister().create( CLToolOptions(cltool) );
303 171 : std::cout<<" \"description\" : \""<<mytool->description()<<"\",\n";
304 57 : if( mytool->inputdata==inputType::commandline ) {
305 48 : std::cout<<" \"inputtype\" : \"command line args\",\n";
306 9 : } else if( mytool->inputdata==inputType::ifile ) {
307 9 : std::cout<<" \"inputtype\" : \"file\",\n";
308 : } else {
309 0 : error("input type for cltool was not specified");
310 : }
311 57 : std::cout<<" \"syntax\" : {"<<std::endl;
312 828 : for(unsigned j=0; j<cltoolRegister().get(cltool).keys.size(); ++j) {
313 771 : std::string k = cltoolRegister().get(cltool).keys.getKeyword(j);
314 771 : printKeywordDocs( k, cltool, cltoolRegister().get(cltool).keys );
315 771 : if( j==cltoolRegister().get(cltool).keys.size()-1 ) {
316 : std::cout<<std::endl;
317 : } else {
318 714 : std::cout<<","<<std::endl;
319 : }
320 : }
321 57 : std::cout<<" }"<<std::endl;
322 57 : std::cout<<" }";
323 57 : if( i==cltool_names.size()-1 ) {
324 : std::cout<<std::endl;
325 : } else {
326 54 : std::cout<<","<<std::endl;
327 : }
328 57 : }
329 3 : std::cout<<" }"<<std::endl;
330 3 : std::cout<<"}"<<std::endl;
331 3 : return 0;
332 9 : }
333 :
334 : } // End of namespace
335 : }
|
