src/include/gnunet_getopt_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001-2013 Christian Grothoff (and other contributing authors)
   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  * @brief Process a command line option
  85  *
  86  * @param ctx context for all options
  87  * @param scls specific closure (for this processor)
  88  * @param option long name of the option (i.e. "config" for --config)
  89  * @param value argument, NULL if none was given
  90  * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort
  91  */
  92 typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
  93                                                          GNUNET_GETOPT_CommandLineProcessorContext *ctx,
  94                                                          void *scls,
  95                                                          const char *option,
  96                                                          const char *value);
  97
  98 /**
  99  * @brief Definition of a command line option.
 100  */
 101 struct GNUNET_GETOPT_CommandLineOption
 102 {
 103
 104   /**
 105    * Short name of the option.
 106    */
 107   const char shortName;
 108
 109   /**
 110    * Long name of the option (may not be NULL)
 111    */
 112   const char *name;
 113
 114   /**
 115    * Name of the argument for the user in help text
 116    */
 117   const char *argumentHelp;
 118
 119   /**
 120    * Help text for the option (description)
 121    */
 122   const char *description;
 123
 124   /**
 125    * Is an argument required?  0: #GNUNET_NO (includes optional), 1: #GNUNET_YES.
 126    */
 127   int require_argument;
 128
 129   /**
 130    * Handler for the option.
 131    */
 132   GNUNET_GETOPT_CommandLineOptionProcessor processor;
 133
 134   /**
 135    * Specific closure to pass to the processor.
 136    */
 137   void *scls;
 138
 139 };
 140
 141 /**
 142  * Macro defining the option to print the command line
 143  * help text (-h option).
 144  *
 145  * @param about string with brief description of the application
 146  */
 147 #define GNUNET_GETOPT_OPTION_HELP(about) \
 148   { 'h', "help", (const char *) NULL, gettext_noop("print this help"), 0, &GNUNET_GETOPT_format_help_, (void *) about }
 149
 150
 151 /**
 152  * Macro defining the option to print the version of
 153  * the application (-v option)
 154  *
 155  * @param version string with the version number
 156  */
 157 #define GNUNET_GETOPT_OPTION_VERSION(version) \
 158   { 'v', "version", (const char *) NULL, gettext_noop("print the version number"), 0, &GNUNET_GETOPT_print_version_, (void *) version }
 159
 160
 161 /**
 162  * Allow user to specify log file name (-l option)
 163  *
 164  * @param logfn set to the name of the logfile
 165  */
 166 #define GNUNET_GETOPT_OPTION_LOGFILE(logfn)                             \
 167   { 'l', "logfile", "LOGFILE", gettext_noop("configure logging to write logs to LOGFILE"), 1, &GNUNET_GETOPT_set_string, (void *) logfn }
 168
 169
 170 /**
 171  * Allow user to specify log level (-L option)
 172  *
 173  * @param loglev set to the log level
 174  */
 175 #define GNUNET_GETOPT_OPTION_LOGLEVEL(loglev)                           \
 176   { 'L', "log", "LOGLEVEL", gettext_noop("configure logging to use LOGLEVEL"), 1, &GNUNET_GETOPT_set_string, (void *) loglev }
 177
 178
 179 /**
 180  * Get number of verbose (-V) flags
 181  *
 182  * @param level where to store the verbosity level (should be an 'int')
 183  */
 184 #define GNUNET_GETOPT_OPTION_VERBOSE(level)                             \
 185   { 'V', "verbose", (const char *) NULL, gettext_noop("be verbose"), 0, &GNUNET_GETOPT_increment_value, (void *) level }
 186
 187
 188 /**
 189  * Get configuration file name (-c option)
 190  *
 191  * @param fn set to the configuration file name
 192  */
 193 #define GNUNET_GETOPT_OPTION_CFG_FILE(fn)                               \
 194   { 'c', "config", "FILENAME", gettext_noop("use configuration file FILENAME"), 1, &GNUNET_GETOPT_set_string, (void *) fn }
 195
 196
 197 /**
 198  * Marker for the end of the list of options.
 199  */
 200 #define GNUNET_GETOPT_OPTION_END \
 201   { '\0', NULL, NULL, NULL, 0, NULL, NULL }
 202
 203
 204 /**
 205  * Parse the command line.
 206  *
 207  * @param binaryOptions Name of application with option summary
 208  * @param allOptions defined options and handlers
 209  * @param argc number of arguments in @a argv
 210  * @param argv actual arguments
 211  * @return index into argv with first non-option
 212  *   argument, or #GNUNET_SYSERR on error
 213  */
 214 int
 215 GNUNET_GETOPT_run (const char *binaryOptions,
 216                    const struct GNUNET_GETOPT_CommandLineOption *allOptions,
 217                    unsigned int argc, char *const *argv);
 218
 219
 220 /**
 221  * Set an option of type 'unsigned long long' from the command line.
 222  * A pointer to this function should be passed as part of the
 223  * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
 224  * of this type.  It should be followed by a pointer to a value of
 225  * type `unsigned long long`.
 226  *
 227  * @param ctx command line processing context
 228  * @param scls additional closure (will point to the 'unsigned long long')
 229  * @param option name of the option
 230  * @param value actual value of the option as a string.
 231  * @return #GNUNET_OK if parsing the value worked
 232  */
 233 int
 234 GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
 235                          void *scls, const char *option, const char *value);
 236
 237
 238 /**
 239  * Set an option of type 'struct GNUNET_TIME_Relative' from the command line.
 240  * A pointer to this function should be passed as part of the
 241  * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
 242  * of this type.  It should be followed by a pointer to a value of
 243  * type `struct GNUNET_TIME_Relative`.
 244  *
 245  * @param ctx command line processing context
 246  * @param scls additional closure (will point to the 'struct GNUNET_TIME_Relative')
 247  * @param option name of the option
 248  * @param value actual value of the option as a string.
 249  * @return #GNUNET_OK if parsing the value worked
 250  */
 251 int
 252 GNUNET_GETOPT_set_relative_time (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
 253                                  void *scls, const char *option, const char *value);
 254
 255
 256 /**
 257  * Set an option of type 'unsigned int' from the command line.
 258  * A pointer to this function should be passed as part of the
 259  * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
 260  * of this type.  It should be followed by a pointer to a value of
 261  * type `unsigned int`.
 262  *
 263  * @param ctx command line processing context
 264  * @param scls additional closure (will point to the 'unsigned int')
 265  * @param option name of the option
 266  * @param value actual value of the option as a string.
 267  * @return #GNUNET_OK if parsing the value worked
 268  */
 269 int
 270 GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
 271                         void *scls, const char *option, const char *value);
 272
 273
 274 /**
 275  * Set an option of type 'int' from the command line to 1 if the
 276  * given option is present.
 277  * A pointer to this function should be passed as part of the
 278  * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
 279  * of this type.  It should be followed by a pointer to a value of
 280  * type `int`.
 281  *
 282  * @param ctx command line processing context
 283  * @param scls additional closure (will point to the `int`)
 284  * @param option name of the option
 285  * @param value not used (NULL)
 286  * @return #GNUNET_OK (always)
 287  */
 288 int
 289 GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
 290                        void *scls, const char *option, const char *value);
 291
 292
 293 /**
 294  * Set an option of type 'char *' from the command line.
 295  * A pointer to this function should be passed as part of the
 296  * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
 297  * of this type.  It should be followed by a pointer to a value of
 298  * type `char *`, which will be allocated with the requested string.
 299  *
 300  * @param ctx command line processing context
 301  * @param scls additional closure (will point to the `char *`,
 302  *             which will be allocated)
 303  * @param option name of the option
 304  * @param value actual value of the option (a string)
 305  * @return #GNUNET_OK (always)
 306  */
 307 int
 308 GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
 309                           void *scls, const char *option, const char *value);
 310
 311
 312 /**
 313  * Set an option of type 'char *' from the command line doing fs expansion.
 314  * A pointer to this function should be passed as part of the
 315  * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
 316  * of this type.  It should be followed by a pointer to a value of
 317  * type 'char *', which will be allocated with the requested string.
 318  *
 319  * @param ctx command line processing context
 320  * @param scls additional closure (will point to the 'char *',
 321  *             which will be allocated)
 322  * @param option name of the option
 323  * @param value actual value of the option (a string)
 324  * @return #GNUNET_OK (always)
 325  */
 326 int
 327 GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
 328                             void *scls, const char *option, const char *value);
 329
 330 /**
 331  * Set an option of type 'unsigned int' from the command line. Each
 332  * time the option flag is given, the value is incremented by one.
 333  * A pointer to this function should be passed as part of the
 334  * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
 335  * of this type.  It should be followed by a pointer to a value of
 336  * type 'int'.
 337  *
 338  * @param ctx command line processing context
 339  * @param scls additional closure (will point to the 'int')
 340  * @param option name of the option
 341  * @param value not used (NULL)
 342  * @return #GNUNET_OK (always)
 343  */
 344 int
 345 GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext
 346                                *ctx, void *scls, const char *option,
 347                                const char *value);
 348
 349
 350 /* *************** internal prototypes - use macros above! ************* */
 351
 352 /**
 353  * Print out details on command line options (implements --help).
 354  *
 355  * @param ctx command line processing context
 356  * @param scls additional closure (points to about text)
 357  * @param option name of the option
 358  * @param value not used (NULL)
 359  * @return #GNUNET_NO (do not continue, not an error)
 360  */
 361 int
 362 GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext
 363                             *ctx, void *scls, const char *option,
 364                             const char *value);
 365
 366 /**
 367  * Print out program version (implements --version).
 368  *
 369  * @param ctx command line processing context
 370  * @param scls additional closure (points to version string)
 371  * @param option name of the option
 372  * @param value not used (NULL)
 373  * @return #GNUNET_NO (do not continue, not an error)
 374  */
 375 int
 376 GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext
 377                               *ctx, void *scls, const char *option,
 378                               const char *value);
 379
 380 #if 0                           /* keep Emacsens' auto-indent happy */
 381 {
 382 #endif
 383 #ifdef __cplusplus
 384 }
 385 #endif
 386
 387 /* ifndef GNUNET_GETOPT_LIB_H */
 388 #endif
 389
 390 /** @} */ /* end of group getopt */
 391
 392 /* end of gnunet_getopt_lib.h */