2 This file is part of GNUnet.
3 Copyright (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., 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;
84 * @brief Process a command line option
86 * @param ctx context for all options
87 * @param scls specific closure (for this processor)
88 * @param option long name of the option (i.e. "config" for --config)
89 * @param value argument, NULL if none was given
90 * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort
92 typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
93 GNUNET_GETOPT_CommandLineProcessorContext *ctx,
99 * @brief Definition of a command line option.
101 struct GNUNET_GETOPT_CommandLineOption
105 * Short name of the option.
107 const char shortName;
110 * Long name of the option (may not be NULL)
115 * Name of the argument for the user in help text
117 const char *argumentHelp;
120 * Help text for the option (description)
122 const char *description;
125 * Is an argument required? 0: #GNUNET_NO (includes optional), 1: #GNUNET_YES.
127 int require_argument;
130 * Handler for the option.
132 GNUNET_GETOPT_CommandLineOptionProcessor processor;
135 * Specific closure to pass to the processor.
142 * Macro defining the option to print the command line
143 * help text (-h option).
145 * @param about string with brief description of the application
147 #define GNUNET_GETOPT_OPTION_HELP(about) \
148 { 'h', "help", (const char *) NULL, gettext_noop("print this help"), 0, &GNUNET_GETOPT_format_help_, (void *) about }
152 * Macro defining the option to print the version of
153 * the application (-v option)
155 * @param version string with the version number
157 #define GNUNET_GETOPT_OPTION_VERSION(version) \
158 { 'v', "version", (const char *) NULL, gettext_noop("print the version number"), 0, &GNUNET_GETOPT_print_version_, (void *) version }
162 * Allow user to specify log file name (-l option)
164 * @param logfn set to the name of the logfile
166 #define GNUNET_GETOPT_OPTION_LOGFILE(logfn) \
167 { 'l', "logfile", "LOGFILE", gettext_noop("configure logging to write logs to LOGFILE"), 1, &GNUNET_GETOPT_set_string, (void *) logfn }
171 * Allow user to specify log level (-L option)
173 * @param loglev set to the log level
175 #define GNUNET_GETOPT_OPTION_LOGLEVEL(loglev) \
176 { 'L', "log", "LOGLEVEL", gettext_noop("configure logging to use LOGLEVEL"), 1, &GNUNET_GETOPT_set_string, (void *) loglev }
180 * Get number of verbose (-V) flags
182 * @param level where to store the verbosity level (should be an 'int')
184 #define GNUNET_GETOPT_OPTION_VERBOSE(level) \
185 { 'V', "verbose", (const char *) NULL, gettext_noop("be verbose"), 0, &GNUNET_GETOPT_increment_value, (void *) level }
189 * Get configuration file name (-c option)
191 * @param fn set to the configuration file name
193 #define GNUNET_GETOPT_OPTION_CFG_FILE(fn) \
194 { 'c', "config", "FILENAME", gettext_noop("use configuration file FILENAME"), 1, &GNUNET_GETOPT_set_string, (void *) fn }
198 * Marker for the end of the list of options.
200 #define GNUNET_GETOPT_OPTION_END \
201 { '\0', NULL, NULL, NULL, 0, NULL, NULL }
205 * Parse the command line.
207 * @param binaryOptions Name of application with option summary
208 * @param allOptions defined options and handlers
209 * @param argc number of arguments in @a argv
210 * @param argv actual arguments
211 * @return index into argv with first non-option
212 * argument, or #GNUNET_SYSERR on error
215 GNUNET_GETOPT_run (const char *binaryOptions,
216 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
217 unsigned int argc, char *const *argv);
221 * Set an option of type 'unsigned long long' from the command line.
222 * A pointer to this function should be passed as part of the
223 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
224 * of this type. It should be followed by a pointer to a value of
225 * type `unsigned long long`.
227 * @param ctx command line processing context
228 * @param scls additional closure (will point to the 'unsigned long long')
229 * @param option name of the option
230 * @param value actual value of the option as a string.
231 * @return #GNUNET_OK if parsing the value worked
234 GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
235 void *scls, const char *option, const char *value);
239 * Set an option of type 'struct GNUNET_TIME_Relative' from the command line.
240 * A pointer to this function should be passed as part of the
241 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
242 * of this type. It should be followed by a pointer to a value of
243 * type `struct GNUNET_TIME_Relative`.
245 * @param ctx command line processing context
246 * @param scls additional closure (will point to the 'struct GNUNET_TIME_Relative')
247 * @param option name of the option
248 * @param value actual value of the option as a string.
249 * @return #GNUNET_OK if parsing the value worked
252 GNUNET_GETOPT_set_relative_time (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
253 void *scls, const char *option, const char *value);
257 * Set an option of type 'unsigned int' from the command line.
258 * A pointer to this function should be passed as part of the
259 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
260 * of this type. It should be followed by a pointer to a value of
261 * type `unsigned int`.
263 * @param ctx command line processing context
264 * @param scls additional closure (will point to the 'unsigned int')
265 * @param option name of the option
266 * @param value actual value of the option as a string.
267 * @return #GNUNET_OK if parsing the value worked
270 GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
271 void *scls, const char *option, const char *value);
275 * Set an option of type 'int' from the command line to 1 if the
276 * given option is present.
277 * A pointer to this function should be passed as part of the
278 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
279 * of this type. It should be followed by a pointer to a value of
282 * @param ctx command line processing context
283 * @param scls additional closure (will point to the `int`)
284 * @param option name of the option
285 * @param value not used (NULL)
286 * @return #GNUNET_OK (always)
289 GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
290 void *scls, const char *option, const char *value);
294 * Set an option of type 'char *' from the command line.
295 * A pointer to this function should be passed as part of the
296 * `struct GNUNET_GETOPT_CommandLineOption` array to initialize options
297 * of this type. It should be followed by a pointer to a value of
298 * type `char *`, which will be allocated with the requested string.
300 * @param ctx command line processing context
301 * @param scls additional closure (will point to the `char *`,
302 * which will be allocated)
303 * @param option name of the option
304 * @param value actual value of the option (a string)
305 * @return #GNUNET_OK (always)
308 GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
309 void *scls, const char *option, const char *value);
313 * Set an option of type 'char *' from the command line doing fs expansion.
314 * A pointer to this function should be passed as part of the
315 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
316 * of this type. It should be followed by a pointer to a value of
317 * type 'char *', which will be allocated with the requested string.
319 * @param ctx command line processing context
320 * @param scls additional closure (will point to the 'char *',
321 * which will be allocated)
322 * @param option name of the option
323 * @param value actual value of the option (a string)
324 * @return #GNUNET_OK (always)
327 GNUNET_GETOPT_set_filename (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
328 void *scls, const char *option, const char *value);
331 * Set an option of type 'unsigned int' from the command line. Each
332 * time the option flag is given, the value is incremented by one.
333 * A pointer to this function should be passed as part of the
334 * 'struct GNUNET_GETOPT_CommandLineOption' array to initialize options
335 * of this type. It should be followed by a pointer to a value of
338 * @param ctx command line processing context
339 * @param scls additional closure (will point to the 'int')
340 * @param option name of the option
341 * @param value not used (NULL)
342 * @return #GNUNET_OK (always)
345 GNUNET_GETOPT_increment_value (struct GNUNET_GETOPT_CommandLineProcessorContext
346 *ctx, void *scls, const char *option,
350 /* *************** internal prototypes - use macros above! ************* */
353 * Print out details on command line options (implements --help).
355 * @param ctx command line processing context
356 * @param scls additional closure (points to about text)
357 * @param option name of the option
358 * @param value not used (NULL)
359 * @return #GNUNET_NO (do not continue, not an error)
362 GNUNET_GETOPT_format_help_ (struct GNUNET_GETOPT_CommandLineProcessorContext
363 *ctx, void *scls, const char *option,
367 * Print out program version (implements --version).
369 * @param ctx command line processing context
370 * @param scls additional closure (points to version string)
371 * @param option name of the option
372 * @param value not used (NULL)
373 * @return #GNUNET_NO (do not continue, not an error)
376 GNUNET_GETOPT_print_version_ (struct GNUNET_GETOPT_CommandLineProcessorContext
377 *ctx, void *scls, const char *option,
380 #if 0 /* keep Emacsens' auto-indent happy */
387 /* ifndef GNUNET_GETOPT_LIB_H */
390 /** @} */ /* end of group getopt */
392 /* end of gnunet_getopt_lib.h */