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