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