GNU Gengetopt 2.21

It wasn't long ago since I released version 2.20 of GNU Gengetopt, and here's a new version.

First of all, I switched to version 3 of GPL.

Another novelty is that gengetopt generates doxygen comments in the generated header files. This way, if you use doxygen on your sources, you'll find also the documentation of the code generated by gengetopt.

Some build issues were fixed: parallel makes work again, and the make files do not depend on GNU make specific features (such as %. rules which are not standard - I must admit I didn't know this, but the new version of automake I started to use, i.e., version 1.10, reports a warning when you use such rules in your Makefile.am files, so I got to know about the problem).

Furthermore, the signatures of generated parser functions changed in a crucial way (of course, the previous signatures are still available, but they are deprecated and possibly removed in the future). In particular, besides the default parser functions (i.e., with default options), other versions are generated that accept further options, such as, e.g., initialize the argument structure, perform required options checks, etc. In the previous versions, this additional signature, whose name was the same as the main parser function with a 2 in the end, used to accept these options as single boolean (actually, integers) parameters. There's nothing wrong with this approach but it does not scale to future enhancements of the signature. In fact, a user requested another option (see the list of changes below) and adding that parameter to the signature would break existing code when regenerating the parser functions, since the code using those functions must be manually modified in order to use the new signature (in C++ this might be a small problem thanks to default values for parameters, but in C...). For this reason, the options are passed to the parser function in the shape of a structure: adding a field in the structure will not break existing code since the signature of the parser functions does not change. Notice that the structure object for these options should not be manually created and initialized (again, if a new field is added in future versions, that field might stay uninitialized), but it should be created and initialized by calling the dedicated generated init function. Here's a snippet of the generated header file (notice the new structure, the new signature with the _ext at the end, the deprecated old signature, and the init function for options):

/** @brief The additional parameters to pass to parser functions */
struct cmdline_parser_params
{
  int override; /**< @brief whether to override possibly already present options (default 0) */
  int initialize; /**< @brief whether to initialize the option structure gengetopt_args_info (default 0) */
  int check_required; /**< @brief whether to check that all required options were provided (default 0) */
  int check_ambiguity; /**< @brief whether to check for options already specified in the option structure gengetopt_args_info (default 0) */
} ;

/**
 * The command line parser
 * @param argc the number of command line options
 * @param argv the command line options
 * @param args_info the structure where option information will be stored
 * @return 0 if everything went fine, NON 0 if an error took place
 */
int cmdline_parser (int argc, char * const *argv,
  struct gengetopt_args_info *args_info);

/**
 * The command line parser (version with additional parameters - deprecated)
 * @param argc the number of command line options
 * @param argv the command line options
 * @param args_info the structure where option information will be stored
 * @param override whether to override possibly already present options
 * @param initialize whether to initialize the option structure my_args_info
 * @param check_required whether to check that all required options were provided
 * @return 0 if everything went fine, NON 0 if an error took place
 * @deprecated use cmdline_parser_ext() instead
 */
int cmdline_parser2 (int argc, char * const *argv,
  struct gengetopt_args_info *args_info,
  int override, int initialize, int check_required);

/**
 * The command line parser (version with additional parameters)
 * @param argc the number of command line options
 * @param argv the command line options
 * @param args_info the structure where option information will be stored
 * @param params additional parameters for the parser
 * @return 0 if everything went fine, NON 0 if an error took place
 */
int cmdline_parser_ext (int argc, char * const *argv,
  struct gengetopt_args_info *args_info,
  struct cmdline_parser_params *params);

/**
 * Allocates dynamically a cmdline_parser_params structure and initializes
 * all its fields to 0
 * @return the initialized cmdline_parser_params structure
 */
struct cmdline_parser_params *cmdline_parser_params_init();

Finally, here's the complete list of the new features:

   * a structure for parser function parameters (that might be extended
     in future versions)
   * a parser parameter to check whether an option that is parsed is
     already present in the args_info struct (suggested by
     Yegor Yefremov)
   * the generated files contain doxygen documentation (suggested by
     Yegor Yefremov)
   * parallel make works
   * generated make files should not depend on GNU make
   * fixed a bug with multiple options with back slashes (thanks to
     Peter Kovacs)
   * updated to version 3 of GPL