src/include/gnunet_getopt_lib.h

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