X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_getopt_lib.h;h=ddeeffef4325c0007ac142531e8a4fbc4dd07ac9;hb=2bbb2934dbbe471640c67c3bc672120f35708fd1;hp=d5f3d1198073529cc2cc8ca2af9a96da305c38ed;hpb=fe947a9704bed14c2fc74b2f2069596fe884cbad;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h index d5f3d1198..ddeeffef4 100644 --- a/src/include/gnunet_getopt_lib.h +++ b/src/include/gnunet_getopt_lib.h @@ -1,28 +1,32 @@ /* This file is part of GNUnet. - (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009 Christian Grothoff (and other contributing authors) + Copyright (C) 2001-2013 GNUnet e.V. - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + SPDX-License-Identifier: AGPL3.0-or-later */ /** - * @file include/gnunet_getopt_lib.h - * @brief command line parsing and --help formatting - * * @author Christian Grothoff + * + * @file + * Command line parsing and --help formatting + * + * @defgroup getopt Getopt library + * Command line parsing and --help formatting + * @{ */ #ifndef GNUNET_GETOPT_LIB_H @@ -76,6 +80,7 @@ struct GNUNET_GETOPT_CommandLineProcessorContext }; + /** * @brief Process a command line option * @@ -83,14 +88,15 @@ struct GNUNET_GETOPT_CommandLineProcessorContext * @param scls specific closure (for this processor) * @param option long name of the option (i.e. "config" for --config) * @param value argument, NULL if none was given - * @return GNUNET_OK to continue processing other options, GNUNET_SYSERR to abort + * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort */ -typedef - int (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct - GNUNET_GETOPT_CommandLineProcessorContext - * ctx, void *scls, - const char *option, - const char *value); +typedef int +(*GNUNET_GETOPT_CommandLineOptionProcessor) (struct + GNUNET_GETOPT_CommandLineProcessorContext *ctx, + void *scls, + const char *option, + const char *value); + /** * @brief Definition of a command line option. @@ -99,7 +105,7 @@ struct GNUNET_GETOPT_CommandLineOption { /** - * Short name of the option (use '\\0' for none). + * Short name of the option. */ const char shortName; @@ -119,15 +125,27 @@ struct GNUNET_GETOPT_CommandLineOption const char *description; /** - * Is an argument required? 0: GNUNET_NO (includes optional), 1: GNUNET_YES. + * Is an argument required? #GNUNET_NO (includes optional) or + * #GNUNET_YES (required) */ int require_argument; + /** + * Is the presence of this option mandatory? + */ + int option_mandatory; + /** * Handler for the option. */ GNUNET_GETOPT_CommandLineOptionProcessor processor; + /** + * Function to call on @e scls to clean up after processing all + * the arguments. Can be NULL. + */ + void (*cleaner)(void *cls); + /** * Specific closure to pass to the processor. */ @@ -135,122 +153,296 @@ struct GNUNET_GETOPT_CommandLineOption }; + /** - * Macro defining the option to print the command line - * help text. + * Defining the option to print the command line + * help text (-h option). * * @param about string with brief description of the application */ -#define GNUNET_GETOPT_OPTION_HELP(about) \ - { 'h', "help", (const char *) NULL, gettext_noop("print this help"), 0, &GNUNET_GETOPT_format_help_, (void *) about } +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_help (const char *about); + /** - * Macro defining the option to print the version of - * the application + * Define the option to print the version of + * the application (-v option) * * @param version string with the version number */ -#define GNUNET_GETOPT_OPTION_VERSION(version) \ - { 'v', "version", (const char *) NULL, gettext_noop("print the version number"), 0, &GNUNET_GETOPT_print_version_, (void *) version } +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_version (const char *version); + + /** - * Get the log level + * Allow user to specify log file name (-l option) + * + * @param[out] logfn set to the name of the logfile */ -#define GNUNET_GETOPT_OPTION_LOGFILE(logfn) \ - { 'l', "logfile", "LOGFILE", gettext_noop("configure logging to write logs to LOGFILE"), 1, &GNUNET_GETOPT_set_string, (void *) logfn } +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_logfile (char **logfn); + /** - * Set the configuration option for logging. + * Allow user to specify a string. + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] str set to the string */ -#define GNUNET_GETOPT_OPTION_LOGLEVEL(loglev) \ - { 'L', "log", "LOGLEVEL", gettext_noop("configure logging to use LOGLEVEL"), 1, &GNUNET_GETOPT_set_string, (void *) loglev } +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_string (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + char **str); /** - * Get number of verbose flags + * Allow user to specify a filename (automatically path expanded). + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] str set to the string */ -#define GNUNET_GETOPT_OPTION_VERBOSE(level) \ - { 'V', "verbose", (const char *) NULL, gettext_noop("be verbose"), 0, &GNUNET_GETOPT_increment_value, (void *) level } +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_filename (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + char **str); + /** - * Get configuration file name + * Allow user to specify a binary value using Crockford + * Base32 encoding. + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val binary value decoded from Crockford Base32-encoded argument + * @param val_size size of @a val in bytes */ -#define GNUNET_GETOPT_OPTION_CFG_FILE(fn) \ - { 'c', "config", "FILENAME", gettext_noop("use configuration file FILENAME"), 1, &GNUNET_GETOPT_set_string, (void *) fn } +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_base32_fixed_size (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + void *val, + size_t val_size); + /** - * Marker to end the list of options. + * Allow user to specify a binary value using Crockford + * Base32 encoding where the size of the binary value is + * automatically determined from its type. + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val binary value decoded from Crockford Base32-encoded argument; + * size is determined by type (sizeof (*val)). */ -#define GNUNET_GETOPT_OPTION_END \ - { '\0', NULL, NULL, NULL, 0, NULL, NULL } +#define GNUNET_GETOPT_option_base32_auto(shortName,name,argumentHelp,description,val) \ + GNUNET_GETOPT_option_base32_fixed_size(shortName,name,argumentHelp,description,val,sizeof(*val)) + /** - * Parse the command line. + * Allow user to specify a flag (which internally means setting + * an integer to 1/#GNUNET_YES/#GNUNET_OK. * - * @param binaryOptions Name of application with option summary - * @param allOptions defined options and handlers - * @param argc number of arguments - * @param argv actual arguments - * @return index into argv with first non-option - * argument, or GNUNET_SYSERR on error + * @param shortName short name of the option + * @param name long name of the option + * @param description long help text for the option + * @param[out] val set to 1 if the option is present + */ +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_flag (char shortName, + const char *name, + const char *description, + int *val); + + +/** + * Allow user to specify an `unsigned int`. + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val set to the value specified at the command line + */ +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_uint (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + unsigned int *val); + + +/** + * Allow user to specify an uint16_t. + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val set to the value specified at the command line + */ +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_uint16 (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + uint16_t *val); + + +/** + * Allow user to specify an `unsigned long long`. + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val set to the value specified at the command line */ -int GNUNET_GETOPT_run (const char *binaryOptions, - const struct GNUNET_GETOPT_CommandLineOption - *allOptions, unsigned int argc, char *const *argv); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_ulong (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + unsigned long long *val); + /** - * FIXME + * Allow user to specify a `struct GNUNET_TIME_Relative` + * (using human-readable "fancy" time). + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val set to the time specified at the command line */ -int GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext - *ctx, void *scls, const char *option, - const char *value); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_relative_time (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + struct GNUNET_TIME_Relative *val); + /** - * FIXME + * Allow user to specify a `struct GNUNET_TIME_Absolute` + * (using human-readable "fancy" time). + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val set to the time specified at the command line */ -int GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext - *ctx, void *scls, const char *option, - const char *value); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_absolute_time (char shortName, + const char *name, + const char *argumentHelp, + const char *description, + struct GNUNET_TIME_Absolute *val); + /** - * FIXME + * Increment @a val each time the option flag is given by one. + * + * @param shortName short name of the option + * @param name long name of the option + * @param argumentHelp help text for the option argument + * @param description long help text for the option + * @param[out] val set to 1 if the option is present */ -int GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext - *ctx, void *scls, const char *option, - const char *value); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_increment_uint (char shortName, + const char *name, + const char *description, + unsigned int *val); + /** - * FIXME + * Define the '-L' log level option. Note that we do not check + * that the log level is valid here. + * + * @param[out] level set to the log level */ -int GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext - *ctx, void *scls, const char *option, - const char *value); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_loglevel (char **level); + /** - * FIXME + * Define the '-V' verbosity option. Using the option more + * than once increments @a level each time. + * + * @param[out] level set to the verbosity level */ -int -GNUNET_GETOPT_increment_value (struct - GNUNET_GETOPT_CommandLineProcessorContext *ctx, - void *scls, const char *option, - const char *value); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_verbose (unsigned int *level); -/* *************** internal prototypes - use macros above! ************* */ /** - * FIXME + * Allow user to specify log file name (-l option) + * + * @param[out] logfn set to the name of the logfile */ -int GNUNET_GETOPT_format_help_ (struct - GNUNET_GETOPT_CommandLineProcessorContext - *ctx, void *scls, const char *option, - const char *value); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_logfile (char **logfn); + /** - * FIXME + * Allow user to specify configuration file name (-c option) + * + * @param[out] fn set to the name of the configuration file */ -int GNUNET_GETOPT_print_version_ (struct - GNUNET_GETOPT_CommandLineProcessorContext - *ctx, void *scls, const char *option, - const char *value); +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_cfgfile (char **fn); + + +/** + * Make the given option mandatory. + * + * @param opt option to modify + * @return @a opt with the mandatory flag set. + */ +struct GNUNET_GETOPT_CommandLineOption +GNUNET_GETOPT_option_mandatory (struct GNUNET_GETOPT_CommandLineOption opt); + + +/** + * Marker for the end of the list of options. + */ +#define GNUNET_GETOPT_OPTION_END \ + { '\0', NULL, NULL, NULL, 0, 0, NULL, NULL, NULL } + + +/** + * Parse the command line. + * + * @param binaryOptions Name of application with option summary + * @param allOptions defined options and handlers + * @param argc number of arguments in @a argv + * @param argv actual arguments + * @return index into argv with first non-option + * argument, or #GNUNET_SYSERR on error + */ +int +GNUNET_GETOPT_run (const char *binaryOptions, + const struct GNUNET_GETOPT_CommandLineOption *allOptions, + unsigned int argc, + char *const *argv); + #if 0 /* keep Emacsens' auto-indent happy */ { @@ -259,7 +451,9 @@ int GNUNET_GETOPT_print_version_ (struct } #endif - /* ifndef GNUNET_GETOPT_LIB_H */ #endif + +/** @} */ /* end of group getopt */ + /* end of gnunet_getopt_lib.h */