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