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