2 This file is part of GNUnet.
3 (C) 2001-2013 Christian Grothoff (and other contributing authors)
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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_getopt_lib.h
23 * @brief command line parsing and --help formatting
24 * @author Christian Grothoff
25 * @defgroup getopt command-line parsing
29 #ifndef GNUNET_GETOPT_LIB_H
30 #define GNUNET_GETOPT_LIB_H
35 #if 0 /* keep Emacsens' auto-indent happy */
40 #include "gnunet_configuration_lib.h"
43 * @brief General context for command line processors.
45 struct GNUNET_GETOPT_CommandLineProcessorContext
49 * Name of the application
51 const char *binaryName;
54 * Name of application with option summary
56 const char *binaryOptions;
59 * Array with all command line options.
61 const struct GNUNET_GETOPT_CommandLineOption *allOptions;
64 * Original command line
69 * Total number of argv's.
76 unsigned int currentArgument;
81 * @brief Process a command line option
83 * @param ctx context for all options
84 * @param scls specific closure (for this processor)
85 * @param option long name of the option (i.e. "config" for --config)
86 * @param value argument, NULL if none was given
87 * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort
89 typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
90 GNUNET_GETOPT_CommandLineProcessorContext
96 * @brief Definition of a command line option.
98 struct GNUNET_GETOPT_CommandLineOption
102 * Short name of the option (use '\\0' for none).
104 const char shortName;
107 * Long name of the option (may not be NULL)
112 * Name of the argument for the user in help text
114 const char *argumentHelp;
117 * Help text for the option (description)
119 const char *description;
122 * Is an argument required? 0: GNUNET_NO (includes optional), 1: GNUNET_YES.
124 int require_argument;
127 * Handler for the option.
129 GNUNET_GETOPT_CommandLineOptionProcessor processor;
132 * Specific closure to pass to the processor.
139 * Macro defining the option to print the command line
140 * help text (-h option).
142 * @param about string with brief description of the application
144 #define GNUNET_GETOPT_OPTION_HELP(about) \
145 { 'h', "help", (const char *) NULL, gettext_noop("print this help"), 0, &GNUNET_GETOPT_format_help_, (void *) about }
149 * Macro defining the option to print the version of
150 * the application (-v option)
152 * @param version string with the version number
154 #define GNUNET_GETOPT_OPTION_VERSION(version) \
155 { 'v', "version", (const char *) NULL, gettext_noop("print the version number"), 0, &GNUNET_GETOPT_print_version_, (void *) version }
159 * Allow user to specify log file name (-l option)
161 * @param logfn set to the name of the logfile
163 #define GNUNET_GETOPT_OPTION_LOGFILE(logfn) \
164 { 'l', "logfile", "LOGFILE", gettext_noop("configure logging to write logs to LOGFILE"), 1, &GNUNET_GETOPT_set_string, (void *) logfn }
168 * Allow user to specify log level (-L option)
170 * @param loglev set to the log level
172 #define GNUNET_GETOPT_OPTION_LOGLEVEL(loglev) \
173 { 'L', "log", "LOGLEVEL", gettext_noop("configure logging to use LOGLEVEL"), 1, &GNUNET_GETOPT_set_string, (void *) loglev }
177 * Get number of verbose (-V) flags
179 * @param level where to store the verbosity level (should be an 'int')
181 #define GNUNET_GETOPT_OPTION_VERBOSE(level) \
182 { 'V', "verbose", (const char *) NULL, gettext_noop("be verbose"), 0, &GNUNET_GETOPT_increment_value, (void *) level }
186 * Get configuration file name (-c option)
188 * @param fn set to the configuration file name
190 #define GNUNET_GETOPT_OPTION_CFG_FILE(fn) \
191 { 'c', "config", "FILENAME", gettext_noop("use configuration file FILENAME"), 1, &GNUNET_GETOPT_set_string, (void *) fn }
195 * Marker for the end of the list of options.
197 #define GNUNET_GETOPT_OPTION_END \
198 { '\0', NULL, NULL, NULL, 0, NULL, NULL }
202 * Parse the command line.
204 * @param binaryOptions Name of application with option summary
205 * @param allOptions defined options and handlers
206 * @param argc number of arguments in @a argv
207 * @param argv actual arguments
208 * @return index into argv with first non-option
209 * argument, or #GNUNET_SYSERR on error
212 GNUNET_GETOPT_run (const char *binaryOptions,
213 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
214 unsigned int argc, char *const *argv);
218 * Set an option of type 'unsigned long long' from the command line.
219 * A pointer to this function should be passed as part of the
220 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
221 * of this type. It should be followed by a pointer to a value of
222 * type 'unsigned long long'.
224 * @param ctx command line processing context
225 * @param scls additional closure (will point to the 'unsigned long long')
226 * @param option name of the option
227 * @param value actual value of the option as a string.
228 * @return #GNUNET_OK if parsing the value worked
231 GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
232 void *scls, const char *option, const char *value);
236 * Set an option of type 'struct GNUNET_TIME_Relative' from the command line.
237 * A pointer to this function should be passed as part of the
238 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
239 * of this type. It should be followed by a pointer to a value of
240 * type 'struct GNUNET_TIME_Relative'.
242 * @param ctx command line processing context
243 * @param scls additional closure (will point to the 'struct GNUNET_TIME_Relative')
244 * @param option name of the option
245 * @param value actual value of the option as a string.
246 * @return #GNUNET_OK if parsing the value worked
249 GNUNET_GETOPT_set_relative_time (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
250 void *scls, const char *option, const char *value);
254 * Set an option of type 'unsigned int' from the command line.
255 * A pointer to this function should be passed as part of the
256 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
257 * of this type. It should be followed by a pointer to a value of
258 * type 'unsigned int'.
260 * @param ctx command line processing context
261 * @param scls additional closure (will point to the 'unsigned int')
262 * @param option name of the option
263 * @param value actual value of the option as a string.
264 * @return #GNUNET_OK if parsing the value worked
267 GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
268 void *scls, const char *option, const char *value);
272 * Set an option of type 'int' from the command line to 1 if the
273 * given option is present.
274 * A pointer to this function should be passed as part of the
275 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
276 * of this type. It should be followed by a pointer to a value of
279 * @param ctx command line processing context
280 * @param scls additional closure (will point to the 'int')
281 * @param option name of the option
282 * @param value not used (NULL)
283 * @return #GNUNET_OK (always)
286 GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
287 void *scls, const char *option, const char *value);
291 * Set an option of type 'char *' from the command line.
292 * A pointer to this function should be passed as part of the
293 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
294 * of this type. It should be followed by a pointer to a value of
295 * type 'char *', which will be allocated with the requested string.
297 * @param ctx command line processing context
298 * @param scls additional closure (will point to the 'char *',
299 * which will be allocated)
300 * @param option name of the option
301 * @param value actual value of the option (a string)
302 * @return #GNUNET_OK (always)
305 GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
306 void *scls, const char *option, const char *value);
310 * Set an option of type 'char *' from the command line doing fs expansion.
311 * A pointer to this function should be passed as part of the
312 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
313 * of this type. It should be followed by a pointer to a value of
314 * type 'char *', which will be allocated with the requested string.
316 * @param ctx command line processing context
317 * @param scls additional closure (will point to the 'char *',
318 * which will be allocated)
319 * @param option name of the option
320 * @param value actual value of the option (a string)
321 * @return #GNUNET_OK (always)
324 GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
325 void *scls, const char *option, const char *value);
328 * Set an option of type 'unsigned int' from the command line. Each
329 * time the option flag is given, the value is incremented by one.
330 * A pointer to this function should be passed as part of the
331 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
332 * of this type. It should be followed by a pointer to a value of
335 * @param ctx command line processing context
336 * @param scls additional closure (will point to the 'int')
337 * @param option name of the option
338 * @param value not used (NULL)
339 * @return #GNUNET_OK (always)
342 GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext
343 *ctx, void *scls, const char *option,
347 /* *************** internal prototypes - use macros above! ************* */
350 * Print out details on command line options (implements --help).
352 * @param ctx command line processing context
353 * @param scls additional closure (points to about text)
354 * @param option name of the option
355 * @param value not used (NULL)
356 * @return #GNUNET_NO (do not continue, not an error)
359 GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext
360 *ctx, void *scls, const char *option,
364 * Print out program version (implements --version).
366 * @param ctx command line processing context
367 * @param scls additional closure (points to version string)
368 * @param option name of the option
369 * @param value not used (NULL)
370 * @return #GNUNET_NO (do not continue, not an error)
373 GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext
374 *ctx, void *scls, const char *option,
377 #if 0 /* keep Emacsens' auto-indent happy */
384 /** @} */ /* end of group getopt */
386 /* ifndef GNUNET_GETOPT_LIB_H */
388 /* end of gnunet_getopt_lib.h */