src/gromacs/commandline/pargs.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-2004, The GROMACS development team.
   6  * Copyright (c) 2013,2014,2015,2017,2018, by the GROMACS development team, led by
   7  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   8  * and including many others, as listed in the AUTHORS file in the
   9  * top-level source directory and at http://www.gromacs.org.
  10  *
  11  * GROMACS is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * GROMACS is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with GROMACS; if not, see
  23  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  25  *
  26  * If you want to redistribute modifications to GROMACS, please
  27  * consider that scientific software is very special. Version
  28  * control is crucial - bugs must be traceable. We will be happy to
  29  * consider code for inclusion in the official distribution, but
  30  * derived work must not be called official GROMACS. Details are found
  31  * in the README & COPYING files - if they are missing, get the
  32  * official version at http://www.gromacs.org.
  33  *
  34  * To help us fund GROMACS development, we humbly ask that you cite
  35  * the research papers on the package. Check out http://www.gromacs.org.
  36  */
  37 /*! \file
  38  * \brief
  39  * Declares \c t_pargs, parse_common_args() and related methods.
  40  *
  41  * \inpublicapi
  42  * \ingroup module_commandline
  43  */
  44 #ifndef GMX_COMMANDLINE_PARGS_H
  45 #define GMX_COMMANDLINE_PARGS_H
  46
  47 #include "gromacs/commandline/filenm.h"
  48 #include "gromacs/fileio/oenv.h"
  49 #include "gromacs/math/vectypes.h"
  50 #include "gromacs/utility/basedefinitions.h"
  51 #include "gromacs/utility/real.h"
  52
  53 struct gmx_output_env_t;
  54
  55 #ifdef __cplusplus
  56 extern "C"
  57 {
  58 #endif
  59
  60 /*! \addtogroup module_commandline
  61  * \{
  62  */
  63
  64 /** Command line argument type. */
  65 enum
  66 {
  67     etINT, etINT64, etREAL, etTIME, etSTR, etBOOL, etRVEC, etENUM, etNR
  68 };
  69
  70 /*! \brief
  71  * Command-line argument definition for C code.
  72  *
  73  * \inpublicapi
  74  */
  75 typedef struct
  76 {
  77     /** Name of the argument (with leading dash included). */
  78     const char *option;
  79     /** Whether the argument is set (should be initialized to `FALSE`). */
  80     gmx_bool    bSet;
  81     /** Type of the argument (one of the enums in pargs.h). */
  82     int         type;
  83     /*! \brief
  84      * Pointer to variable that is to receive the value.
  85      *
  86      * The expected type depends on the value of \a type.
  87      * If an argument is not set by the user, then the pointed value is not
  88      * changed.  In other words, the initial value for the variable defines the
  89      * default value.
  90      */
  91     union
  92     {
  93         /*! \brief
  94          * Generic pointer for operations that do not need type information.
  95          *
  96          * Needs to be the first member to use initialized arrays.
  97          */
  98         void            *v;
  99         /** Integer value for etINT. */
 100         int             *i;
 101         /** Integer value for etINT64. */
 102         int64_t         *is;
 103         /** Real value for etREAL and etTIME. */
 104         real            *r;
 105         /*! \brief
 106          * String value for etSTR and etENUM.
 107          *
 108          * For etSTR, this should point to a `const char *` variable, which
 109          * will receive a pointer to the string value (caller should not free
 110          * the string).
 111          *
 112          * For etENUM, this should be an array of `const char *` values, where
 113          * the first and last values are `NULL`, and the other values define
 114          * the allowed enum values.  The first non-NULL value is the default
 115          * value.  After the arguments are parsed, the first element in the array
 116          * points to the selected enum value (pointers will be equal).
 117          */
 118         const char     **c;
 119         /** Boolean value for etBOOL. */
 120         gmx_bool        *b;
 121         /** Vector value for etRVEC. */
 122         rvec            *rv;
 123     }           u;
 124     /*! \brief
 125      * Description for the argument.
 126      *
 127      * If the string starts with `HIDDEN`, then the argument is hidden from
 128      * normal help listing and shell completions.
 129      */
 130     const char *desc;
 131 } t_pargs;
 132
 133 /*! \brief
 134  * Returns ordinal number for an etENUM argument.
 135  *
 136  * \param[in] enumc  Array passed to `t_pargs` for an etENUM argument.
 137  * \returns   Index of selected enum value in the array.
 138  *
 139  * See t_pargs::u::c for the expected format of the array, including how the
 140  * first element should be initialized.
 141  * Note that the return value starts at one instead of zero: if the first enum
 142  * value is selected, this returns 1.
 143  */
 144 int nenum(const char *const enumc[]);
 145
 146 /*! \brief
 147  * Returns value of an etINT option.
 148  *
 149  * \param[in] option Name of etINT argument to query.
 150  * \param[in] nparg  Number of elements in \p pa.
 151  * \param[in] pa     Array of arguments.
 152  * \returns   Value of \p option.
 153  *
 154  * \p option must specify a valid argument in \p pa of the correct type.
 155  */
 156 int opt2parg_int(const char *option, int nparg, t_pargs pa[]);
 157
 158 /*! \brief
 159  * Returns value of an etBOOL option.
 160  *
 161  * \param[in] option Name of etBOOL argument to query.
 162  * \param[in] nparg  Number of elements in \p pa.
 163  * \param[in] pa     Array of arguments.
 164  * \returns   Value of \p option.
 165  *
 166  * \p option must specify a valid argument in \p pa of the correct type.
 167  */
 168 gmx_bool opt2parg_bool(const char *option, int nparg, t_pargs pa[]);
 169
 170 /*! \brief
 171  * Returns value of an etREAL/etTIME option.
 172  *
 173  * \param[in] option Name of etREAL/etTIME argument to query.
 174  * \param[in] nparg  Number of elements in \p pa.
 175  * \param[in] pa     Array of arguments.
 176  * \returns   Value of \p option.
 177  *
 178  * \p option must specify a valid argument in \p pa of the correct type.
 179  */
 180 real opt2parg_real(const char *option, int nparg, t_pargs pa[]);
 181
 182 /*! \brief
 183  * Returns value of an etSTR option.
 184  *
 185  * \param[in] option Name of etSTR argument to query.
 186  * \param[in] nparg  Number of elements in \p pa.
 187  * \param[in] pa     Array of arguments.
 188  * \returns   Value of \p option.
 189  *
 190  * \p option must specify a valid argument in \p pa of the correct type.
 191  */
 192 const char *opt2parg_str(const char *option, int nparg, t_pargs pa[]);
 193
 194 /*! \brief
 195  * Returns value of an etENUM option.
 196  *
 197  * \param[in] option Name of etENUM argument to query.
 198  * \param[in] nparg  Number of elements in \p pa.
 199  * \param[in] pa     Array of arguments.
 200  * \returns   Value of \p option.
 201  *
 202  * \p option must specify a valid argument in \p pa of the correct type.
 203  */
 204 const char *opt2parg_enum(const char *option, int nparg, t_pargs pa[]);
 205
 206 /*! \brief
 207  * Returns whether an argument has been set.
 208  *
 209  * \param[in] option Name of argument to check.
 210  * \param[in] nparg  Number of elements in \p pa.
 211  * \param[in] pa     Array of arguments.
 212  * \returns   `true` if \p option has been set.
 213  *
 214  * \p option must specify a valid argument in \p pa.
 215  */
 216 gmx_bool opt2parg_bSet(const char *option, int nparg, const t_pargs *pa);
 217
 218
 219 /** Add option -w to view output files (must be implemented in program). */
 220 #define PCA_CAN_VIEW       (1<<5)
 221 /** Add option to set begin time for trajectory reading. */
 222 #define PCA_CAN_BEGIN      (1<<6)
 223 /** Add option to set end time for trajectory reading. */
 224 #define PCA_CAN_END        (1<<7)
 225 /** Add option to set time step for trajectory reading. */
 226 #define PCA_CAN_DT         (1<<14)
 227 /** Add all options for trajectory time control. */
 228 #define PCA_CAN_TIME       (PCA_CAN_BEGIN | PCA_CAN_END | PCA_CAN_DT)
 229 /** Add option -tu to set time unit for output. */
 230 #define PCA_TIME_UNIT      (1<<15)
 231 /** Add option -deffnm to set default for all file options. */
 232 #define PCA_CAN_SET_DEFFNM (1<<10)
 233 /** Do not raise a fatal error when invalid options are encountered. */
 234 #define PCA_NOEXIT_ON_ARGS (1<<11)
 235 /** Don't do any special processing for ffREAD files */
 236 #define PCA_DISABLE_INPUT_FILE_CHECKING (1<<17)
 237
 238 /*! \brief
 239  * Parse command-line arguments.
 240  *
 241  * Some common default arguments are also recognized in addition to those
 242  * provided through \p pa.  The set of recognized default arguments is affected
 243  * by \p Flags.
 244  *
 245  * Recognized arguments are removed from the list.
 246  *
 247  * For full functionality, this function needs to be used within a function
 248  * that is passed to gmx_run_cmain().  It should be called as the first thing in
 249  * that function.  Initialization code can be executed before it, but you need
 250  * to be aware that if the program is executed with -h and MPI, the code before
 251  * parse_common_args() only executes on the master node.
 252  *
 253  * If the return value is `FALSE`, the program should return immediately (this
 254  * is necessary for -h and a few other cases).
 255  *
 256  * \see gmx_run_cmain().
 257  */
 258 gmx_bool parse_common_args(int *argc, char *argv[], unsigned long Flags,
 259                            int nfile, t_filenm fnm[], int npargs, t_pargs *pa,
 260                            int ndesc, const char **desc,
 261                            int nbugs, const char **bugs,
 262                            gmx_output_env_t **oenv);
 263
 264 /*! \} */
 265
 266 #ifdef __cplusplus
 267 }
 268 #endif
 269
 270 #endif