Collective Variables Module - Developer Documentation
Loading...
Searching...
No Matches
colvarscript.h
1// -*- c++ -*-
2
3// This file is part of the Collective Variables module (Colvars).
4// The original version of Colvars and its updates are located at:
5// https://github.com/Colvars/colvars
6// Please update all Colvars source files before making any changes.
7// If you wish to distribute your changes, please submit them to the
8// Colvars repository at GitHub.
9
10#ifndef COLVARSCRIPT_H
11#define COLVARSCRIPT_H
12
13#include <string>
14#include <vector>
15#include <map>
16
17#include "colvarmodule.h"
18#include "colvarvalue.h"
19#include "colvarproxy.h"
20
21
22// Only these error values are part of the scripting interface
23#define COLVARSCRIPT_ERROR -1
24#define COLVARSCRIPT_OK 0
25
26
27class colvardeps;
28
30
31private:
32
33 colvarproxy *proxy_;
34 colvarmodule *colvars;
35
36 inline colvarscript() {} // no-argument construction forbidden
37
38public:
39
40 friend class colvarproxy;
41
43
45
47 std::string str_result_;
48
50 int run(int objc, unsigned char *const objv[]);
51
53 inline std::string const &str_result() const
54 {
55 return str_result_;
56 }
57
59 inline std::string &modify_str_result()
60 {
61 return str_result_;
62 }
63
65 int set_result_str(std::string const &s);
66
68 int clear_str_result();
69
71 void add_error_msg(std::string const &s);
72
74 enum command {
75#define CVSCRIPT_ENUM_COMM(COMM) COMM,
76#undef CVSCRIPT
77#define CVSCRIPT(COMM,HELP,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY) \
78 CVSCRIPT_ENUM_COMM(COMM)
79#ifdef COLVARSCRIPT_COMMANDS_H
80#undef COLVARSCRIPT_COMMANDS_H
81#endif
82#include "colvarscript_commands.h"
83#undef COLVARSCRIPT_COMMANDS_H
84#undef CVSCRIPT
85#undef CVSCRIPT_ENUM_COMM
86 cv_n_commands
87 };
88
91 use_module,
92 use_colvar,
93 use_bias
94 };
95
97 std::string get_cmd_prefix(Object_type t);
98
100 template<Object_type T>
101 unsigned char *get_cmd_arg(int iarg, int objc, unsigned char *const objv[]);
102
104 unsigned char *get_module_cmd_arg(int iarg, int objc,
105 unsigned char *const objv[]);
106
108 unsigned char *get_colvar_cmd_arg(int iarg, int objc,
109 unsigned char *const objv[]);
110
112 unsigned char *get_bias_cmd_arg(int iarg, int objc,
113 unsigned char *const objv[]);
114
116 template<Object_type T>
117 int check_cmd_nargs(char const *cmd, int objc,
118 int n_args_min, int n_args_max);
119
121 int check_module_cmd_nargs(char const *cmd, int objc,
122 int n_args_min, int n_args_max);
123
125 int check_colvar_cmd_nargs(char const *cmd, int objc,
126 int n_args_min, int n_args_max);
127
129 int check_bias_cmd_nargs(char const *cmd, int objc,
130 int n_args_min, int n_args_max);
131
133 template<colvarscript::Object_type T>
134 int cmd_arg_shift();
135
137 inline char const **get_command_names() const
138 {
139 return cmd_names;
140 }
141
144 char const *get_command_help(char const *cmd);
145
148 char const *get_command_rethelp(char const *cmd);
149
155 char const *get_command_arghelp(char const *cmd, int i);
156
159 int get_command_n_args_min(char const *cmd);
160
163 int get_command_n_args_max(char const *cmd);
164
166 inline void set_cmdline_main_cmd(std::string const &cmd) {
167 cmdline_main_cmd_ = cmd;
168 }
169
172 char const *get_command_full_help(char const *cmd);
173
177
182
186 std::string get_command_cmdline_help(Object_type t, std::string const &cmd);
187
189 int unsupported_op();
190
193 {
194 return this->colvars;
195 }
196
199 {
200 return this->proxy_;
201 }
202
203 // Input functions - get the string reps of script argument objects
204
206 char *obj_to_str(unsigned char *obj);
207
209 std::vector<std::string> obj_to_str_vector(unsigned char *obj);
210
211
212 // Output functions - convert internal objects to representations suitable
213 // for use in the scripting language. At the moment only conversion to C
214 // strings is supported, and obj is assumed to be a char * pointer.
215
217 int set_result_int(int const &x, unsigned char *obj = NULL);
218
220 int set_result_int_vec(std::vector<int> const &x, unsigned char *obj = NULL);
221
223 int set_result_long_int(long int const &x, unsigned char *obj = NULL);
224
226 int set_result_long_int_vec(std::vector<long int> const &x,
227 unsigned char *obj = NULL);
228
230 int set_result_real(cvm::real const &x, unsigned char *obj = NULL);
231
233 int set_result_real_vec(std::vector<cvm::real> const &x,
234 unsigned char *obj = NULL);
235
237 int set_result_rvector(cvm::rvector const &x, unsigned char *obj = NULL);
238
240 int set_result_rvector_vec(std::vector<cvm::rvector> const &x,
241 unsigned char *obj = NULL);
242
244 int set_result_colvarvalue(colvarvalue const &x, unsigned char *obj = NULL);
245
247 int set_result_colvarvalue_vec(std::vector<colvarvalue> const &x,
248 unsigned char *obj = NULL);
249
250private:
251
253 int init_commands();
254
256 int init_command(colvarscript::command const &comm,
257 char const *name, char const *help,
258 int n_args_min, int n_args_max, char const *arghelp,
259 int (*fn)(void *, int, unsigned char * const *));
260
261public: // TODO this function will be removed soon
262
264 int proc_features(colvardeps *obj,
265 int argc, unsigned char *const argv[]);
266
267private: // TODO
268
270 std::map<std::string, command> cmd_str_map;
271
273 std::string cmdline_main_cmd_;
274
276 char const **cmd_names;
277
279 std::vector<std::string> cmd_help;
280
282 std::vector<std::string> cmd_rethelp;
283
285 std::vector<size_t> cmd_n_args_min;
286
288 std::vector<size_t> cmd_n_args_max;
289
291 std::vector< std::vector<std::string> > cmd_arghelp;
292
294 std::vector<std::string> cmd_full_help;
295
297 std::vector<int (*)(void *, int, unsigned char * const *)> cmd_fns;
298
300 inline int (*get_cmd_fn(std::string const &cmd_key))(void *,
301 int,
302 unsigned char * const *)
303 {
304 if (cmd_str_map.count(cmd_key) > 0) {
305 return cmd_fns[cmd_str_map[cmd_key]];
306 }
307 return NULL;
308 }
309
311 template <typename T>
312 int set_result_text(T const &x, unsigned char *obj);
313
315 template <typename T>
316 int pack_vector_elements_text(std::vector<T> const &x, std::string &x_str);
317
319 int set_result_text_from_str(std::string const &x_str, unsigned char *obj);
320
321
322};
323
324
326inline static colvarscript *colvarscript_obj()
327{
328 return cvm::main()->proxy->script;
329}
330
331
333inline static colvar *colvar_obj(void *pobj)
334{
335 return reinterpret_cast<colvar *>(pobj);
336}
337
338
340inline static colvarbias *colvarbias_obj(void *pobj)
341{
342 return reinterpret_cast<colvarbias *>(pobj);
343}
344
345
346
347template<colvarscript::Object_type T>
348unsigned char *colvarscript::get_cmd_arg(int iarg,
349 int objc,
350 unsigned char *const objv[])
351{
352 int const shift = cmd_arg_shift<T>();
353 return (shift+iarg < objc) ? objv[shift+iarg] : NULL;
354}
355
356
357inline unsigned char *colvarscript::get_module_cmd_arg(int iarg, int objc,
358 unsigned char *const objv[])
359{
360 return get_cmd_arg<use_module>(iarg, objc, objv);
361}
362
363
364inline unsigned char *colvarscript::get_colvar_cmd_arg(int iarg, int objc,
365 unsigned char *const objv[])
366{
367 return get_cmd_arg<use_colvar>(iarg, objc, objv);
368}
369
370
371inline unsigned char *colvarscript::get_bias_cmd_arg(int iarg, int objc,
372 unsigned char *const objv[])
373{
374 return get_cmd_arg<use_bias>(iarg, objc, objv);
375}
376
377
378template<colvarscript::Object_type T>
380 int objc,
381 int n_args_min,
382 int n_args_max)
383{
384 int const shift = cmd_arg_shift<T>();
385 if (objc < shift+n_args_min) {
386 add_error_msg("Insufficient number of arguments ("+cvm::to_str(objc)+
387 ") for script function \""+std::string(cmd)+
388 "\":\n"+get_command_full_help(cmd));
389 return COLVARSCRIPT_ERROR;
390 }
391 if (objc > shift+n_args_max) {
392 add_error_msg("Too many arguments ("+cvm::to_str(objc)+
393 ") for script function \""+std::string(cmd)+
394 "\":\n"+get_command_full_help(cmd));
395 return COLVARSCRIPT_ERROR;
396 }
397 return COLVARSCRIPT_OK;
398}
399
400
401inline int colvarscript::check_module_cmd_nargs(char const *cmd,
402 int objc,
403 int n_args_min,
404 int n_args_max)
405{
406 return check_cmd_nargs<use_module>(cmd, objc, n_args_min, n_args_max);
407}
408
409
410inline int colvarscript::check_colvar_cmd_nargs(char const *cmd,
411 int objc,
412 int n_args_min,
413 int n_args_max)
414{
415 return check_cmd_nargs<use_colvar>(cmd, objc, n_args_min, n_args_max);
416}
417
418
419inline int colvarscript::check_bias_cmd_nargs(char const *cmd,
420 int objc,
421 int n_args_min,
422 int n_args_max)
423{
424 return check_cmd_nargs<use_bias>(cmd, objc, n_args_min, n_args_max);
425}
426
427
428template<colvarscript::Object_type T>
430{
431 int shift = 0;
432 if (T == use_module) {
433 // "cv" and "COMMAND" are 1st and 2nd argument, and shift is equal to 2
434 shift = 2;
435 } else if (T == use_colvar) {
436 // Same as above with additional arguments "colvar" and "NAME"
437 shift = 4;
438 } else if (T == use_bias) {
439 shift = 4;
440 }
441 return shift;
442}
443
444
445extern "C" {
446
448 int run_colvarscript_command(int objc, unsigned char *const objv[]);
449
451 const char * get_colvarscript_result();
452
453}
454
455
456#endif // #ifndef COLVARSCRIPT_H
A collective variable (main class); to be defined, it needs at least one object of a derived class of...
Definition: colvar.h:53
Collective variable bias, base class.
Definition: colvarbias.h:23
Parent class for a member object of a bias, cv or cvc etc. containing features and their dependencies...
Definition: colvardeps.h:34
vector of real numbers with three components
Definition: colvartypes.h:727
Collective variables module (main class)
Definition: colvarmodule.h:59
double real
Defining an abstract real number allows to switch precision.
Definition: colvarmodule.h:95
static colvarmodule * main()
Access the one instance of the Colvars module.
Definition: colvarmodule.cpp:174
static colvarproxy * proxy
Pointer to the proxy object, used to retrieve atomic data from the hosting program; it is static in o...
Definition: colvarmodule.h:860
static std::string to_str(char const *s)
Convert to string for output purposes.
Definition: colvarmodule.cpp:2378
colvarscript * script
Definition: colvarproxy.h:539
Definition: colvarproxy.h:573
Definition: colvarscript.h:29
int clear_str_result()
Clear the string result.
Definition: colvarscript.cpp:606
int set_result_long_int(long int const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:883
int set_result_real(cvm::real const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:893
char const * get_command_arghelp(char const *cmd, int i)
Definition: colvarscript.cpp:211
int set_result_rvector_vec(std::vector< cvm::rvector > const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:907
int proc_features(colvardeps *obj, int argc, unsigned char *const argv[])
Run subcommands on base colvardeps object (colvar, bias, ...)
Definition: colvarscript.cpp:506
void add_error_msg(std::string const &s)
Add the given string to the error message of the script interface.
Definition: colvarscript.cpp:596
int run(int objc, unsigned char *const objv[])
Run a script command with space-separated positional arguments (objects)
Definition: colvarscript.cpp:347
int set_result_str(std::string const &s)
Set the return value to the given string.
Definition: colvarscript.cpp:584
std::string & modify_str_result()
Modify the string result of the current scripting call.
Definition: colvarscript.h:59
char const * get_command_rethelp(char const *cmd)
Definition: colvarscript.cpp:199
std::string const & str_result() const
Get the string result of the current scripting call.
Definition: colvarscript.h:53
int set_result_long_int_vec(std::vector< long int > const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:887
void set_cmdline_main_cmd(std::string const &cmd)
Set the main command for the CLI, when it is not "cv" (e.g. LAMMPS)
Definition: colvarscript.h:166
int set_result_text(T const &x, unsigned char *obj)
Set obj equal to x, using its string representation.
Definition: colvarscript.cpp:780
int pack_vector_elements_text(std::vector< T > const &x, std::string &x_str)
Code reused by instances of set_result_text()
Definition: colvarscript.cpp:787
command
Commands available.
Definition: colvarscript.h:74
std::vector< std::string > obj_to_str_vector(unsigned char *obj)
Get a list of strings from an object (does not work with a simple cast)
Definition: colvarscript.cpp:463
int set_result_colvarvalue(colvarvalue const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:913
int unsupported_op()
Set error code for unsupported script operation.
Definition: colvarscript.cpp:577
std::map< std::string, command > cmd_str_map
Internal identifiers of command strings.
Definition: colvarscript.h:270
int set_result_text_from_str(std::string const &x_str, unsigned char *obj)
Code reused by all instances of set_result_text()
Definition: colvarscript.cpp:767
int set_result_int(int const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:873
int check_module_cmd_nargs(char const *cmd, int objc, int n_args_min, int n_args_max)
Instantiation of check_cmd_nargs<> for module-level commands.
Definition: colvarscript.h:401
char * obj_to_str(unsigned char *obj)
Get the string representation of an object (by default, a simple cast)
Definition: colvarscript.cpp:452
char const * get_command_help(char const *cmd)
Definition: colvarscript.cpp:187
int init_command(colvarscript::command const &comm, char const *name, char const *help, int n_args_min, int n_args_max, char const *arghelp, int(*fn)(void *, int, unsigned char *const *))
Set up a single script API function.
Definition: colvarscript.cpp:104
int check_colvar_cmd_nargs(char const *cmd, int objc, int n_args_min, int n_args_max)
Instantiation of check_cmd_nargs<> for colvar-level commands.
Definition: colvarscript.h:410
int cmd_arg_shift()
Number of positional arguments to shift for each object type.
Definition: colvarscript.h:429
std::vector< size_t > cmd_n_args_max
Maximum number of arguments for each command.
Definition: colvarscript.h:288
char const * get_command_full_help(char const *cmd)
Definition: colvarscript.cpp:247
int get_command_n_args_min(char const *cmd)
Definition: colvarscript.cpp:223
unsigned char * get_colvar_cmd_arg(int iarg, int objc, unsigned char *const objv[])
Instantiation of get_cmd_arg<> for colvar-level commands.
Definition: colvarscript.h:364
colvarmodule * module()
Pointer to the Colvars main object.
Definition: colvarscript.h:192
std::vector< std::string > cmd_rethelp
Description of the return values of each command (may be empty)
Definition: colvarscript.h:282
int check_bias_cmd_nargs(char const *cmd, int objc, int n_args_min, int n_args_max)
Instantiation of get_cmd_arg<> for bias-level commands.
Definition: colvarscript.h:419
char const ** get_command_names() const
Get names of all commands.
Definition: colvarscript.h:137
std::vector< size_t > cmd_n_args_min
Minimum number of arguments for each command.
Definition: colvarscript.h:285
unsigned char * get_cmd_arg(int iarg, int objc, unsigned char *const objv[])
Get a pointer to the i-th argument of the command (NULL if not given)
Definition: colvarscript.h:348
char const ** cmd_names
Inverse of cmd_str_map (to be exported outside this class)
Definition: colvarscript.h:276
int set_result_colvarvalue_vec(std::vector< colvarvalue > const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:918
int set_result_rvector(cvm::rvector const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:903
unsigned char * get_bias_cmd_arg(int iarg, int objc, unsigned char *const objv[])
Instantiation of get_cmd_arg<> for bias-level commands.
Definition: colvarscript.h:371
Object_type
Type of object handling a script command.
Definition: colvarscript.h:90
int get_command_n_args_max(char const *cmd)
Definition: colvarscript.cpp:235
colvarproxy * proxy()
Pointer to the colvarproxy object (interface with host engine)
Definition: colvarscript.h:198
unsigned char * get_module_cmd_arg(int iarg, int objc, unsigned char *const objv[])
Instantiation of get_cmd_arg<> for module-level commands.
Definition: colvarscript.h:357
int set_result_int_vec(std::vector< int > const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:877
int init_commands()
Set up all script API functions.
Definition: colvarscript.cpp:65
std::string get_command_cmdline_syntax(Object_type t, command c)
Definition: colvarscript.cpp:259
std::vector< std::vector< std::string > > cmd_arghelp
Help strings for each command argument.
Definition: colvarscript.h:291
int(*)(void *, int, unsigned char *const *) get_cmd_fn(std::string const &cmd_key)
Get a pointer to the implementation of the given command.
Definition: colvarscript.h:300
std::string cmdline_main_cmd_
Main command used in command line ("cv" by default)
Definition: colvarscript.h:273
std::string get_cmdline_help_summary(Object_type t)
Definition: colvarscript.cpp:301
int check_cmd_nargs(char const *cmd, int objc, int n_args_min, int n_args_max)
Check the argument count of the command.
Definition: colvarscript.h:379
std::vector< std::string > cmd_help
Help strings for each command.
Definition: colvarscript.h:279
std::string get_cmd_prefix(Object_type t)
Return the prefix of the individual command for each object function.
Definition: colvarscript.cpp:170
std::string get_command_cmdline_help(Object_type t, std::string const &cmd)
Definition: colvarscript.cpp:333
int set_result_real_vec(std::vector< cvm::real > const &x, unsigned char *obj=NULL)
Copy x into obj if not NULL, or into the script object's result otherwise.
Definition: colvarscript.cpp:897
std::vector< std::string > cmd_full_help
Full help strings for each command.
Definition: colvarscript.h:294
std::string str_result_
String representation of the result of a script call.
Definition: colvarscript.h:47
std::vector< int(*)(void *, int, unsigned char *const *)> cmd_fns
Implementations of each command.
Definition: colvarscript.h:297
Value of a collective variable: this is a metatype which can be set at runtime. By default it is set ...
Definition: colvarvalue.h:43
Collective variables main module.
Colvars proxy classes.