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