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
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.
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.
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.
22 * @author Christian Grothoff
25 * Command line parsing and --help formatting
27 * @defgroup getopt Getopt library
28 * Command line parsing and --help formatting
32 #ifndef GNUNET_GETOPT_LIB_H
33 #define GNUNET_GETOPT_LIB_H
38 #if 0 /* keep Emacsens' auto-indent happy */
43 #include "gnunet_configuration_lib.h"
46 * @brief General context for command line processors.
48 struct GNUNET_GETOPT_CommandLineProcessorContext
52 * Name of the application
54 const char *binaryName;
57 * Name of application with option summary
59 const char *binaryOptions;
62 * Array with all command line options.
64 const struct GNUNET_GETOPT_CommandLineOption *allOptions;
67 * Original command line
72 * Total number of argv's.
79 unsigned int currentArgument;
85 * @brief Process a command line option
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
94 (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
95 GNUNET_GETOPT_CommandLineProcessorContext *ctx,
102 * @brief Definition of a command line option.
104 struct GNUNET_GETOPT_CommandLineOption
108 * Short name of the option.
110 const char shortName;
113 * Long name of the option (may not be NULL)
118 * Name of the argument for the user in help text
120 const char *argumentHelp;
123 * Help text for the option (description)
125 const char *description;
128 * Is an argument required? #GNUNET_NO (includes optional) or
129 * #GNUNET_YES (required)
131 int require_argument;
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_SET_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_SET_BASE32_AUTO(shortName,name,argumentHelp,description,val) \
248 GNUNET_GETOPT_OPTION_SET_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_SET_ONE (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_SET_UINT (char shortName,
279 const char *argumentHelp,
280 const char *description,
285 * Allow user to specify an `unsigned long long`.
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_SET_ULONG (char shortName,
296 const char *argumentHelp,
297 const char *description,
298 unsigned long long *val);
302 * Allow user to specify a `struct GNUNET_TIME_Relative`
303 * (using human-readable "fancy" time).
305 * @param shortName short name of the option
306 * @param name long name of the option
307 * @param argumentHelp help text for the option argument
308 * @param description long help text for the option
309 * @param[out] val set to the time specified at the command line
311 struct GNUNET_GETOPT_CommandLineOption
312 GNUNET_GETOPT_OPTION_SET_RELATIVE_TIME (char shortName,
314 const char *argumentHelp,
315 const char *description,
316 struct GNUNET_TIME_Relative *val);
320 * Allow user to specify a `struct GNUNET_TIME_Absolute`
321 * (using human-readable "fancy" time).
323 * @param shortName short name of the option
324 * @param name long name of the option
325 * @param argumentHelp help text for the option argument
326 * @param description long help text for the option
327 * @param[out] val set to the time specified at the command line
329 struct GNUNET_GETOPT_CommandLineOption
330 GNUNET_GETOPT_OPTION_SET_ABSOLUTE_TIME (char shortName,
332 const char *argumentHelp,
333 const char *description,
334 struct GNUNET_TIME_Absolute *val);
338 * Increment @a val each time the option flag is given by one.
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 1 if the option is present
346 struct GNUNET_GETOPT_CommandLineOption
347 GNUNET_GETOPT_OPTION_INCREMENT_VALUE (char shortName,
349 const char *description,
354 * Define the '-L' log level option. Note that we do not check
355 * that the log level is valid here.
357 * @param[out] level set to the log level
359 struct GNUNET_GETOPT_CommandLineOption
360 GNUNET_GETOPT_OPTION_LOGLEVEL (char **level);
364 * Define the '-V' verbosity option. Using the option more
365 * than once increments @a level each time.
367 * @param[out] level set to the verbosity level
369 struct GNUNET_GETOPT_CommandLineOption
370 GNUNET_GETOPT_OPTION_VERBOSE (unsigned int *level);
374 * Allow user to specify log file name (-l option)
376 * @param[out] logfn set to the name of the logfile
378 struct GNUNET_GETOPT_CommandLineOption
379 GNUNET_GETOPT_OPTION_LOGFILE (char **logfn);
383 * Allow user to specify configuration file name (-c option)
385 * @param[out] fn set to the name of the configuration file
387 struct GNUNET_GETOPT_CommandLineOption
388 GNUNET_GETOPT_OPTION_CFG_FILE (char **fn);
392 * Marker for the end of the list of options.
394 #define GNUNET_GETOPT_OPTION_END \
395 { '\0', NULL, NULL, NULL, 0, NULL, NULL, NULL }
399 * Parse the command line.
401 * @param binaryOptions Name of application with option summary
402 * @param allOptions defined options and handlers
403 * @param argc number of arguments in @a argv
404 * @param argv actual arguments
405 * @return index into argv with first non-option
406 * argument, or #GNUNET_SYSERR on error
409 GNUNET_GETOPT_run (const char *binaryOptions,
410 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
415 #if 0 /* keep Emacsens' auto-indent happy */
422 /* ifndef GNUNET_GETOPT_LIB_H */
425 /** @} */ /* end of group getopt */
427 /* end of gnunet_getopt_lib.h */