gnunet_getopt_lib.h (15111B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2001-2013 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup libgnunetutil 23 * Multi-function utilities library for GNUnet programs 24 * @{ 25 * 26 * @author Christian Grothoff 27 * 28 * @file 29 * Command line parsing and --help formatting 30 * 31 * @defgroup getopt Getopt library 32 * Command line parsing and --help formatting 33 * @{ 34 */ 35 36 #if ! defined (__GNUNET_UTIL_LIB_H_INSIDE__) 37 #error "Only <gnunet_util_lib.h> can be included directly." 38 #endif 39 40 #ifndef GNUNET_GETOPT_LIB_H 41 #define GNUNET_GETOPT_LIB_H 42 43 #ifdef __cplusplus 44 extern "C" { 45 #if 0 /* keep Emacsens' auto-indent happy */ 46 } 47 #endif 48 #endif 49 50 51 #include "gnunet_configuration_lib.h" 52 53 /** 54 * @brief General context for command line processors. 55 */ 56 struct GNUNET_GETOPT_CommandLineProcessorContext 57 { 58 /** 59 * Name of the application 60 */ 61 const char *binaryName; 62 63 /** 64 * Name of application with option summary 65 */ 66 const char *binaryOptions; 67 68 /** 69 * Array with all command line options. 70 */ 71 const struct GNUNET_GETOPT_CommandLineOption *allOptions; 72 73 /** 74 * Original command line 75 */ 76 char *const *argv; 77 78 /** 79 * Total number of argv's. 80 */ 81 unsigned int argc; 82 83 /** 84 * Current argument. 85 */ 86 unsigned int currentArgument; 87 }; 88 89 90 /** 91 * @brief Process a command line option 92 * 93 * @param ctx context for all options 94 * @param scls specific closure (for this processor) 95 * @param option long name of the option (e.g. "config" for --config) 96 * @param value argument, NULL if none was given 97 * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort 98 */ 99 typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) ( 100 struct GNUNET_GETOPT_CommandLineProcessorContext *ctx, 101 void *scls, 102 const char *option, 103 const char *value); 104 105 106 /** 107 * @brief Definition of a command line option. 108 */ 109 struct GNUNET_GETOPT_CommandLineOption 110 { 111 /** 112 * Short name of the option. 113 */ 114 const char shortName; 115 116 /** 117 * Long name of the option (may not be NULL) 118 */ 119 const char *name; 120 121 /** 122 * Name of the argument for the user in help text 123 */ 124 const char *argumentHelp; 125 126 /** 127 * Help text for the option (description) 128 */ 129 const char *description; 130 131 /** 132 * Is an argument required? #GNUNET_NO (includes optional) or 133 * #GNUNET_YES (required) 134 */ 135 int require_argument; 136 137 /** 138 * Is the presence of this option mandatory? 139 */ 140 int option_mandatory; 141 142 /** 143 * Is the option exclusive? 144 */ 145 int option_exclusive; 146 147 /** 148 * Handler for the option. 149 */ 150 GNUNET_GETOPT_CommandLineOptionProcessor processor; 151 152 /** 153 * Function to call on @e scls to clean up after processing all 154 * the arguments. Can be NULL. 155 */ 156 void (*cleaner) (void *cls); 157 158 /** 159 * Specific closure to pass to the processor. 160 */ 161 void *scls; 162 }; 163 164 165 /** 166 * Defining the option to print the command line 167 * help text (-h option). 168 * 169 * @param pd project data to determine details about the application 170 * @param about string with brief description of the application 171 */ 172 struct GNUNET_GETOPT_CommandLineOption 173 GNUNET_GETOPT_option_help (const struct GNUNET_OS_ProjectData *pd, 174 const char *about); 175 176 177 /** 178 * Allow user to specify a `long long` with an offset to add to the current 179 * system time to construct the time seen by the application. Used for 180 * debugging / testing. 181 * 182 * @param shortName short name of the option 183 * @param name long name of the option 184 * @param[out] val set to the time specified at the command line 185 */ 186 struct GNUNET_GETOPT_CommandLineOption 187 GNUNET_GETOPT_option_timetravel (char shortName, 188 const char *name); 189 190 191 /** 192 * Define the option to print the version of 193 * the application (-v option) 194 * 195 * @param version string with the version number 196 */ 197 struct GNUNET_GETOPT_CommandLineOption 198 GNUNET_GETOPT_option_version (const char *version); 199 200 201 /** 202 * Allow user to specify log file name (-l option) 203 * 204 * @param[out] logfn set to the name of the logfile 205 */ 206 struct GNUNET_GETOPT_CommandLineOption 207 GNUNET_GETOPT_option_logfile (char **logfn); 208 209 210 /** 211 * Allow user to specify a string. 212 * 213 * @param shortName short name of the option 214 * @param name long name of the option 215 * @param argumentHelp help text for the option argument 216 * @param description long help text for the option 217 * @param[out] str set to the string 218 */ 219 struct GNUNET_GETOPT_CommandLineOption 220 GNUNET_GETOPT_option_string (char shortName, 221 const char *name, 222 const char *argumentHelp, 223 const char *description, 224 char **str); 225 226 /** 227 * Allow user to specify a filename (automatically path expanded). 228 * 229 * @param shortName short name of the option 230 * @param name long name of the option 231 * @param argumentHelp help text for the option argument 232 * @param description long help text for the option 233 * @param[out] str set to the string 234 */ 235 struct GNUNET_GETOPT_CommandLineOption 236 GNUNET_GETOPT_option_filename (char shortName, 237 const char *name, 238 const char *argumentHelp, 239 const char *description, 240 char **str); 241 242 243 /** 244 * Allow user to specify a binary value using Crockford 245 * Base32 encoding. 246 * 247 * @param shortName short name of the option 248 * @param name long name of the option 249 * @param argumentHelp help text for the option argument 250 * @param description long help text for the option 251 * @param[out] val binary value decoded from Crockford Base32-encoded argument 252 * @param val_size size of @a val in bytes 253 */ 254 struct GNUNET_GETOPT_CommandLineOption 255 GNUNET_GETOPT_option_base32_fixed_size (char shortName, 256 const char *name, 257 const char *argumentHelp, 258 const char *description, 259 void *val, 260 size_t val_size); 261 262 263 /** 264 * Allow user to specify a binary value using Crockford 265 * Base32 encoding where the size of the binary value is 266 * automatically determined from its type. 267 * 268 * @param shortName short name of the option 269 * @param name long name of the option 270 * @param argumentHelp help text for the option argument 271 * @param description long help text for the option 272 * @param[out] val binary value decoded from Crockford Base32-encoded argument; 273 * size is determined by type (sizeof (*val)). 274 */ 275 #define GNUNET_GETOPT_option_base32_auto(shortName, \ 276 name, \ 277 argumentHelp, \ 278 description, \ 279 val) \ 280 GNUNET_GETOPT_option_base32_fixed_size (shortName, \ 281 name, \ 282 argumentHelp, \ 283 description, \ 284 val, \ 285 sizeof(*val)) 286 287 288 /** 289 * Allow user to specify a flag (which internally means setting 290 * an integer to 1/#GNUNET_YES/#GNUNET_OK. 291 * 292 * @param shortName short name of the option 293 * @param name long name of the option 294 * @param description long help text for the option 295 * @param[out] val set to 1 if the option is present 296 */ 297 struct GNUNET_GETOPT_CommandLineOption 298 GNUNET_GETOPT_option_flag (char shortName, 299 const char *name, 300 const char *description, 301 int *val); 302 303 304 /** 305 * Allow user to specify an `unsigned int`. 306 * 307 * @param shortName short name of the option 308 * @param name long name of the option 309 * @param argumentHelp help text for the option argument 310 * @param description long help text for the option 311 * @param[out] val set to the value specified at the command line 312 */ 313 struct GNUNET_GETOPT_CommandLineOption 314 GNUNET_GETOPT_option_uint (char shortName, 315 const char *name, 316 const char *argumentHelp, 317 const char *description, 318 unsigned int *val); 319 320 321 /** 322 * Allow user to specify an uint16_t. 323 * 324 * @param shortName short name of the option 325 * @param name long name of the option 326 * @param argumentHelp help text for the option argument 327 * @param description long help text for the option 328 * @param[out] val set to the value specified at the command line 329 */ 330 struct GNUNET_GETOPT_CommandLineOption 331 GNUNET_GETOPT_option_uint16 (char shortName, 332 const char *name, 333 const char *argumentHelp, 334 const char *description, 335 uint16_t *val); 336 337 338 /** 339 * Allow user to specify an `unsigned long long`. 340 * 341 * @param shortName short name of the option 342 * @param name long name of the option 343 * @param argumentHelp help text for the option argument 344 * @param description long help text for the option 345 * @param[out] val set to the value specified at the command line 346 */ 347 struct GNUNET_GETOPT_CommandLineOption 348 GNUNET_GETOPT_option_ulong (char shortName, 349 const char *name, 350 const char *argumentHelp, 351 const char *description, 352 unsigned long long *val); 353 354 355 /** 356 * Allow user to specify a `struct GNUNET_TIME_Relative` 357 * (using human-readable "fancy" time). 358 * 359 * @param shortName short name of the option 360 * @param name long name of the option 361 * @param argumentHelp help text for the option argument 362 * @param description long help text for the option 363 * @param[out] val set to the time specified at the command line 364 */ 365 struct GNUNET_GETOPT_CommandLineOption 366 GNUNET_GETOPT_option_relative_time (char shortName, 367 const char *name, 368 const char *argumentHelp, 369 const char *description, 370 struct GNUNET_TIME_Relative *val); 371 372 373 /** 374 * Allow user to specify a `struct GNUNET_TIME_Absolute` 375 * (using human-readable "fancy" time). 376 * 377 * @param shortName short name of the option 378 * @param name long name of the option 379 * @param argumentHelp help text for the option argument 380 * @param description long help text for the option 381 * @param[out] val set to the time specified at the command line 382 */ 383 struct GNUNET_GETOPT_CommandLineOption 384 GNUNET_GETOPT_option_absolute_time (char shortName, 385 const char *name, 386 const char *argumentHelp, 387 const char *description, 388 struct GNUNET_TIME_Absolute *val); 389 390 391 /** 392 * Allow user to specify a `struct GNUNET_TIME_Timestamp` 393 * (using human-readable "fancy" time). 394 * 395 * @param shortName short name of the option 396 * @param name long name of the option 397 * @param argumentHelp help text for the option argument 398 * @param description long help text for the option 399 * @param[out] val set to the time specified at the command line 400 */ 401 struct GNUNET_GETOPT_CommandLineOption 402 GNUNET_GETOPT_option_timestamp (char shortName, 403 const char *name, 404 const char *argumentHelp, 405 const char *description, 406 struct GNUNET_TIME_Timestamp *val); 407 408 409 /** 410 * Increment @a val each time the option flag is given by one. 411 * 412 * @param shortName short name of the option 413 * @param name long name of the option 414 * @param description long help text for the option 415 * @param[out] val set to 1 if the option is present 416 */ 417 struct GNUNET_GETOPT_CommandLineOption 418 GNUNET_GETOPT_option_increment_uint (char shortName, 419 const char *name, 420 const char *description, 421 unsigned int *val); 422 423 424 /** 425 * Define the '-L' log level option. Note that we do not check 426 * that the log level is valid here. 427 * 428 * @param[out] level set to the log level 429 */ 430 struct GNUNET_GETOPT_CommandLineOption 431 GNUNET_GETOPT_option_loglevel (char **level); 432 433 434 /** 435 * Define the '-V' verbosity option. Using the option more 436 * than once increments @a level each time. 437 * 438 * @param[out] level set to the verbosity level 439 */ 440 struct GNUNET_GETOPT_CommandLineOption 441 GNUNET_GETOPT_option_verbose (unsigned int *level); 442 443 444 /** 445 * Allow user to specify configuration file name (-c option) 446 * 447 * @param[out] fn set to the name of the configuration file 448 */ 449 struct GNUNET_GETOPT_CommandLineOption 450 GNUNET_GETOPT_option_cfgfile (char **fn); 451 452 453 /** 454 * Make the given option mandatory. 455 * 456 * @param opt option to modify 457 * @return @a opt with the mandatory flag set. 458 */ 459 struct GNUNET_GETOPT_CommandLineOption 460 GNUNET_GETOPT_option_mandatory (struct GNUNET_GETOPT_CommandLineOption opt); 461 462 463 /** 464 * Make the given option mutually exclusive with other options. 465 * 466 * @param opt option to modify 467 * @return @a opt with the exclusive flag set. 468 */ 469 struct GNUNET_GETOPT_CommandLineOption 470 GNUNET_GETOPT_option_exclusive (struct GNUNET_GETOPT_CommandLineOption opt); 471 472 473 /** 474 * Marker for the end of the list of options. 475 */ 476 #define GNUNET_GETOPT_OPTION_END \ 477 { \ 478 '\0', NULL, NULL, NULL, 0, 0, 0, NULL, NULL, NULL \ 479 } 480 481 482 /** 483 * Parse the command line. 484 * 485 * @param binaryOptions Name of application with option summary 486 * @param allOptions defined options and handlers 487 * @param argc number of arguments in @a argv 488 * @param argv actual arguments 489 * @return index into argv with first non-option 490 * argument, or #GNUNET_SYSERR on error 491 */ 492 int 493 GNUNET_GETOPT_run (const char *binaryOptions, 494 const struct GNUNET_GETOPT_CommandLineOption *allOptions, 495 unsigned int argc, 496 char *const *argv); 497 498 499 #if 0 /* keep Emacsens' auto-indent happy */ 500 { 501 #endif 502 #ifdef __cplusplus 503 } 504 #endif 505 506 /* ifndef GNUNET_GETOPT_LIB_H */ 507 #endif 508 509 /** @} */ /* end of group getopt */ 510 511 /** @} */ /* end of group addition */ 512 513 /* end of gnunet_getopt_lib.h */