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
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  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 `unsigned long long`.
 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_ulong (char shortName,
 300                             const char *name,
 301                             const char *argumentHelp,
 302                             const char *description,
 303                             unsigned long long *val);
 304
 305
 306 /**
 307  * Allow user to specify a `struct GNUNET_TIME_Relative`
 308  * (using human-readable "fancy" time).
 309  *
 310  * @param shortName short name of the option
 311  * @param name long name of the option
 312  * @param argumentHelp help text for the option argument
 313  * @param description long help text for the option
 314  * @param[out] val set to the time specified at the command line
 315  */
 316 struct GNUNET_GETOPT_CommandLineOption
 317 GNUNET_GETOPT_option_relative_time (char shortName,
 318                                     const char *name,
 319                                     const char *argumentHelp,
 320                                     const char *description,
 321                                     struct GNUNET_TIME_Relative *val);
 322
 323
 324 /**
 325  * Allow user to specify a `struct GNUNET_TIME_Absolute`
 326  * (using human-readable "fancy" time).
 327  *
 328  * @param shortName short name of the option
 329  * @param name long name of the option
 330  * @param argumentHelp help text for the option argument
 331  * @param description long help text for the option
 332  * @param[out] val set to the time specified at the command line
 333  */
 334 struct GNUNET_GETOPT_CommandLineOption
 335 GNUNET_GETOPT_option_absolute_time (char shortName,
 336                                     const char *name,
 337                                     const char *argumentHelp,
 338                                     const char *description,
 339                                     struct GNUNET_TIME_Absolute *val);
 340
 341
 342 /**
 343  * Increment @a val each time the option flag is given by one.
 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 1 if the option is present
 350  */
 351 struct GNUNET_GETOPT_CommandLineOption
 352 GNUNET_GETOPT_option_increment_uint (char shortName,
 353                                      const char *name,
 354                                      const char *description,
 355                                      unsigned int *val);
 356
 357
 358 /**
 359  * Define the '-L' log level option.  Note that we do not check
 360  * that the log level is valid here.
 361  *
 362  * @param[out] level set to the log level
 363  */
 364 struct GNUNET_GETOPT_CommandLineOption
 365 GNUNET_GETOPT_option_loglevel (char **level);
 366
 367
 368 /**
 369  * Define the '-V' verbosity option.  Using the option more
 370  * than once increments @a level each time.
 371  *
 372  * @param[out] level set to the verbosity level
 373  */
 374 struct GNUNET_GETOPT_CommandLineOption
 375 GNUNET_GETOPT_option_verbose (unsigned int *level);
 376
 377
 378 /**
 379  * Allow user to specify log file name (-l option)
 380  *
 381  * @param[out] logfn set to the name of the logfile
 382  */
 383 struct GNUNET_GETOPT_CommandLineOption
 384 GNUNET_GETOPT_option_logfile (char **logfn);
 385
 386
 387 /**
 388  * Allow user to specify configuration file name (-c option)
 389  *
 390  * @param[out] fn set to the name of the configuration file
 391  */
 392 struct GNUNET_GETOPT_CommandLineOption
 393 GNUNET_GETOPT_option_cfgfile (char **fn);
 394
 395
 396 /**
 397  * Make the given option mandatory.
 398  *
 399  * @param opt option to modify
 400  * @return @a opt with the mandatory flag set.
 401  */
 402 struct GNUNET_GETOPT_CommandLineOption
 403 GNUNET_GETOPT_option_mandatory (struct GNUNET_GETOPT_CommandLineOption opt);
 404
 405
 406 /**
 407  * Marker for the end of the list of options.
 408  */
 409 #define GNUNET_GETOPT_OPTION_END \
 410   { '\0', NULL, NULL, NULL, 0, 0, NULL, NULL, NULL }
 411
 412
 413 /**
 414  * Parse the command line.
 415  *
 416  * @param binaryOptions Name of application with option summary
 417  * @param allOptions defined options and handlers
 418  * @param argc number of arguments in @a argv
 419  * @param argv actual arguments
 420  * @return index into argv with first non-option
 421  *   argument, or #GNUNET_SYSERR on error
 422  */
 423 int
 424 GNUNET_GETOPT_run (const char *binaryOptions,
 425                    const struct GNUNET_GETOPT_CommandLineOption *allOptions,
 426                    unsigned int argc,
 427                    char *const *argv);
 428
 429
 430 #if 0                           /* keep Emacsens' auto-indent happy */
 431 {
 432 #endif
 433 #ifdef __cplusplus
 434 }
 435 #endif
 436
 437 /* ifndef GNUNET_GETOPT_LIB_H */
 438 #endif
 439
 440 /** @} */ /* end of group getopt */
 441
 442 /* end of gnunet_getopt_lib.h */