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    * Specific closure to pass to the processor.
 140    */
 141   void *scls;
 142
 143 };
 144
 145
 146 /**
 147  * Defining the option to print the command line
 148  * help text (-h option).
 149  *
 150  * @param about string with brief description of the application
 151  */
 152 struct GNUNET_GETOPT_CommandLineOption
 153 GNUNET_GETOPT_OPTION_HELP (const char *about);
 154
 155
 156 /**
 157  * Define the option to print the version of
 158  * the application (-v option)
 159  *
 160  * @param version string with the version number
 161  */
 162 struct GNUNET_GETOPT_CommandLineOption
 163 GNUNET_GETOPT_OPTION_VERSION (const char *version);
 164
 165
 166
 167 /**
 168  * Allow user to specify log file name (-l option)
 169  *
 170  * @param[out] logfn set to the name of the logfile
 171  */
 172 struct GNUNET_GETOPT_CommandLineOption
 173 GNUNET_GETOPT_OPTION_LOGFILE (char **logfn);
 174
 175
 176 /**
 177  * Allow user to specify a string.
 178  *
 179  * @param shortName short name of the option
 180  * @param name long name of the option
 181  * @param argumentHelp help text for the option argument
 182  * @param description long help text for the option
 183  * @param[out] str set to the string
 184  */
 185 struct GNUNET_GETOPT_CommandLineOption
 186 GNUNET_GETOPT_OPTION_STRING (char shortName,
 187                              const char *name,
 188                              const char *argumentHelp,
 189                              const char *description,
 190                              char **str);
 191
 192 /**
 193  * Allow user to specify a filename (automatically path expanded).
 194  *
 195  * @param shortName short name of the option
 196  * @param name long name of the option
 197  * @param argumentHelp help text for the option argument
 198  * @param description long help text for the option
 199  * @param[out] str set to the string
 200  */
 201 struct GNUNET_GETOPT_CommandLineOption
 202 GNUNET_GETOPT_OPTION_FILENAME (char shortName,
 203                                const char *name,
 204                                const char *argumentHelp,
 205                                const char *description,
 206                                char **str);
 207
 208
 209 /**
 210  * Allow user to specify a flag (which internally means setting
 211  * an integer to 1/#GNUNET_YES/#GNUNET_OK.
 212  *
 213  * @param shortName short name of the option
 214  * @param name long name of the option
 215  * @param description long help text for the option
 216  * @param[out] val set to 1 if the option is present
 217  */
 218 struct GNUNET_GETOPT_CommandLineOption
 219 GNUNET_GETOPT_OPTION_SET_ONE (char shortName,
 220                               const char *name,
 221                               const char *description,
 222                               int *val);
 223
 224
 225 /**
 226  * Allow user to specify an `unsigned int`.
 227  *
 228  * @param shortName short name of the option
 229  * @param name long name of the option
 230  * @param argumentHelp help text for the option argument
 231  * @param description long help text for the option
 232  * @param[out] val set to the value specified at the command line
 233  */
 234 struct GNUNET_GETOPT_CommandLineOption
 235 GNUNET_GETOPT_OPTION_SET_UINT (char shortName,
 236                                const char *name,
 237                                const char *argumentHelp,
 238                                const char *description,
 239                                unsigned int *val);
 240
 241
 242 /**
 243  * Allow user to specify an `unsigned long long`.
 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 set to the value specified at the command line
 250  */
 251 struct GNUNET_GETOPT_CommandLineOption
 252 GNUNET_GETOPT_OPTION_SET_ULONG (char shortName,
 253                                 const char *name,
 254                                 const char *argumentHelp,
 255                                 const char *description,
 256                                 unsigned long long *val);
 257
 258
 259 /**
 260  * Allow user to specify a `struct GNUNET_TIME_Relative`
 261  * (using human-readable "fancy" time).
 262  *
 263  * @param shortName short name of the option
 264  * @param name long name of the option
 265  * @param argumentHelp help text for the option argument
 266  * @param description long help text for the option
 267  * @param[out] val set to the time specified at the command line
 268  */
 269 struct GNUNET_GETOPT_CommandLineOption
 270 GNUNET_GETOPT_OPTION_SET_RELATIVE_TIME (char shortName,
 271                                         const char *name,
 272                                         const char *argumentHelp,
 273                                         const char *description,
 274                                         struct GNUNET_TIME_Relative *val);
 275
 276
 277 /**
 278  * Increment @a val each time the option flag is given by one.
 279  *
 280  * @param shortName short name of the option
 281  * @param name long name of the option
 282  * @param argumentHelp help text for the option argument
 283  * @param description long help text for the option
 284  * @param[out] val set to 1 if the option is present
 285  */
 286 struct GNUNET_GETOPT_CommandLineOption
 287 GNUNET_GETOPT_OPTION_INCREMENT_VALUE (char shortName,
 288                                       const char *name,
 289                                       const char *description,
 290                                       unsigned int *val);
 291
 292
 293 /**
 294  * Define the '-L' log level option.  Note that we do not check
 295  * that the log level is valid here.
 296  *
 297  * @param[out] level set to the log level
 298  */
 299 struct GNUNET_GETOPT_CommandLineOption
 300 GNUNET_GETOPT_OPTION_LOGLEVEL (char **level);
 301
 302
 303 /**
 304  * Define the '-V' verbosity option.  Using the option more
 305  * than once increments @a level each time.
 306  *
 307  * @param[out] level set to the verbosity level
 308  */
 309 struct GNUNET_GETOPT_CommandLineOption
 310 GNUNET_GETOPT_OPTION_VERBOSE (int *level);
 311
 312
 313 /**
 314  * Allow user to specify log file name (-l option)
 315  *
 316  * @param[out] logfn set to the name of the logfile
 317  */
 318 struct GNUNET_GETOPT_CommandLineOption
 319 GNUNET_GETOPT_OPTION_LOGFILE (char **logfn);
 320
 321
 322 /**
 323  * Allow user to specify configuration file name (-c option)
 324  *
 325  * @param[out] fn set to the name of the configuration file
 326  */
 327 struct GNUNET_GETOPT_CommandLineOption
 328 GNUNET_GETOPT_OPTION_CFG_FILE (char **fn);
 329
 330
 331 /**
 332  * Marker for the end of the list of options.
 333  */
 334 #define GNUNET_GETOPT_OPTION_END \
 335   { '\0', NULL, NULL, NULL, 0, NULL, NULL }
 336
 337
 338 /**
 339  * Parse the command line.
 340  *
 341  * @param binaryOptions Name of application with option summary
 342  * @param allOptions defined options and handlers
 343  * @param argc number of arguments in @a argv
 344  * @param argv actual arguments
 345  * @return index into argv with first non-option
 346  *   argument, or #GNUNET_SYSERR on error
 347  */
 348 int
 349 GNUNET_GETOPT_run (const char *binaryOptions,
 350                    const struct GNUNET_GETOPT_CommandLineOption *allOptions,
 351                    unsigned int argc,
 352                    char *const *argv);
 353
 354
 355 #if 0                           /* keep Emacsens' auto-indent happy */
 356 {
 357 #endif
 358 #ifdef __cplusplus
 359 }
 360 #endif
 361
 362 /* ifndef GNUNET_GETOPT_LIB_H */
 363 #endif
 364
 365 /** @} */ /* end of group getopt */
 366
 367 /* end of gnunet_getopt_lib.h */