2 This file is part of GNUnet.
3 Copyright (C) 2001-2013 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
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 Affero General Public License for more details.
17 * @author Christian Grothoff
20 * Command line parsing and --help formatting
22 * @defgroup getopt Getopt library
23 * Command line parsing and --help formatting
27 #ifndef GNUNET_GETOPT_LIB_H
28 #define GNUNET_GETOPT_LIB_H
33 #if 0 /* keep Emacsens' auto-indent happy */
38 #include "gnunet_configuration_lib.h"
41 * @brief General context for command line processors.
43 struct GNUNET_GETOPT_CommandLineProcessorContext
47 * Name of the application
49 const char *binaryName;
52 * Name of application with option summary
54 const char *binaryOptions;
57 * Array with all command line options.
59 const struct GNUNET_GETOPT_CommandLineOption *allOptions;
62 * Original command line
67 * Total number of argv's.
74 unsigned int currentArgument;
80 * @brief Process a command line option
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
89 (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
90 GNUNET_GETOPT_CommandLineProcessorContext *ctx,
97 * @brief Definition of a command line option.
99 struct GNUNET_GETOPT_CommandLineOption
103 * Short name of the option.
105 const char shortName;
108 * Long name of the option (may not be NULL)
113 * Name of the argument for the user in help text
115 const char *argumentHelp;
118 * Help text for the option (description)
120 const char *description;
123 * Is an argument required? #GNUNET_NO (includes optional) or
124 * #GNUNET_YES (required)
126 int require_argument;
129 * Is the presence of this option mandatory?
131 int option_mandatory;
134 * Handler for the option.
136 GNUNET_GETOPT_CommandLineOptionProcessor processor;
139 * Function to call on @e scls to clean up after processing all
140 * the arguments. Can be NULL.
142 void (*cleaner)(void *cls);
145 * Specific closure to pass to the processor.
153 * Defining the option to print the command line
154 * help text (-h option).
156 * @param about string with brief description of the application
158 struct GNUNET_GETOPT_CommandLineOption
159 GNUNET_GETOPT_option_help (const char *about);
163 * Define the option to print the version of
164 * the application (-v option)
166 * @param version string with the version number
168 struct GNUNET_GETOPT_CommandLineOption
169 GNUNET_GETOPT_option_version (const char *version);
174 * Allow user to specify log file name (-l option)
176 * @param[out] logfn set to the name of the logfile
178 struct GNUNET_GETOPT_CommandLineOption
179 GNUNET_GETOPT_option_logfile (char **logfn);
183 * Allow user to specify a string.
185 * @param shortName short name of the option
186 * @param name long name of the option
187 * @param argumentHelp help text for the option argument
188 * @param description long help text for the option
189 * @param[out] str set to the string
191 struct GNUNET_GETOPT_CommandLineOption
192 GNUNET_GETOPT_option_string (char shortName,
194 const char *argumentHelp,
195 const char *description,
199 * Allow user to specify a filename (automatically path expanded).
201 * @param shortName short name of the option
202 * @param name long name of the option
203 * @param argumentHelp help text for the option argument
204 * @param description long help text for the option
205 * @param[out] str set to the string
207 struct GNUNET_GETOPT_CommandLineOption
208 GNUNET_GETOPT_option_filename (char shortName,
210 const char *argumentHelp,
211 const char *description,
216 * Allow user to specify a binary value using Crockford
219 * @param shortName short name of the option
220 * @param name long name of the option
221 * @param argumentHelp help text for the option argument
222 * @param description long help text for the option
223 * @param[out] val binary value decoded from Crockford Base32-encoded argument
224 * @param val_size size of @a val in bytes
226 struct GNUNET_GETOPT_CommandLineOption
227 GNUNET_GETOPT_option_base32_fixed_size (char shortName,
229 const char *argumentHelp,
230 const char *description,
236 * Allow user to specify a binary value using Crockford
237 * Base32 encoding where the size of the binary value is
238 * automatically determined from its type.
240 * @param shortName short name of the option
241 * @param name long name of the option
242 * @param argumentHelp help text for the option argument
243 * @param description long help text for the option
244 * @param[out] val binary value decoded from Crockford Base32-encoded argument;
245 * size is determined by type (sizeof (*val)).
247 #define GNUNET_GETOPT_option_base32_auto(shortName,name,argumentHelp,description,val) \
248 GNUNET_GETOPT_option_base32_fixed_size(shortName,name,argumentHelp,description,val,sizeof(*val))
252 * Allow user to specify a flag (which internally means setting
253 * an integer to 1/#GNUNET_YES/#GNUNET_OK.
255 * @param shortName short name of the option
256 * @param name long name of the option
257 * @param description long help text for the option
258 * @param[out] val set to 1 if the option is present
260 struct GNUNET_GETOPT_CommandLineOption
261 GNUNET_GETOPT_option_flag (char shortName,
263 const char *description,
268 * Allow user to specify an `unsigned int`.
270 * @param shortName short name of the option
271 * @param name long name of the option
272 * @param argumentHelp help text for the option argument
273 * @param description long help text for the option
274 * @param[out] val set to the value specified at the command line
276 struct GNUNET_GETOPT_CommandLineOption
277 GNUNET_GETOPT_option_uint (char shortName,
279 const char *argumentHelp,
280 const char *description,
285 * Allow user to specify an uint16_t.
287 * @param shortName short name of the option
288 * @param name long name of the option
289 * @param argumentHelp help text for the option argument
290 * @param description long help text for the option
291 * @param[out] val set to the value specified at the command line
293 struct GNUNET_GETOPT_CommandLineOption
294 GNUNET_GETOPT_option_uint16 (char shortName,
296 const char *argumentHelp,
297 const char *description,
302 * Allow user to specify an `unsigned long long`.
304 * @param shortName short name of the option
305 * @param name long name of the option
306 * @param argumentHelp help text for the option argument
307 * @param description long help text for the option
308 * @param[out] val set to the value specified at the command line
310 struct GNUNET_GETOPT_CommandLineOption
311 GNUNET_GETOPT_option_ulong (char shortName,
313 const char *argumentHelp,
314 const char *description,
315 unsigned long long *val);
319 * Allow user to specify a `struct GNUNET_TIME_Relative`
320 * (using human-readable "fancy" time).
322 * @param shortName short name of the option
323 * @param name long name of the option
324 * @param argumentHelp help text for the option argument
325 * @param description long help text for the option
326 * @param[out] val set to the time specified at the command line
328 struct GNUNET_GETOPT_CommandLineOption
329 GNUNET_GETOPT_option_relative_time (char shortName,
331 const char *argumentHelp,
332 const char *description,
333 struct GNUNET_TIME_Relative *val);
337 * Allow user to specify a `struct GNUNET_TIME_Absolute`
338 * (using human-readable "fancy" time).
340 * @param shortName short name of the option
341 * @param name long name of the option
342 * @param argumentHelp help text for the option argument
343 * @param description long help text for the option
344 * @param[out] val set to the time specified at the command line
346 struct GNUNET_GETOPT_CommandLineOption
347 GNUNET_GETOPT_option_absolute_time (char shortName,
349 const char *argumentHelp,
350 const char *description,
351 struct GNUNET_TIME_Absolute *val);
355 * Increment @a val each time the option flag is given by one.
357 * @param shortName short name of the option
358 * @param name long name of the option
359 * @param argumentHelp help text for the option argument
360 * @param description long help text for the option
361 * @param[out] val set to 1 if the option is present
363 struct GNUNET_GETOPT_CommandLineOption
364 GNUNET_GETOPT_option_increment_uint (char shortName,
366 const char *description,
371 * Define the '-L' log level option. Note that we do not check
372 * that the log level is valid here.
374 * @param[out] level set to the log level
376 struct GNUNET_GETOPT_CommandLineOption
377 GNUNET_GETOPT_option_loglevel (char **level);
381 * Define the '-V' verbosity option. Using the option more
382 * than once increments @a level each time.
384 * @param[out] level set to the verbosity level
386 struct GNUNET_GETOPT_CommandLineOption
387 GNUNET_GETOPT_option_verbose (unsigned int *level);
391 * Allow user to specify log file name (-l option)
393 * @param[out] logfn set to the name of the logfile
395 struct GNUNET_GETOPT_CommandLineOption
396 GNUNET_GETOPT_option_logfile (char **logfn);
400 * Allow user to specify configuration file name (-c option)
402 * @param[out] fn set to the name of the configuration file
404 struct GNUNET_GETOPT_CommandLineOption
405 GNUNET_GETOPT_option_cfgfile (char **fn);
409 * Make the given option mandatory.
411 * @param opt option to modify
412 * @return @a opt with the mandatory flag set.
414 struct GNUNET_GETOPT_CommandLineOption
415 GNUNET_GETOPT_option_mandatory (struct GNUNET_GETOPT_CommandLineOption opt);
419 * Marker for the end of the list of options.
421 #define GNUNET_GETOPT_OPTION_END \
422 { '\0', NULL, NULL, NULL, 0, 0, NULL, NULL, NULL }
426 * Parse the command line.
428 * @param binaryOptions Name of application with option summary
429 * @param allOptions defined options and handlers
430 * @param argc number of arguments in @a argv
431 * @param argv actual arguments
432 * @return index into argv with first non-option
433 * argument, or #GNUNET_SYSERR on error
436 GNUNET_GETOPT_run (const char *binaryOptions,
437 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
442 #if 0 /* keep Emacsens' auto-indent happy */
449 /* ifndef GNUNET_GETOPT_LIB_H */
452 /** @} */ /* end of group getopt */
454 /* end of gnunet_getopt_lib.h */