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,
101 * @brief Definition of a command line option.
103 struct GNUNET_GETOPT_CommandLineOption
107 * Short name of the option.
109 const char shortName;
112 * Long name of the option (may not be NULL)
117 * Name of the argument for the user in help text
119 const char *argumentHelp;
122 * Help text for the option (description)
124 const char *description;
127 * Is an argument required? #GNUNET_NO (includes optional) or
128 * #GNUNET_YES (required)
130 int require_argument;
133 * Handler for the option.
135 GNUNET_GETOPT_CommandLineOptionProcessor processor;
138 * Specific closure to pass to the processor.
145 * Macro defining the option to print the command line
146 * help text (-h option).
148 * @param about string with brief description of the application
150 #define GNUNET_GETOPT_OPTION_HELP(about) \
151 { 'h', "help", (const char *) NULL, gettext_noop("print this help"), 0, &GNUNET_GETOPT_format_help_, (void *) about }
155 * Macro defining the option to print the version of
156 * the application (-v option)
158 * @param version string with the version number
160 #define GNUNET_GETOPT_OPTION_VERSION(version) \
161 { 'v', "version", (const char *) NULL, gettext_noop("print the version number"), 0, &GNUNET_GETOPT_print_version_, (void *) version }
165 * Allow user to specify log file name (-l option)
167 * @param logfn set to the name of the logfile
169 #define GNUNET_GETOPT_OPTION_LOGFILE(logfn) \
170 { 'l', "logfile", "LOGFILE", gettext_noop("configure logging to write logs to LOGFILE"), 1, &GNUNET_GETOPT_set_string, (void *) logfn }
174 * Allow user to specify log level (-L option)
176 * @param loglev set to the log level
178 #define GNUNET_GETOPT_OPTION_LOGLEVEL(loglev) \
179 { 'L', "log", "LOGLEVEL", gettext_noop("configure logging to use LOGLEVEL"), 1, &GNUNET_GETOPT_set_string, (void *) loglev }
183 * Get number of verbose (-V) flags
185 * @param level where to store the verbosity level (should be an 'int')
187 #define GNUNET_GETOPT_OPTION_VERBOSE(level) \
188 { 'V', "verbose", (const char *) NULL, gettext_noop("be verbose"), 0, &GNUNET_GETOPT_increment_value, (void *) level }
192 * Get configuration file name (-c option)
194 * @param fn set to the configuration file name
196 #define GNUNET_GETOPT_OPTION_CFG_FILE(fn) \
197 { 'c', "config", "FILENAME", gettext_noop("use configuration file FILENAME"), 1, &GNUNET_GETOPT_set_string, (void *) fn }
201 * Marker for the end of the list of options.
203 #define GNUNET_GETOPT_OPTION_END \
204 { '\0', NULL, NULL, NULL, 0, NULL, NULL }
208 * Parse the command line.
210 * @param binaryOptions Name of application with option summary
211 * @param allOptions defined options and handlers
212 * @param argc number of arguments in @a argv
213 * @param argv actual arguments
214 * @return index into argv with first non-option
215 * argument, or #GNUNET_SYSERR on error
218 GNUNET_GETOPT_run (const char *binaryOptions,
219 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
220 unsigned int argc, char *const *argv);
224 * Set an option of type 'unsigned long long' from the command line.
225 * A pointer to this function should be passed as part of the
226 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
227 * of this type. It should be followed by a pointer to a value of
228 * type `unsigned long long`.
230 * @param ctx command line processing context
231 * @param scls additional closure (will point to the 'unsigned long long')
232 * @param option name of the option
233 * @param value actual value of the option as a string.
234 * @return #GNUNET_OK if parsing the value worked
237 GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
238 void *scls, const char *option, const char *value);
242 * Set an option of type 'struct GNUNET_TIME_Relative' from the command line.
243 * A pointer to this function should be passed as part of the
244 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
245 * of this type. It should be followed by a pointer to a value of
246 * type `struct GNUNET_TIME_Relative`.
248 * @param ctx command line processing context
249 * @param scls additional closure (will point to the 'struct GNUNET_TIME_Relative')
250 * @param option name of the option
251 * @param value actual value of the option as a string.
252 * @return #GNUNET_OK if parsing the value worked
255 GNUNET_GETOPT_set_relative_time (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
256 void *scls, const char *option, const char *value);
260 * Set an option of type 'unsigned int' from the command line.
261 * A pointer to this function should be passed as part of the
262 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
263 * of this type. It should be followed by a pointer to a value of
264 * type `unsigned int`.
266 * @param ctx command line processing context
267 * @param scls additional closure (will point to the 'unsigned int')
268 * @param option name of the option
269 * @param value actual value of the option as a string.
270 * @return #GNUNET_OK if parsing the value worked
273 GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
274 void *scls, const char *option, const char *value);
278 * Set an option of type 'int' from the command line to 1 if the
279 * given option is present.
280 * A pointer to this function should be passed as part of the
281 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
282 * of this type. It should be followed by a pointer to a value of
285 * @param ctx command line processing context
286 * @param scls additional closure (will point to the `int`)
287 * @param option name of the option
288 * @param value not used (NULL)
289 * @return #GNUNET_OK (always)
292 GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
293 void *scls, const char *option, const char *value);
297 * Set an option of type 'char *' from the command line.
298 * A pointer to this function should be passed as part of the
299 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
300 * of this type. It should be followed by a pointer to a value of
301 * type `char *`, which will be allocated with the requested string.
303 * @param ctx command line processing context
304 * @param scls additional closure (will point to the `char *`,
305 * which will be allocated)
306 * @param option name of the option
307 * @param value actual value of the option (a string)
308 * @return #GNUNET_OK (always)
311 GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
312 void *scls, const char *option, const char *value);
316 * Set an option of type 'char *' from the command line doing fs expansion.
317 * A pointer to this function should be passed as part of the
318 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
319 * of this type. It should be followed by a pointer to a value of
320 * type 'char *', which will be allocated with the requested string.
322 * @param ctx command line processing context
323 * @param scls additional closure (will point to the 'char *',
324 * which will be allocated)
325 * @param option name of the option
326 * @param value actual value of the option (a string)
327 * @return #GNUNET_OK (always)
330 GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
331 void *scls, const char *option, const char *value);
334 * Set an option of type 'unsigned int' from the command line. Each
335 * time the option flag is given, the value is incremented by one.
336 * A pointer to this function should be passed as part of the
337 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
338 * of this type. It should be followed by a pointer to a value of
341 * @param ctx command line processing context
342 * @param scls additional closure (will point to the 'int')
343 * @param option name of the option
344 * @param value not used (NULL)
345 * @return #GNUNET_OK (always)
348 GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext
349 *ctx, void *scls, const char *option,
353 /* *************** internal prototypes - use macros above! ************* */
356 * Print out details on command line options (implements --help).
358 * @param ctx command line processing context
359 * @param scls additional closure (points to about text)
360 * @param option name of the option
361 * @param value not used (NULL)
362 * @return #GNUNET_NO (do not continue, not an error)
365 GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext
366 *ctx, void *scls, const char *option,
370 * Print out program version (implements --version).
372 * @param ctx command line processing context
373 * @param scls additional closure (points to version string)
374 * @param option name of the option
375 * @param value not used (NULL)
376 * @return #GNUNET_NO (do not continue, not an error)
379 GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext
380 *ctx, void *scls, const char *option,
383 #if 0 /* keep Emacsens' auto-indent happy */
390 /* ifndef GNUNET_GETOPT_LIB_H */
393 /** @} */ /* end of group getopt */
395 /* end of gnunet_getopt_lib.h */