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