src/gmxlib/selection/selmethod.c

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2009, The GROMACS development team,
   6  * check out http://www.gromacs.org for more information.
   7  * Copyright (c) 2012, by the GROMACS development team, led by
   8  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   9  * others, as listed in the AUTHORS file in the top-level source
  10  * directory and at http://www.gromacs.org.
  11  *
  12  * GROMACS is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public License
  14  * as published by the Free Software Foundation; either version 2.1
  15  * of the License, or (at your option) any later version.
  16  *
  17  * GROMACS is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with GROMACS; if not, see
  24  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  26  *
  27  * If you want to redistribute modifications to GROMACS, please
  28  * consider that scientific software is very special. Version
  29  * control is crucial - bugs must be traceable. We will be happy to
  30  * consider code for inclusion in the official distribution, but
  31  * derived work must not be called official GROMACS. Details are found
  32  * in the README & COPYING files - if they are missing, get the
  33  * official version at http://www.gromacs.org.
  34  *
  35  * To help us fund GROMACS development, we humbly ask that you cite
  36  * the research papers on the package. Check out http://www.gromacs.org.
  37  */
  38 /*! \internal \file
  39  * \brief Implementation of functions in selmethod.h.
  40  */
  41 #ifdef HAVE_CONFIG_H
  42 #include <config.h>
  43 #endif
  44
  45 #include <ctype.h>
  46 #include <stdarg.h>
  47
  48 #include <macros.h>
  49 #include <string2.h>
  50
  51 #include <selmethod.h>
  52
  53 #include "selcollection.h"
  54 #include "symrec.h"
  55
  56 /*
  57  * These global variables cannot be const because gmx_ana_selmethod_register()
  58  * modifies them to set some defaults. This is a small price to pay for the
  59  * convenience of not having to remember exactly how the selection compiler
  60  * expects the structures to be filled, and even more so if the expectations
  61  * change. Also, even if the gmx_ana_selmethod_t structures were made const,
  62  * the parameters could not be without typecasts somewhere, because the param
  63  * field in gmx_ana_selmethod_t cannot be declared const.
  64  *
  65  * Even though the variables may be modified, this should be thread-safe as
  66  * modifications are done only in gmx_ana_selmethod_register(), and it should
  67  * work even if called more than once for the same structure, and even if
  68  * called concurrently from multiple threads (as long as the selection
  69  * collection is not the same).
  70  *
  71  * All of these problems should go away if/when the selection methods are
  72  * implemented as C++ classes.
  73  */
  74
  75 /* From sm_com.c */
  76 extern gmx_ana_selmethod_t sm_cog;
  77 extern gmx_ana_selmethod_t sm_com;
  78 /* From sm_simple.c */
  79 extern gmx_ana_selmethod_t sm_all;
  80 extern gmx_ana_selmethod_t sm_none;
  81 extern gmx_ana_selmethod_t sm_atomnr;
  82 extern gmx_ana_selmethod_t sm_resnr;
  83 extern gmx_ana_selmethod_t sm_resindex;
  84 extern gmx_ana_selmethod_t sm_molindex;
  85 extern gmx_ana_selmethod_t sm_atomname;
  86 extern gmx_ana_selmethod_t sm_pdbatomname;
  87 extern gmx_ana_selmethod_t sm_atomtype;
  88 extern gmx_ana_selmethod_t sm_resname;
  89 extern gmx_ana_selmethod_t sm_insertcode;
  90 extern gmx_ana_selmethod_t sm_chain;
  91 extern gmx_ana_selmethod_t sm_mass;
  92 extern gmx_ana_selmethod_t sm_charge;
  93 extern gmx_ana_selmethod_t sm_altloc;
  94 extern gmx_ana_selmethod_t sm_occupancy;
  95 extern gmx_ana_selmethod_t sm_betafactor;
  96 extern gmx_ana_selmethod_t sm_x;
  97 extern gmx_ana_selmethod_t sm_y;
  98 extern gmx_ana_selmethod_t sm_z;
  99 /* From sm_distance.c */
 100 extern gmx_ana_selmethod_t sm_distance;
 101 extern gmx_ana_selmethod_t sm_mindistance;
 102 extern gmx_ana_selmethod_t sm_within;
 103 /* From sm_insolidangle.c */
 104 extern gmx_ana_selmethod_t sm_insolidangle;
 105 /* From sm_same.c */
 106 extern gmx_ana_selmethod_t sm_same;
 107
 108 /* From sm_merge.c */
 109 extern gmx_ana_selmethod_t sm_merge;
 110 extern gmx_ana_selmethod_t sm_plus;
 111 /* From sm_permute.c */
 112 extern gmx_ana_selmethod_t sm_permute;
 113
 114 /*! \brief
 115  * Helper structure for defining selection methods.
 116  */
 117 typedef struct {
 118     /*! \brief
 119      * Name to register the method under.
 120      *
 121      * If NULL, use the actual name of the method.
 122      * This field is used for defining synonyms.
 123      */
 124     const char            *name;
 125     /** Method data structure to register. */
 126     gmx_ana_selmethod_t   *method;
 127 } t_register_method;
 128
 129 /** Array of selection methods defined in the library. */
 130 static const t_register_method smtable_def[] = {
 131     {NULL,         &sm_cog},
 132     {NULL,         &sm_com},
 133
 134     {NULL,         &sm_all},
 135     {NULL,         &sm_none},
 136     {NULL,         &sm_atomnr},
 137     {NULL,         &sm_resnr},
 138     {"resid",      &sm_resnr},
 139     {NULL,         &sm_resindex},
 140     {"residue",    &sm_resindex},
 141     {NULL,         &sm_molindex},
 142     {"mol",        &sm_molindex},
 143     {"molecule",   &sm_molindex},
 144     {NULL,         &sm_atomname},
 145     {"name",       &sm_atomname},
 146     {NULL,         &sm_pdbatomname},
 147     {"pdbname",    &sm_pdbatomname},
 148     {NULL,         &sm_atomtype},
 149     {"type",       &sm_atomtype},
 150     {NULL,         &sm_resname},
 151     {NULL,         &sm_insertcode},
 152     {NULL,         &sm_chain},
 153     {NULL,         &sm_mass},
 154     {NULL,         &sm_charge},
 155     {NULL,         &sm_altloc},
 156     {NULL,         &sm_occupancy},
 157     {NULL,         &sm_betafactor},
 158     {NULL,         &sm_x},
 159     {NULL,         &sm_y},
 160     {NULL,         &sm_z},
 161
 162     {NULL,         &sm_distance},
 163     {NULL,         &sm_mindistance},
 164     {NULL,         &sm_within},
 165     {NULL,         &sm_insolidangle},
 166     {NULL,         &sm_same},
 167
 168     {NULL,         &sm_merge},
 169     {NULL,         &sm_plus},
 170     {NULL,         &sm_permute},
 171 };
 172
 173 /*! \brief
 174  * Convenience function for reporting errors found in selection methods.
 175  */
 176 static void
 177 report_error(FILE *fp, const char *name, const char *fmt, ...)
 178 {
 179     va_list ap;
 180     va_start(ap, fmt);
 181     if (fp)
 182     {
 183         fprintf(fp, "selection method '%s': ", name);
 184         vfprintf(fp, fmt, ap);
 185         fprintf(fp, "\n");
 186     }
 187     va_end(ap);
 188 }
 189
 190 /*! \brief
 191  * Convenience function for reporting errors found in selection method parameters.
 192  */
 193 static void
 194 report_param_error(FILE *fp, const char *mname, const char *pname,
 195                    const char *fmt, ...)
 196 {
 197     va_list ap;
 198     va_start(ap, fmt);
 199     if (fp)
 200     {
 201         fprintf(fp, "selection method '%s': parameter '%s': ", mname, pname);
 202         vfprintf(fp, fmt, ap);
 203         fprintf(fp, "\n");
 204     }
 205     va_end(ap);
 206 }
 207
 208 /*! \brief
 209  * Checks the validity of parameters.
 210  *
 211  * \param[in]     fp      File handle to use for diagnostic messages
 212  *   (can be NULL).
 213  * \param[in]     name    Name of the method (used for error messages).
 214  * \param[in]     nparams Number of parameters in \p param.
 215  * \param[in,out] param   Parameter array
 216  *   (only the \c flags field of gmx_boolean parameters may be modified).
 217  * \param[in]     symtab  Symbol table (used for checking overlaps).
 218  * \returns       TRUE if there are no problems with the parameters,
 219  *   FALSE otherwise.
 220  *
 221  * This function performs some checks common to both check_method() and
 222  * check_modifier().
 223  * The purpose of these checks is to ensure that the selection parser does not
 224  * need to check for the validity of the parameters at each turn, and to
 225  * report programming errors as early as possible.
 226  * If you remove a check, make sure that the parameter parser can handle the
 227  * resulting parameters.
 228  */
 229 static gmx_bool
 230 check_params(FILE *fp, const char *name, int nparams, gmx_ana_selparam_t param[],
 231              gmx_sel_symtab_t *symtab)
 232 {
 233     gmx_bool              bOk = TRUE;
 234     gmx_sel_symrec_t *sym;
 235     int               i, j;
 236
 237     if (nparams > 0 && !param)
 238     {
 239         report_error(fp, name, "error: missing parameter data");
 240         return FALSE;
 241     }
 242     if (nparams == 0 && param)
 243     {
 244         report_error(fp, name, "warning: parameter data unused because nparams=0");
 245     }
 246     /* Check each parameter */
 247     for (i = 0; i < nparams; ++i)
 248     {
 249         /* Check that there is at most one NULL name, in the beginning */
 250         if (param[i].name == NULL && i > 0)
 251         {
 252             report_error(fp, name, "error: NULL parameter should be the first one");
 253             bOk = FALSE;
 254             continue;
 255         }
 256         /* Check for duplicates */
 257         for (j = 0; j < i; ++j)
 258         {
 259             if (param[j].name == NULL)
 260             {
 261                 continue;
 262             }
 263             if (!gmx_strcasecmp(param[i].name, param[j].name))
 264             {
 265                 report_error(fp, name, "error: duplicate parameter name '%s'", param[i].name);
 266                 bOk = FALSE;
 267                 break;
 268             }
 269         }
 270         /* Check flags */
 271         if (param[i].flags & SPAR_SET)
 272         {
 273             report_param_error(fp, name, param[i].name, "warning: flag SPAR_SET is set");
 274             param[i].flags &= ~SPAR_SET;
 275         }
 276         if (param[i].flags & SPAR_RANGES)
 277         {
 278             if (param[i].val.type != INT_VALUE && param[i].val.type != REAL_VALUE)
 279             {
 280                 report_param_error(fp, name, param[i].name, "error: SPAR_RANGES cannot be set for a non-numeric parameter");
 281                 bOk = FALSE;
 282             }
 283             if (param[i].flags & SPAR_DYNAMIC)
 284             {
 285                 report_param_error(fp, name, param[i].name, "warning: SPAR_DYNAMIC does not have effect with SPAR_RANGES");
 286                 param[i].flags &= ~SPAR_DYNAMIC;
 287             }
 288             if (!(param[i].flags & SPAR_VARNUM) && param[i].val.nr != 1)
 289             {
 290                 report_param_error(fp, name, param[i].name, "error: range should take either one or an arbitrary number of values");
 291                 bOk = FALSE;
 292             }
 293             if (param[i].flags & SPAR_ATOMVAL)
 294             {
 295                 report_param_error(fp, name, param[i].name, "error: SPAR_RANGES and SPAR_ATOMVAL both set");
 296                 bOk = FALSE;
 297             }
 298         }
 299         if ((param[i].flags & SPAR_VARNUM) && (param[i].flags & SPAR_ATOMVAL))
 300         {
 301             report_param_error(fp, name, param[i].name, "error: SPAR_VARNUM and SPAR_ATOMVAL both set");
 302             bOk = FALSE;
 303         }
 304         if (param[i].flags & SPAR_ENUMVAL)
 305         {
 306             if (param[i].val.type != STR_VALUE)
 307             {
 308                 report_param_error(fp, name, param[i].name, "error: SPAR_ENUMVAL can only be set for string parameters");
 309                 bOk = FALSE;
 310             }
 311             if (param[i].val.nr != 1)
 312             {
 313                 report_param_error(fp, name, param[i].name, "error: SPAR_ENUMVAL parameters should take exactly one value");
 314                 bOk = FALSE;
 315             }
 316             if (param[i].flags & (SPAR_DYNAMIC | SPAR_VARNUM | SPAR_ATOMVAL))
 317             {
 318                 report_param_error(fp, name, param[i].name, "error: only SPAR_OPTIONAL supported with SPAR_ENUMVAL");
 319                 bOk = FALSE;
 320             }
 321         }
 322         /* Check gmx_boolean parameters */
 323         if (param[i].val.type == NO_VALUE)
 324         {
 325             if (param[i].val.nr != 0)
 326             {
 327                 report_param_error(fp, name, param[i].name, "error: number of values should be zero for gmx_boolean parameters");
 328                 bOk = FALSE;
 329             }
 330             /* The gmx_boolean parameters should always be optional, so set the
 331              * flag for convenience. */
 332             param[i].flags |= SPAR_OPTIONAL;
 333             /* Any other flags should not be specified */
 334             if (param[i].flags & ~SPAR_OPTIONAL)
 335             {
 336                 report_param_error(fp, name, param[i].name, "error: gmx_boolean parameter should not have any flags set");
 337                 bOk = FALSE;
 338             }
 339         }
 340         /* Check val.nr */
 341         if (param[i].flags & (SPAR_VARNUM | SPAR_ATOMVAL))
 342         {
 343             if (param[i].val.nr != -1)
 344             {
 345                 report_param_error(fp, name, param[i].name, "warning: val.nr is not -1 although SPAR_VARNUM/SPAR_ATOMVAL is set");
 346             }
 347             param[i].val.nr = -1;
 348         }
 349         else if (param[i].val.type != NO_VALUE)
 350         {
 351             if (param[i].val.nr <= 0)
 352             {
 353                 report_param_error(fp, name, param[i].name, "error: val.nr <= 0");
 354                 bOk = FALSE;
 355             }
 356         }
 357         /* Check that the value pointer is NULL */
 358         if (param[i].nvalptr != NULL)
 359         {
 360             report_param_error(fp, name, param[i].name, "warning: nvalptr is set");
 361         }
 362         if (param[i].val.u.ptr != NULL && !(param[i].flags & SPAR_ENUMVAL))
 363         {
 364             report_param_error(fp, name, param[i].name, "warning: value pointer is set");
 365         }
 366         /* Check that the name contains only valid characters */
 367         if (param[i].name == NULL)
 368         {
 369             continue;
 370         }
 371         if (!isalpha(param[i].name[0]))
 372         {
 373             report_param_error(fp, name, param[i].name, "error: name does not begin with a letter");
 374             bOk = FALSE;
 375             continue;
 376         }
 377         for (j = 1; param[i].name[j] != 0; ++j)
 378         {
 379             if (param[i].name[j] != '_' && !isalnum(param[i].name[j]))
 380             {
 381                 report_param_error(fp, name, param[i].name, "error: name contains non-alphanumeric characters");
 382                 bOk = FALSE;
 383                 break;
 384             }
 385         }
 386         if (param[i].name[j] != 0)
 387         {
 388             continue;
 389         }
 390         /* Check that the name does not conflict with a method */
 391         if (_gmx_sel_find_symbol(symtab, param[i].name, TRUE))
 392         {
 393             report_param_error(fp, name, param[i].name, "error: name conflicts with another method or a keyword");
 394             bOk = FALSE;
 395         }
 396     } /* End of parameter loop */
 397     /* Check parameters of existing methods */
 398     sym = _gmx_sel_first_symbol(symtab, SYMBOL_METHOD);
 399     while (sym)
 400     {
 401         gmx_ana_selmethod_t *method = _gmx_sel_sym_value_method(sym);
 402         gmx_ana_selparam_t  *param =
 403             gmx_ana_selmethod_find_param(name, method);
 404         if (param)
 405         {
 406             report_param_error(fp, method->name, param->name, "error: name conflicts with another method or a keyword");
 407             bOk = FALSE;
 408         }
 409         sym = _gmx_sel_next_symbol(sym, SYMBOL_METHOD);
 410     }
 411     return bOk;
 412 }
 413
 414 /*! \brief
 415  * Checks the validity of selection method callback functions.
 416  *
 417  * \param[in] fp        File handle to use for diagnostic messages
 418  *   (can be NULL).
 419  * \param[in] method    The method to check.
 420  * \returns   TRUE if there are no problems, FALSE otherwise.
 421  *
 422  * This function performs some checks common to both check_method() and
 423  * check_modifier().
 424  * This function checks that all the required callbacks are defined, i.e.,
 425  * not NULL, to find programming errors.
 426  */
 427 static gmx_bool
 428 check_callbacks(FILE *fp, gmx_ana_selmethod_t *method)
 429 {
 430     gmx_bool         bOk = TRUE;
 431     gmx_bool         bNeedInit;
 432     int          i;
 433
 434     /* Make some checks on init_data and free */
 435     if (method->nparams > 0 && !method->init_data)
 436     {
 437         report_error(fp, method->name, "error: init_data should be provided because the method has parameters");
 438         bOk = FALSE;
 439     }
 440     if (method->free && !method->init_data)
 441     {
 442         report_error(fp, method->name, "warning: free is not used because of missing init_data");
 443     }
 444     /* Check presence of outinit for position-valued methods */
 445     if (method->type == POS_VALUE && !method->outinit)
 446     {
 447         report_error(fp, method->name, "error: outinit should be provided because the method has POS_VALUE");
 448         bOk = FALSE;
 449     }
 450     /* Check presence of outinit for variable output count methods */
 451     if ((method->flags & SMETH_VARNUMVAL) && !method->outinit)
 452     {
 453         report_error(fp, method->name, "error: outinit should be provided because the method has SMETH_VARNUMVAL");
 454         bOk = FALSE;
 455     }
 456     /* Warn of dynamic callbacks in static methods */
 457     if (!(method->flags & SMETH_MODIFIER))
 458     {
 459         if (method->pupdate && !(method->flags & SMETH_DYNAMIC))
 460         {
 461             report_error(fp, method->name, "warning: pupdate not used because the method is static");
 462             method->pupdate = NULL;
 463         }
 464     }
 465     /* Check that there is an evaluation function */
 466     if (method->type != NO_VALUE && !method->update && !method->pupdate)
 467     {
 468         report_error(fp, method->name, "error: evaluation function missing");
 469         bOk = FALSE;
 470     }
 471     /* Loop through the parameters to determine if initialization callbacks
 472      * are needed. */
 473     bNeedInit = FALSE;
 474     for (i = 0; i < method->nparams; ++i)
 475     {
 476         if (method->param[i].val.type != POS_VALUE
 477             && (method->param[i].flags & (SPAR_VARNUM | SPAR_ATOMVAL)))
 478         {
 479             bNeedInit = TRUE;
 480         }
 481     }
 482     /* Check that the callbacks required by the parameters are present */
 483     if (bNeedInit && !method->init)
 484     {
 485         report_error(fp, method->name, "error: init should be provided");
 486         bOk = FALSE;
 487     }
 488     return bOk;
 489 }
 490
 491 /*!
 492  * Checks the validity of a selection method.
 493  *
 494  * \param[in]     fp     File handle to use for diagnostic messages
 495  *   (can be NULL).
 496  * \param[in,out] method Method to check.
 497  * \param[in]     symtab Symbol table (used for checking overlaps).
 498  *
 499  * Checks the validity of the given selection method data structure
 500  * that does not have \ref SMETH_MODIFIER set.
 501  * If you remove a check, please make sure that the selection parser,
 502  * compiler, and evaluation functions can deal with the method.
 503  */
 504 static gmx_bool
 505 check_method(FILE *fp, gmx_ana_selmethod_t *method, gmx_sel_symtab_t *symtab)
 506 {
 507     gmx_bool         bOk = TRUE;
 508
 509     /* Check the type */
 510     if (method->type == NO_VALUE)
 511     {
 512         report_error(fp, method->name, "error: no value type specified");
 513         bOk = FALSE;
 514     }
 515     if (method->type == STR_VALUE && method->nparams > 0)
 516     {
 517         report_error(fp, method->name, "error: evaluates to a string but is not a keyword");
 518         bOk = FALSE;
 519     }
 520     /* Check flags */
 521     if (method->type == GROUP_VALUE)
 522     {
 523         /* Group methods should always have SMETH_SINGLEVAL,
 524          * so set it for convenience. */
 525         method->flags |= SMETH_SINGLEVAL;
 526         /* Check that conflicting flags are not present. */
 527         if (method->flags & SMETH_VARNUMVAL)
 528         {
 529             report_error(fp, method->name, "error: SMETH_VARNUMVAL cannot be set for group-valued methods");
 530             bOk = FALSE;
 531         }
 532     }
 533     else
 534     {
 535         if ((method->flags & SMETH_SINGLEVAL)
 536             && (method->flags & SMETH_VARNUMVAL))
 537         {
 538             report_error(fp, method->name, "error: SMETH_SINGLEVAL and SMETH_VARNUMVAL both set");
 539             bOk = FALSE;
 540         }
 541     }
 542     if ((method->flags & SMETH_CHARVAL) && method->type != STR_VALUE)
 543     {
 544         report_error(fp, method->name, "error: SMETH_CHARVAL can only be specified for STR_VALUE methods");
 545         bOk = FALSE;
 546     }
 547     /* Check the parameters */
 548     if (!check_params(fp, method->name, method->nparams, method->param, symtab))
 549     {
 550         bOk = FALSE;
 551     }
 552     /* Check the callback pointers */
 553     if (!check_callbacks(fp, method))
 554     {
 555         bOk = FALSE;
 556     }
 557
 558     return bOk;
 559 }
 560
 561 /*!
 562  * Checks the validity of a selection modifier method.
 563  *
 564  * \param[in]     fp     File handle to use for diagnostic messages
 565  *   (can be NULL).
 566  * \param[in,out] method Method to check.
 567  * \param[in]     symtab Symbol table (used for checking overlaps).
 568  *
 569  * Checks the validity of the given selection method data structure
 570  * that has \ref SMETH_MODIFIER set.
 571  * If you remove a check, please make sure that the selection parser,
 572  * compiler, and evaluation functions can deal with the method.
 573  */
 574 static gmx_bool
 575 check_modifier(FILE *fp, gmx_ana_selmethod_t *method, gmx_sel_symtab_t *symtab)
 576 {
 577     gmx_bool         bOk = TRUE;
 578
 579     /* Check the type */
 580     if (method->type != NO_VALUE && method->type != POS_VALUE)
 581     {
 582         report_error(fp, method->name, "error: modifier should have type POS_VALUE or NO_VALUE");
 583         bOk = FALSE;
 584     }
 585     /* Check flags */
 586     if (method->flags & (SMETH_SINGLEVAL | SMETH_VARNUMVAL))
 587     {
 588         report_error(fp, method->name, "error: modifier should not have SMETH_SINGLEVAL or SMETH_VARNUMVAL set");
 589         bOk = FALSE;
 590     }
 591     /* Check the parameters */
 592     /* The first parameter is skipped */
 593     if (!check_params(fp, method->name, method->nparams-1, method->param+1, symtab))
 594     {
 595         bOk = FALSE;
 596     }
 597     /* Check the callback pointers */
 598     if (!check_callbacks(fp, method))
 599     {
 600         bOk = FALSE;
 601     }
 602     if (method->update)
 603     {
 604         report_error(fp, method->name, "error: modifier should not have update");
 605         bOk = FALSE;
 606     }
 607     if (method->type == POS_VALUE && !method->pupdate)
 608     {
 609         report_error(fp, method->name, "error: evaluation function missing");
 610         bOk = FALSE;
 611     }
 612
 613     return bOk;
 614 }
 615
 616 /*!
 617  * \param[in,out] sc     Selection collection to registered the method to.
 618  * \param[in]     name   Name under which the method should be registered.
 619  * \param[in]     method Method to register.
 620  * \returns       0 on success, EINVAL if there was something wrong with the
 621  *   method.
 622  *
 623  * \p name does not need to match the name of the method, and the same
 624  * method can be registered multiple times under different names.
 625  * If \p name equals some previously registered name,
 626  * an error message is printed and the method is not registered.
 627  *
 628  * The function also performs some sanity checking on the input method,
 629  * and refuses to register it if there are problems.
 630  * Some problems only generate warnings.
 631  * All problems are described to \p stderr.
 632  */
 633 int
 634 gmx_ana_selmethod_register(struct gmx_ana_selcollection_t *sc,
 635                            const char *name, gmx_ana_selmethod_t *method)
 636 {
 637     gmx_bool bOk;
 638
 639     /* Check the method */
 640     if (method->flags & SMETH_MODIFIER)
 641     {
 642         bOk = check_modifier(stderr, method, sc->symtab);
 643     }
 644     else
 645     {
 646         bOk = check_method(stderr, method, sc->symtab);
 647     }
 648     /* Try to register the method if everything is ok */
 649     if (bOk)
 650     {
 651         if (!_gmx_sel_add_method_symbol(sc->symtab, name, method))
 652         {
 653             bOk = FALSE;
 654         }
 655     }
 656     if (!bOk)
 657     {
 658         report_error(stderr, name, "warning: not registered");
 659         return EINVAL;
 660     }
 661     return 0;
 662 }
 663
 664 /*!
 665  * \param[in,out] sc     Selection collection to registered the methods to.
 666  * \returns       0 on success, -1 if any of the default methods could not be
 667  *   registered.
 668  */
 669 int
 670 gmx_ana_selmethod_register_defaults(struct gmx_ana_selcollection_t *sc)
 671 {
 672     size_t i;
 673     int  rc;
 674     gmx_bool bOk;
 675
 676     bOk = TRUE;
 677     for (i = 0; i < asize(smtable_def); ++i)
 678     {
 679         gmx_ana_selmethod_t *method = smtable_def[i].method;
 680
 681         if (smtable_def[i].name == NULL)
 682         {
 683             rc = gmx_ana_selmethod_register(sc, method->name, method);
 684         }
 685         else
 686         {
 687             rc = gmx_ana_selmethod_register(sc, smtable_def[i].name, method);
 688         }
 689         if (rc != 0)
 690         {
 691             bOk = FALSE;
 692         }
 693     }
 694     return bOk ? 0 : -1;
 695 }
 696
 697 /*!
 698  * \param[in] name   Name of the parameter to search.
 699  * \param[in] method Method to search for the parameter.
 700  * \returns   Pointer to the parameter in the
 701  *   \ref gmx_ana_selmethod_t::param "method->param" array,
 702  *   or NULL if no parameter with name \p name was found.
 703  *
 704  * This is a simple wrapper for gmx_ana_selparam_find().
 705  */
 706 gmx_ana_selparam_t *
 707 gmx_ana_selmethod_find_param(const char *name, gmx_ana_selmethod_t *method)
 708 {
 709     return gmx_ana_selparam_find(name, method->nparams, method->param);
 710 }