colvarscript.h

// -*- c++ -*-
 
// This file is part of the Collective Variables module (Colvars).
// The original version of Colvars and its updates are located at:
// https://github.com/Colvars/colvars
// Please update all Colvars source files before making any changes.
// If you wish to distribute your changes, please submit them to the
// Colvars repository at GitHub.
 
#ifndef COLVARSCRIPT_H
#define COLVARSCRIPT_H
 
#include <string>
#include <vector>
#include <map>
 
#include "colvarmodule.h"
#include "colvarvalue.h"
#include "colvarproxy.h"
 
 
// Only these error values are part of the scripting interface
#define COLVARSCRIPT_ERROR -1
#define COLVARSCRIPT_OK 0
 
#define COLVARSCRIPT_MAGIC 0x5349474E
 
class colvardeps;
 
class colvarscript {
 
public:
  uint32_t const magic = COLVARSCRIPT_MAGIC;
 
  static bool is_valid(const colvarscript* script_ptr) {
    if (!script_ptr) return false;
    // if address is inaccessible, this will sefgault
    return script_ptr->magic == COLVARSCRIPT_MAGIC;
  }
 
private:
 
  colvarproxy *proxy_;
  colvarmodule *cvmodule;
 
  inline colvarscript() {} // no-argument construction forbidden
 
public:
 
  friend class colvarproxy;
 
  colvarscript(colvarproxy *p, colvarmodule *m);
 
  ~colvarscript();
 
  std::string str_result_;
 
  int run(int objc, unsigned char *const objv[]);
 
  inline std::string const &str_result() const
  {
    return str_result_;
  }
 
  inline std::string &modify_str_result()
  {
    return str_result_;
  }
 
  int set_result_str(std::string const &s);
 
  int clear_str_result();
 
  void add_error_msg(std::string const &s);
 
  enum command {
#define CVSCRIPT_ENUM_COMM(COMM) COMM,
#undef CVSCRIPT
#define CVSCRIPT(COMM,HELP,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY)  \
  CVSCRIPT_ENUM_COMM(COMM)
#ifdef COLVARSCRIPT_COMMANDS_H
#undef COLVARSCRIPT_COMMANDS_H
#endif
#include "colvarscript_commands.h"
#undef COLVARSCRIPT_COMMANDS_H
#undef CVSCRIPT
#undef CVSCRIPT_ENUM_COMM
    cv_n_commands
  };
 
  enum Object_type {
    use_module,
    use_colvar,
    use_bias
  };
 
  std::string get_cmd_prefix(Object_type t);
 
  template<Object_type T>
  unsigned char *get_cmd_arg(int iarg, int objc, unsigned char *const objv[]);
 
  unsigned char *get_module_cmd_arg(int iarg, int objc,
                                    unsigned char *const objv[]);
 
  unsigned char *get_colvar_cmd_arg(int iarg, int objc,
                                    unsigned char *const objv[]);
 
  unsigned char *get_bias_cmd_arg(int iarg, int objc,
                                  unsigned char *const objv[]);
 
  template<Object_type T>
  int check_cmd_nargs(char const *cmd, int objc,
                      int n_args_min, int n_args_max);
 
  int check_module_cmd_nargs(char const *cmd, int objc,
                             int n_args_min, int n_args_max);
 
  int check_colvar_cmd_nargs(char const *cmd, int objc,
                             int n_args_min, int n_args_max);
 
  int check_bias_cmd_nargs(char const *cmd, int objc,
                           int n_args_min, int n_args_max);
 
  template<colvarscript::Object_type T>
  int cmd_arg_shift();
 
  inline char const **get_command_names() const
  {
    return cmd_names;
  }
 
  char const *get_command_help(char const *cmd);
 
  char const *get_command_rethelp(char const *cmd);
 
  char const *get_command_arghelp(char const *cmd, int i);
 
  int get_command_n_args_min(char const *cmd);
 
  int get_command_n_args_max(char const *cmd);
 
  inline void set_cmdline_main_cmd(std::string const &cmd) {
    cmdline_main_cmd_ = cmd;
  }
 
  char const *get_command_full_help(char const *cmd);
 
  std::string get_cmdline_help_summary(Object_type t);
 
  std::string get_command_cmdline_syntax(Object_type t, command c);
 
  std::string get_command_cmdline_help(Object_type t, std::string const &cmd);
 
  int unsupported_op();
 
  inline colvarmodule *module()
  {
    return this->cvmodule;
  }
 
  inline colvarproxy *proxy()
  {
    return this->proxy_;
  }
 
  // Input functions - get the string reps of script argument objects
 
  char *obj_to_str(unsigned char *obj);
 
  std::vector<std::string> obj_to_str_vector(unsigned char *obj);
 
 
  // Output functions - convert internal objects to representations suitable
  // for use in the scripting language.  At the moment only conversion to C
  // strings is supported, and obj is assumed to be a char * pointer.
 
  int set_result_int(int const &x, unsigned char *obj = NULL);
 
  int set_result_int_vec(std::vector<int> const &x, unsigned char *obj = NULL);
 
  int set_result_long_int(long int const &x, unsigned char *obj = NULL);
 
  int set_result_long_int_vec(std::vector<long int> const &x,
                              unsigned char *obj = NULL);
 
  int set_result_real(cvm::real const &x, unsigned char *obj = NULL);
 
  template <typename T>
  int set_result_real_vec(T const &x,
                          unsigned char *obj = NULL);
 
  int set_result_rvector(cvm::rvector const &x, unsigned char *obj = NULL);
 
  template <typename T>
  int set_result_rvector_vec(T const &x,
                             unsigned char *obj = NULL);
 
  int set_result_colvarvalue(colvarvalue const &x, unsigned char *obj = NULL);
 
  int set_result_colvarvalue_vec(std::vector<colvarvalue> const &x,
                                 unsigned char *obj = NULL);
 
private:
 
  int init_commands();
 
  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 *));
 
public: // TODO this function will be removed soon
 
  int proc_features(colvardeps *obj,
                    int argc, unsigned char *const argv[]);
 
private: // TODO
 
  std::map<std::string, command> cmd_str_map;
 
  std::string cmdline_main_cmd_;
 
  char const **cmd_names;
 
  std::vector<std::string> cmd_help;
 
  std::vector<std::string> cmd_rethelp;
 
  std::vector<size_t> cmd_n_args_min;
 
  std::vector<size_t> cmd_n_args_max;
 
  std::vector< std::vector<std::string> > cmd_arghelp;
 
  std::vector<std::string> cmd_full_help;
 
  std::vector<int (*)(void *, int, unsigned char * const *)> cmd_fns;
 
  inline int (*get_cmd_fn(std::string const &cmd_key))(void *,
                                                       int,
                                                       unsigned char * const *)
  {
    if (cmd_str_map.count(cmd_key) > 0) {
      return cmd_fns[cmd_str_map[cmd_key]];
    }
    return NULL;
  }
 
  template <typename T>
  int set_result_text(T const &x, unsigned char *obj);
 
  template <typename T>
  int pack_vector_elements_text(T const &x, std::string &x_str);
 
  int set_result_text_from_str(std::string const &x_str, unsigned char *obj);
 
 
};
 
 
inline static colvarscript *colvarscript_obj(void *pobj)
{
  return reinterpret_cast<colvarscript *>(pobj);
}
 
inline static colvarscript *colvarscript_obj()
{
  return cvm::main()->proxy->script;
}
 
inline static colvar *colvar_obj(void *pobj)
{
  return reinterpret_cast<colvar *>(pobj);
}
 
 
inline static colvarbias *colvarbias_obj(void *pobj)
{
  return reinterpret_cast<colvarbias *>(pobj);
}
 
 
 
template<colvarscript::Object_type T>
unsigned char *colvarscript::get_cmd_arg(int iarg,
                                         int objc,
                                         unsigned char *const objv[])
{
  int const shift = cmd_arg_shift<T>();
  return (shift+iarg < objc) ? objv[shift+iarg] : NULL;
}
 
 
inline unsigned char *colvarscript::get_module_cmd_arg(int iarg, int objc,
                                                       unsigned char *const objv[])
{
  return get_cmd_arg<use_module>(iarg, objc, objv);
}
 
 
inline unsigned char *colvarscript::get_colvar_cmd_arg(int iarg, int objc,
                                                       unsigned char *const objv[])
{
  return get_cmd_arg<use_colvar>(iarg, objc, objv);
}
 
 
inline unsigned char *colvarscript::get_bias_cmd_arg(int iarg, int objc,
                                                     unsigned char *const objv[])
{
  return get_cmd_arg<use_bias>(iarg, objc, objv);
}
 
 
template<colvarscript::Object_type T>
int colvarscript::check_cmd_nargs(char const *cmd,
                                  int objc,
                                  int n_args_min,
                                  int n_args_max)
{
  int const shift = cmd_arg_shift<T>();
  if (objc < shift+n_args_min) {
    add_error_msg("Insufficient number of arguments ("+cvm::to_str(objc)+
                  ") for script function \""+std::string(cmd)+
                  "\":\n"+get_command_full_help(cmd));
    return COLVARSCRIPT_ERROR;
  }
  if (objc > shift+n_args_max) {
    add_error_msg("Too many arguments ("+cvm::to_str(objc)+
                  ") for script function \""+std::string(cmd)+
                  "\":\n"+get_command_full_help(cmd));
    return COLVARSCRIPT_ERROR;
  }
  return COLVARSCRIPT_OK;
}
 
 
inline int colvarscript::check_module_cmd_nargs(char const *cmd,
                                                int objc,
                                                int n_args_min,
                                                int n_args_max)
{
  return check_cmd_nargs<use_module>(cmd, objc, n_args_min, n_args_max);
}
 
 
inline int colvarscript::check_colvar_cmd_nargs(char const *cmd,
                                                int objc,
                                                int n_args_min,
                                                int n_args_max)
{
  return check_cmd_nargs<use_colvar>(cmd, objc, n_args_min, n_args_max);
}
 
 
inline int colvarscript::check_bias_cmd_nargs(char const *cmd,
                                              int objc,
                                              int n_args_min,
                                              int n_args_max)
{
  return check_cmd_nargs<use_bias>(cmd, objc, n_args_min, n_args_max);
}
 
 
template<colvarscript::Object_type T>
int colvarscript::cmd_arg_shift()
{
  int shift = 0;
  if (T == use_module) {
    // "cv" and "COMMAND" are 1st and 2nd argument, and shift is equal to 2
    shift = 2;
  } else if (T == use_colvar) {
    // Same as above with additional arguments "colvar" and "NAME"
    shift = 4;
  } else if (T == use_bias) {
    shift = 4;
  }
  return shift;
}
 
 
extern "C" {
 
  // New: requires pointer to colvarscript object - TODO - pass it in ctypes Python example
  int run_colvarscript_command(colvarscript *script, int objc, unsigned char *const objv[]);
 
  const char * get_colvarscript_result();
 
}
 
#endif // #ifndef COLVARSCRIPT_H