include/selparam.h

   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,2013, 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 /*! \file
  39  * \brief API for handling parameters used in selections.
  40  *
  41  * There should be no need to use the data structures or call the
  42  * functions in this file directly unless implementing a custom selection
  43  * method.
  44  *
  45  * More details can be found on the page discussing
  46  * \ref selmethods "custom selection methods".
  47  */
  48 #ifndef SELPARAM_H
  49 #define SELPARAM_H
  50
  51 #include "typedefs.h"
  52
  53 #include "indexutil.h"
  54 #include "selvalue.h"
  55
  56 #ifdef __cplusplus
  57 extern "C"
  58 {
  59 #endif
  60
  61 /*! \name Parameter flags
  62  * \anchor selparam_flags
  63  */
  64 /*@{*/
  65 /*! \brief
  66  * This flag is set if the user has provided the parameter.
  67  *
  68  * This flag is set automatically, and should not be set by the user.
  69  */
  70 #define SPAR_SET      1
  71 /*! \brief
  72  * If not set, an error is reported if the parameter is not specified by the
  73  * user.
  74  */
  75 #define SPAR_OPTIONAL 2
  76 /*! \brief
  77  * If set, the parameter value can be dynamic, i.e., be different for
  78  * different frames.
  79  *
  80  * If set, the parameter value should only be accessed in the update function
  81  * of \c gmx_ana_selmethod_t.
  82  * The flag is cleared before sel_initfunc() if the value provided is actually
  83  * static.
  84  */
  85 #define SPAR_DYNAMIC  4
  86 /*! \brief
  87  * If set, the parameter value is parsed into sorted ranges.
  88  *
  89  * Can only be specified for integer parameters.
  90  * If specified, the value of the parameter (\c gmx_ana_selparam_t::val)
  91  * consists of sets of two integers, each specifying a range.
  92  * The values give the endpoints of the ranges (inclusive).
  93  * The ranges are sorted and overlapping/continuous ranges are merged into
  94  * a single range to minimize the number of ranges.
  95  *
  96  * If this flag is specified, \c gmx_ana_selparam_t::nval gives the number of
  97  * ranges. \p gmx_ana_selparam_t::nval should be 1 or \ref SPAR_VARNUM should be
  98  * specified; other values would lead to unpredictable behavior.
  99  */
 100 #define SPAR_RANGES   8
 101 /*! \brief
 102  * If set, the parameter can have any number of values.
 103  *
 104  * If specified, the data pointer in \c gmx_ana_selparam_t::val should be NULL;
 105  * the memory is allocated by the parameter parser.
 106  * The implementation of the method should ensure that the pointer to the
 107  * allocated memory is stored somewhere in sel_initfunc();
 108  * otherwise, the memory is lost.
 109  *
 110  * The initial value of \c gmx_ana_selparam_t::nval is not used with this flag.
 111  * Instead, it will give the number of actual values provided by the user
 112  * after the parameters have been parsed.
 113  * For consistency, it should be initialized to -1.
 114  *
 115  * Cannot be combined with \ref GROUP_VALUE parameters.
 116  */
 117 #define SPAR_VARNUM   16
 118 /*! \brief
 119  * If set, the parameter can have a separate value for each atom.
 120  *
 121  * The flag is cleared before sel_initfunc() if the value provided is actually
 122  * a single value.
 123  *
 124  * Cannot be combined with \ref POS_VALUE or \ref GROUP_VALUE parameters.
 125  */
 126 #define SPAR_ATOMVAL  32
 127 /*! \brief
 128  * If set, the parameter takes one of a set of predefined strings.
 129  *
 130  * Can only be specified for a \ref STR_VALUE parameter that takes a single
 131  * string.
 132  * The data pointer in \c gmx_ana_selparam_t::val should be initialized into an
 133  * array of strings such that the first and last elements are NULL, and the
 134  * rest give the possible values. For optional values, the second element in
 135  * the array should give the default value. The string given by the user is
 136  * matched against the beginnings of the given strings, and if a unique match
 137  * is found, the first pointer in the array will be initialized to point to
 138  * the matching string.
 139  * The data pointer can be initialized as a static array; duplication of the
 140  * array for multiple instances of the same method is automatically taken care
 141  * of.
 142  */
 143 #define SPAR_ENUMVAL  128
 144 /*@}*/
 145
 146 /*! \brief
 147  * Describes a single parameter for a selection method.
 148  */
 149 typedef struct gmx_ana_selparam_t
 150 {
 151     /** Name of the parameter. */
 152     const char         *name;
 153     /*! \brief
 154      * The parameter value.
 155      *
 156      * Type \ref NO_VALUE can be used to define a boolean parameter.
 157      * The number of values should be 0 for boolean parameters.
 158      *
 159      * The value pointer be initialized to NULL in the definition of a
 160      * \c gmx_ana_selmethod_t and initialized in the
 161      * \c gmx_ana_selmethod_t::init_data call
 162      * (see sel_datafunc()).
 163      * However, if \ref SPAR_VARNUM is provided and the parameter is not
 164      * \ref POS_VALUE, this field should not be initialized. Instead,
 165      * sufficient memory is allocated automatically and the pointer should be
 166      * stored in \c gmx_ana_selmethod_t::init
 167      * (see sel_initfunc()).
 168      *
 169      * The values cannot be accessed outside these two functions: the compiler
 170      * makes a copy of the parameter structure for each instance of the
 171      * method, and the original parameter array is not changed.
 172      */
 173     gmx_ana_selvalue_t  val;
 174     /*! \brief
 175      * Pointer to store the number of values.
 176      *
 177      * If not NULL, the number of values for the parameter is stored in the
 178      * pointed value.
 179      * Should be specified if \ref SPAR_VARNUM and \ref SPAR_DYNAMIC are both
 180      * set.
 181      *
 182      * Should be initialized to NULL in the definition a \c gmx_ana_selmethod_t
 183      * and initialized in sel_datafunc().
 184      */
 185     int                *nvalptr;
 186     /*! \brief
 187      * Flags that alter the way the parameter is parsed/handled.
 188      *
 189      * See \ref selparam_flags for allowed values.
 190      */
 191     int                 flags;
 192 } gmx_ana_selparam_t;
 193
 194 /** Finds a parameter from an array by name. */
 195 gmx_ana_selparam_t *
 196 gmx_ana_selparam_find(const char *name, int nparam, gmx_ana_selparam_t *param);
 197
 198 #ifdef __cplusplus
 199 }
 200 #endif
 201
 202 #endif