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.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @author Christian Grothoff
23 * Command line parsing and --help formatting
25 * @defgroup getopt Getopt library
26 * Command line parsing and --help formatting
30 #ifndef GNUNET_GETOPT_LIB_H
31 #define GNUNET_GETOPT_LIB_H
36 #if 0 /* keep Emacsens' auto-indent happy */
41 #include "gnunet_configuration_lib.h"
44 * @brief General context for command line processors.
46 struct GNUNET_GETOPT_CommandLineProcessorContext
50 * Name of the application
52 const char *binaryName;
55 * Name of application with option summary
57 const char *binaryOptions;
60 * Array with all command line options.
62 const struct GNUNET_GETOPT_CommandLineOption *allOptions;
65 * Original command line
70 * Total number of argv's.
77 unsigned int currentArgument;
83 * @brief Process a command line option
85 * @param ctx context for all options
86 * @param scls specific closure (for this processor)
87 * @param option long name of the option (i.e. "config" for --config)
88 * @param value argument, NULL if none was given
89 * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort
92 (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
93 GNUNET_GETOPT_CommandLineProcessorContext *ctx,
100 * @brief Definition of a command line option.
102 struct GNUNET_GETOPT_CommandLineOption
106 * Short name of the option.
108 const char shortName;
111 * Long name of the option (may not be NULL)
116 * Name of the argument for the user in help text
118 const char *argumentHelp;
121 * Help text for the option (description)
123 const char *description;
126 * Is an argument required? #GNUNET_NO (includes optional) or
127 * #GNUNET_YES (required)
129 int require_argument;
132 * Is the presence of this option mandatory?
134 int option_mandatory;
137 * Handler for the option.
139 GNUNET_GETOPT_CommandLineOptionProcessor processor;
142 * Function to call on @e scls to clean up after processing all
143 * the arguments. Can be NULL.
145 void (*cleaner)(void *cls);
148 * Specific closure to pass to the processor.
156 * Defining the option to print the command line
157 * help text (-h option).
159 * @param about string with brief description of the application
161 struct GNUNET_GETOPT_CommandLineOption
162 GNUNET_GETOPT_option_help (const char *about);
166 * Define the option to print the version of
167 * the application (-v option)
169 * @param version string with the version number
171 struct GNUNET_GETOPT_CommandLineOption
172 GNUNET_GETOPT_option_version (const char *version);
177 * Allow user to specify log file name (-l option)
179 * @param[out] logfn set to the name of the logfile
181 struct GNUNET_GETOPT_CommandLineOption
182 GNUNET_GETOPT_option_logfile (char **logfn);
186 * Allow user to specify a string.
188 * @param shortName short name of the option
189 * @param name long name of the option
190 * @param argumentHelp help text for the option argument
191 * @param description long help text for the option
192 * @param[out] str set to the string
194 struct GNUNET_GETOPT_CommandLineOption
195 GNUNET_GETOPT_option_string (char shortName,
197 const char *argumentHelp,
198 const char *description,
202 * Allow user to specify a filename (automatically path expanded).
204 * @param shortName short name of the option
205 * @param name long name of the option
206 * @param argumentHelp help text for the option argument
207 * @param description long help text for the option
208 * @param[out] str set to the string
210 struct GNUNET_GETOPT_CommandLineOption
211 GNUNET_GETOPT_option_filename (char shortName,
213 const char *argumentHelp,
214 const char *description,
219 * Allow user to specify a binary value using Crockford
222 * @param shortName short name of the option
223 * @param name long name of the option
224 * @param argumentHelp help text for the option argument
225 * @param description long help text for the option
226 * @param[out] val binary value decoded from Crockford Base32-encoded argument
227 * @param val_size size of @a val in bytes
229 struct GNUNET_GETOPT_CommandLineOption
230 GNUNET_GETOPT_option_base32_fixed_size (char shortName,
232 const char *argumentHelp,
233 const char *description,
239 * Allow user to specify a binary value using Crockford
240 * Base32 encoding where the size of the binary value is
241 * automatically determined from its type.
243 * @param shortName short name of the option
244 * @param name long name of the option
245 * @param argumentHelp help text for the option argument
246 * @param description long help text for the option
247 * @param[out] val binary value decoded from Crockford Base32-encoded argument;
248 * size is determined by type (sizeof (*val)).
250 #define GNUNET_GETOPT_option_base32_auto(shortName,name,argumentHelp,description,val) \
251 GNUNET_GETOPT_option_base32_fixed_size(shortName,name,argumentHelp,description,val,sizeof(*val))
255 * Allow user to specify a flag (which internally means setting
256 * an integer to 1/#GNUNET_YES/#GNUNET_OK.
258 * @param shortName short name of the option
259 * @param name long name of the option
260 * @param description long help text for the option
261 * @param[out] val set to 1 if the option is present
263 struct GNUNET_GETOPT_CommandLineOption
264 GNUNET_GETOPT_option_flag (char shortName,
266 const char *description,
271 * Allow user to specify an `unsigned int`.
273 * @param shortName short name of the option
274 * @param name long name of the option
275 * @param argumentHelp help text for the option argument
276 * @param description long help text for the option
277 * @param[out] val set to the value specified at the command line
279 struct GNUNET_GETOPT_CommandLineOption
280 GNUNET_GETOPT_option_uint (char shortName,
282 const char *argumentHelp,
283 const char *description,
288 * Allow user to specify an uint16_t.
290 * @param shortName short name of the option
291 * @param name long name of the option
292 * @param argumentHelp help text for the option argument
293 * @param description long help text for the option
294 * @param[out] val set to the value specified at the command line
296 struct GNUNET_GETOPT_CommandLineOption
297 GNUNET_GETOPT_option_uint16 (char shortName,
299 const char *argumentHelp,
300 const char *description,
305 * Allow user to specify an `unsigned long long`.
307 * @param shortName short name of the option
308 * @param name long name of the option
309 * @param argumentHelp help text for the option argument
310 * @param description long help text for the option
311 * @param[out] val set to the value specified at the command line
313 struct GNUNET_GETOPT_CommandLineOption
314 GNUNET_GETOPT_option_ulong (char shortName,
316 const char *argumentHelp,
317 const char *description,
318 unsigned long long *val);
322 * Allow user to specify a `struct GNUNET_TIME_Relative`
323 * (using human-readable "fancy" time).
325 * @param shortName short name of the option
326 * @param name long name of the option
327 * @param argumentHelp help text for the option argument
328 * @param description long help text for the option
329 * @param[out] val set to the time specified at the command line
331 struct GNUNET_GETOPT_CommandLineOption
332 GNUNET_GETOPT_option_relative_time (char shortName,
334 const char *argumentHelp,
335 const char *description,
336 struct GNUNET_TIME_Relative *val);
340 * Allow user to specify a `struct GNUNET_TIME_Absolute`
341 * (using human-readable "fancy" time).
343 * @param shortName short name of the option
344 * @param name long name of the option
345 * @param argumentHelp help text for the option argument
346 * @param description long help text for the option
347 * @param[out] val set to the time specified at the command line
349 struct GNUNET_GETOPT_CommandLineOption
350 GNUNET_GETOPT_option_absolute_time (char shortName,
352 const char *argumentHelp,
353 const char *description,
354 struct GNUNET_TIME_Absolute *val);
358 * Increment @a val each time the option flag is given by one.
360 * @param shortName short name of the option
361 * @param name long name of the option
362 * @param argumentHelp help text for the option argument
363 * @param description long help text for the option
364 * @param[out] val set to 1 if the option is present
366 struct GNUNET_GETOPT_CommandLineOption
367 GNUNET_GETOPT_option_increment_uint (char shortName,
369 const char *description,
374 * Define the '-L' log level option. Note that we do not check
375 * that the log level is valid here.
377 * @param[out] level set to the log level
379 struct GNUNET_GETOPT_CommandLineOption
380 GNUNET_GETOPT_option_loglevel (char **level);
384 * Define the '-V' verbosity option. Using the option more
385 * than once increments @a level each time.
387 * @param[out] level set to the verbosity level
389 struct GNUNET_GETOPT_CommandLineOption
390 GNUNET_GETOPT_option_verbose (unsigned int *level);
394 * Allow user to specify log file name (-l option)
396 * @param[out] logfn set to the name of the logfile
398 struct GNUNET_GETOPT_CommandLineOption
399 GNUNET_GETOPT_option_logfile (char **logfn);
403 * Allow user to specify configuration file name (-c option)
405 * @param[out] fn set to the name of the configuration file
407 struct GNUNET_GETOPT_CommandLineOption
408 GNUNET_GETOPT_option_cfgfile (char **fn);
412 * Make the given option mandatory.
414 * @param opt option to modify
415 * @return @a opt with the mandatory flag set.
417 struct GNUNET_GETOPT_CommandLineOption
418 GNUNET_GETOPT_option_mandatory (struct GNUNET_GETOPT_CommandLineOption opt);
422 * Marker for the end of the list of options.
424 #define GNUNET_GETOPT_OPTION_END \
425 { '\0', NULL, NULL, NULL, 0, 0, NULL, NULL, NULL }
429 * Parse the command line.
431 * @param binaryOptions Name of application with option summary
432 * @param allOptions defined options and handlers
433 * @param argc number of arguments in @a argv
434 * @param argv actual arguments
435 * @return index into argv with first non-option
436 * argument, or #GNUNET_SYSERR on error
439 GNUNET_GETOPT_run (const char *binaryOptions,
440 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
445 #if 0 /* keep Emacsens' auto-indent happy */
452 /* ifndef GNUNET_GETOPT_LIB_H */
455 /** @} */ /* end of group getopt */
457 /* end of gnunet_getopt_lib.h */