---

colvarscript.h

Go to the documentation of this file.

// -*- 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 "colvarbias.h"
#include "colvarproxy.h"


// Only these error values are part of the scripting interface
#define COLVARSCRIPT_ERROR -1
#define COLVARSCRIPT_OK 0


class colvarscript  {

private:

  colvarproxy *proxy_;
  colvarmodule *colvars;

  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);

  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->colvars;
  }

  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);

  int set_result_real_vec(std::vector<cvm::real> const &x,
                          unsigned char *obj = NULL);

  int set_result_rvector(cvm::rvector const &x, unsigned char *obj = NULL);

  int set_result_rvector_vec(std::vector<cvm::rvector> 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;

  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(std::vector<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()
{
  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" {

  int run_colvarscript_command(int objc, unsigned char *const objv[]);

  const char * get_colvarscript_result();

}


#endif // #ifndef COLVARSCRIPT_H

---