src/include/gnunet_getopt_lib.h

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