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    * 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_SET_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_SET_BASE32_AUTO(shortName,name,argumentHelp,description,val) \
 248   GNUNET_GETOPT_OPTION_SET_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_SET_ONE (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_SET_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 `unsigned long long`.
 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_SET_ULONG (char shortName,
 295                                 const char *name,
 296                                 const char *argumentHelp,
 297                                 const char *description,
 298                                 unsigned long long *val);
 299
 300
 301 /**
 302  * Allow user to specify a `struct GNUNET_TIME_Relative`
 303  * (using human-readable "fancy" time).
 304  *
 305  * @param shortName short name of the option
 306  * @param name long name of the option
 307  * @param argumentHelp help text for the option argument
 308  * @param description long help text for the option
 309  * @param[out] val set to the time specified at the command line
 310  */
 311 struct GNUNET_GETOPT_CommandLineOption
 312 GNUNET_GETOPT_OPTION_SET_RELATIVE_TIME (char shortName,
 313                                         const char *name,
 314                                         const char *argumentHelp,
 315                                         const char *description,
 316                                         struct GNUNET_TIME_Relative *val);
 317
 318
 319 /**
 320  * Increment @a val each time the option flag is given by one.
 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 1 if the option is present
 327  */
 328 struct GNUNET_GETOPT_CommandLineOption
 329 GNUNET_GETOPT_OPTION_INCREMENT_VALUE (char shortName,
 330                                       const char *name,
 331                                       const char *description,
 332                                       unsigned int *val);
 333
 334
 335 /**
 336  * Define the '-L' log level option.  Note that we do not check
 337  * that the log level is valid here.
 338  *
 339  * @param[out] level set to the log level
 340  */
 341 struct GNUNET_GETOPT_CommandLineOption
 342 GNUNET_GETOPT_OPTION_LOGLEVEL (char **level);
 343
 344
 345 /**
 346  * Define the '-V' verbosity option.  Using the option more
 347  * than once increments @a level each time.
 348  *
 349  * @param[out] level set to the verbosity level
 350  */
 351 struct GNUNET_GETOPT_CommandLineOption
 352 GNUNET_GETOPT_OPTION_VERBOSE (unsigned int *level);
 353
 354
 355 /**
 356  * Allow user to specify log file name (-l option)
 357  *
 358  * @param[out] logfn set to the name of the logfile
 359  */
 360 struct GNUNET_GETOPT_CommandLineOption
 361 GNUNET_GETOPT_OPTION_LOGFILE (char **logfn);
 362
 363
 364 /**
 365  * Allow user to specify configuration file name (-c option)
 366  *
 367  * @param[out] fn set to the name of the configuration file
 368  */
 369 struct GNUNET_GETOPT_CommandLineOption
 370 GNUNET_GETOPT_OPTION_CFG_FILE (char **fn);
 371
 372
 373 /**
 374  * Marker for the end of the list of options.
 375  */
 376 #define GNUNET_GETOPT_OPTION_END \
 377   { '\0', NULL, NULL, NULL, 0, NULL, NULL, NULL }
 378
 379
 380 /**
 381  * Parse the command line.
 382  *
 383  * @param binaryOptions Name of application with option summary
 384  * @param allOptions defined options and handlers
 385  * @param argc number of arguments in @a argv
 386  * @param argv actual arguments
 387  * @return index into argv with first non-option
 388  *   argument, or #GNUNET_SYSERR on error
 389  */
 390 int
 391 GNUNET_GETOPT_run (const char *binaryOptions,
 392                    const struct GNUNET_GETOPT_CommandLineOption *allOptions,
 393                    unsigned int argc,
 394                    char *const *argv);
 395
 396
 397 #if 0                           /* keep Emacsens' auto-indent happy */
 398 {
 399 #endif
 400 #ifdef __cplusplus
 401 }
 402 #endif
 403
 404 /* ifndef GNUNET_GETOPT_LIB_H */
 405 #endif
 406
 407 /** @} */ /* end of group getopt */
 408
 409 /* end of gnunet_getopt_lib.h */