GNU Gengetopt 2.23

lazy

myprog --input foo.c -o foo.o --no-tabs -i 100 *.class

cd <source code main directory>
./configure
make
make install

git clone git://git.savannah.gnu.org/gengetopt.git

autoreconf -i

package "<packname>"
version "<version>"
purpose "<purpose>"
usage "<usage>"
description "<description>"
versiontext "<versiontext>"

args "<command line options>"

option <long> <short> "<desc>"
	{details="<detailed description>"}
	{argtype} {typestr="<type descr>"}
	{values="<value1>","<value2>",...}
	{default="<default value>"}
	{dependon="<other option>"}
	{required} {argoptional} {multiple}
	{hidden}

option <long> <short> "<desc>" flag <on/off>

section "section name" {sectiondesc="optional section description"}

text "a textual sentence"

args "--no-handle-error --string-parser -u"

"This string will be interpreted
into two lines exactly as it is"

"This string is specified with two lines \
but interpreted as specified in only one line \
i.e., without explicit line break"

"This string\nwill have a line break"

"This string contains \"a quoted string\" inside"

option <long> <short> "<desc>"

option <long> <short> "<desc>" {argtype} {typestr="<type descr>"}

option <long> <short> "<desc>" {typestr="<type descr>"} {argtype}

section "section name" {sectiondesc="optional section description"}

text "\nA text description with possible line\nbreaks"

text ""

# Name of your program
package "sample1" # don't use package if you're using automake
# Version of your program
version "2.0"   # don't use version if you're using automake

# Options
option  "str-opt"         s "A string option, for a filename"
        string typestr="filename"     optional
text "\nA brief text description"
text " before the other options.\n"
option  "my-opt"          m "Another integer option, \
this time the description of the option should be \"quite\" long to \
require wrapping... possibly more than one wrapping :-) \
especially if I\nrequire a line break"      int     optional
option  "int-opt"         i "A int option"         int        yes
section "more involved options" 
        sectiondesc="the following options\nare more complex"
text ""
option  "flag-opt"        - "A flag option"        flag       off
option  "funct-opt"       F "A function option"    optional 
    details="\nA function option is basically an option with no argument.\
  It can be used, e.g., to specify a specific behavior for a program.

Well, this further explanation is quite useless, but it's only to \
show an example of an option with details, \
which will be printed only when --detailed-help is given \
at the command line."
section "last option section"
option  "long-opt"        - "A long option"        long       optional
option  "def-opt"         - "A string option with default" 
        string default="Hello" optional
option  "enum-opt"         - "A string option with list of values" 
        values="foo","bar","hello","bye" default="hello" optional
option  "secret"         S "hidden option will not appear in --help" 
        int optional hidden
option  "dependant"         D 
        "option that depends on str-opt" int optional dependon="str-opt"
text "\nAn ending text."

gengetopt < sample1.ggo

gengetopt < sample1.ggo --file-name=cmdline1 --unnamed-opts

/** @file cmdline1.h
 *  @brief The header file for the command line option parser
 *  generated by GNU Gengetopt version 2.23
 *  http://www.gnu.org/software/gengetopt.
 *  DO NOT modify this file, since it can be overwritten
 *  @author GNU Gengetopt */

#ifndef CMDLINE1_H
#define CMDLINE1_H

/* If we use autoconf.  */
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <stdio.h> /* for FILE */

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

#ifndef CMDLINE_PARSER_PACKAGE
/** @brief the program name (used for printing errors) */
#define CMDLINE_PARSER_PACKAGE "sample1"
#endif

#ifndef CMDLINE_PARSER_PACKAGE_NAME
/** @brief the complete program name (used for help and version) */
#define CMDLINE_PARSER_PACKAGE_NAME "sample1"
#endif

#ifndef CMDLINE_PARSER_VERSION
/** @brief the program version */
#define CMDLINE_PARSER_VERSION "2.0"
#endif

/** @brief Where the command line options are stored */
struct gengetopt_args_info
{
  const char *help_help; /**< @brief Print help and exit help description.  */
  const char *detailed_help_help; /**< @brief Print help, including all details and hidden options, and exit help description.  */
  const char *full_help_help; /**< @brief Print help, including hidden options, and exit help description.  */
  const char *version_help; /**< @brief Print version and exit help description.  */
  char * str_opt_arg;	/**< @brief A string option, for a filename.  */
  char * str_opt_orig;	/**< @brief A string option, for a filename original value given at command line.  */
  const char *str_opt_help; /**< @brief A string option, for a filename help description.  */
  int my_opt_arg;	/**< @brief Another integer option, this time the description of the option should be \"quite\" long to require wrapping... possibly more than one wrapping :-) especially if I
  require a line break.  */
  char * my_opt_orig;	/**< @brief Another integer option, this time the description of the option should be \"quite\" long to require wrapping... possibly more than one wrapping :-) especially if I
  require a line break original value given at command line.  */
  const char *my_opt_help; /**< @brief Another integer option, this time the description of the option should be \"quite\" long to require wrapping... possibly more than one wrapping :-) especially if I
  require a line break help description.  */
  int int_opt_arg;	/**< @brief A int option.  */
  char * int_opt_orig;	/**< @brief A int option original value given at command line.  */
  const char *int_opt_help; /**< @brief A int option help description.  */
  int flag_opt_flag;	/**< @brief A flag option (default=off).  */
  const char *flag_opt_help; /**< @brief A flag option help description.  */
  const char *funct_opt_help; /**< @brief A function option help description.  */
  long long_opt_arg;	/**< @brief A long option.  */
  char * long_opt_orig;	/**< @brief A long option original value given at command line.  */
  const char *long_opt_help; /**< @brief A long option help description.  */
  char * def_opt_arg;	/**< @brief A string option with default (default='Hello').  */
  char * def_opt_orig;	/**< @brief A string option with default original value given at command line.  */
  const char *def_opt_help; /**< @brief A string option with default help description.  */
  char * enum_opt_arg;	/**< @brief A string option with list of values (default='hello').  */
  char * enum_opt_orig;	/**< @brief A string option with list of values original value given at command line.  */
  const char *enum_opt_help; /**< @brief A string option with list of values help description.  */
  int secret_arg;	/**< @brief hidden option will not appear in --help.  */
  char * secret_orig;	/**< @brief hidden option will not appear in --help original value given at command line.  */
  const char *secret_help; /**< @brief hidden option will not appear in --help help description.  */
  int dependant_arg;	/**< @brief option that depends on str-opt.  */
  char * dependant_orig;	/**< @brief option that depends on str-opt original value given at command line.  */
  const char *dependant_help; /**< @brief option that depends on str-opt help description.  */

  unsigned int help_given ;	/**< @brief Whether help was given.  */
  unsigned int detailed_help_given ;	/**< @brief Whether detailed-help was given.  */
  unsigned int full_help_given ;	/**< @brief Whether full-help was given.  */
  unsigned int version_given ;	/**< @brief Whether version was given.  */
  unsigned int str_opt_given ;	/**< @brief Whether str-opt was given.  */
  unsigned int my_opt_given ;	/**< @brief Whether my-opt was given.  */
  unsigned int int_opt_given ;	/**< @brief Whether int-opt was given.  */
  unsigned int flag_opt_given ;	/**< @brief Whether flag-opt was given.  */
  unsigned int funct_opt_given ;	/**< @brief Whether funct-opt was given.  */
  unsigned int long_opt_given ;	/**< @brief Whether long-opt was given.  */
  unsigned int def_opt_given ;	/**< @brief Whether def-opt was given.  */
  unsigned int enum_opt_given ;	/**< @brief Whether enum-opt was given.  */
  unsigned int secret_given ;	/**< @brief Whether secret was given.  */
  unsigned int dependant_given ;	/**< @brief Whether dependant was given.  */

  char **inputs ; /**< @brief unnamed options (options without names) */
  unsigned inputs_num ; /**< @brief unnamed options number */
} ;

/** @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 1) */
  int check_required; /**< @brief whether to check that all required options were provided (default 1) */
  int check_ambiguity; /**< @brief whether to check for options already specified in the option structure gengetopt_args_info (default 0) */
  int print_errors; /**< @brief whether getopt_long should print an error message for a bad option (default 1) */
} ;

/** @brief the purpose string of the program */
extern const char *gengetopt_args_info_purpose;
/** @brief the usage string of the program */
extern const char *gengetopt_args_info_usage;
/** @brief the description string of the program */
extern const char *gengetopt_args_info_description;
/** @brief all the lines making the help output */
extern const char *gengetopt_args_info_help[];
/** @brief all the lines making the full help output (including hidden options) */
extern const char *gengetopt_args_info_full_help[];
/** @brief all the lines making the detailed help output (including hidden options and details) */
extern const char *gengetopt_args_info_detailed_help[];

/**
 * 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 **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 **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 **argv,
  struct gengetopt_args_info *args_info,
  struct cmdline_parser_params *params);

/**
 * Save the contents of the option struct into an already open FILE stream.
 * @param outfile the stream where to dump options
 * @param args_info the option struct to dump
 * @return 0 if everything went fine, NON 0 if an error took place
 */
int cmdline_parser_dump(FILE *outfile,
  struct gengetopt_args_info *args_info);

/**
 * Save the contents of the option struct into a (text) file.
 * This file can be read by the config file parser (if generated by gengetopt)
 * @param filename the file where to save
 * @param args_info the option struct to save
 * @return 0 if everything went fine, NON 0 if an error took place
 */
int cmdline_parser_file_save(const char *filename,
  struct gengetopt_args_info *args_info);

/**
 * Print the help
 */
void cmdline_parser_print_help(void);
/**
 * Print the full help (including hidden options)
 */
void cmdline_parser_print_full_help(void);
/**
 * Print the detailed help (including hidden options and details)
 */
void cmdline_parser_print_detailed_help(void);
/**
 * Print the version
 */
void cmdline_parser_print_version(void);

/**
 * Initializes all the fields a cmdline_parser_params structure 
 * to their default values
 * @param params the structure to initialize
 */
void cmdline_parser_params_init(struct cmdline_parser_params *params);

/**
 * Allocates dynamically a cmdline_parser_params structure and initializes
 * all its fields to their default values
 * @return the created and initialized cmdline_parser_params structure
 */
struct cmdline_parser_params *cmdline_parser_params_create(void);

/**
 * Initializes the passed gengetopt_args_info structure's fields
 * (also set default values for options that have a default)
 * @param args_info the structure to initialize
 */
void cmdline_parser_init (struct gengetopt_args_info *args_info);
/**
 * Deallocates the string fields of the gengetopt_args_info structure
 * (but does not deallocate the structure itself)
 * @param args_info the structure to deallocate
 */
void cmdline_parser_free (struct gengetopt_args_info *args_info);

/**
 * Checks that all the required options were specified
 * @param args_info the structure to check
 * @param prog_name the name of the program that will be used to print
 *   possible errors
 * @return
 */
int cmdline_parser_required (struct gengetopt_args_info *args_info,
  const char *prog_name);

extern const char *cmdline_parser_enum_opt_values[];  /**< @brief Possible values for enum-opt. */

#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* CMDLINE1_H */

/* main1.cc */
/* we try to use gengetopt generated file in a C++ program */
/* we don't use autoconf and automake vars */

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <iostream>
#include "stdlib.h"

#include "cmdline1.h"

using std::cout;
using std::endl;

int
main (int argc, char **argv)
{
  gengetopt_args_info args_info;

  cout << "This one is from a C++ program" << endl ;
  cout << "Try to launch me with some options" << endl ;
  cout << "(type sample1 --help for the complete list)" << endl ;
  cout << "For example: ./sample1 *.* --funct-opt" << endl ;

  /* let's call our cmdline parser */
  if (cmdline_parser (argc, argv, &args_info) != 0)
    exit(1) ;

  cout << "Here are the options you passed..." << endl;

  for ( unsigned i = 0 ; i < args_info.inputs_num ; ++i )
    cout << "file: " << args_info.inputs[i] << endl ;

  if ( args_info.funct_opt_given )
    cout << "You chose --funct-opt or -F." << endl ;

  if ( args_info.str_opt_given )
    cout << "You inserted " << args_info.str_opt_arg << " for " <<
      "--str-opt option." << endl ;

  if ( args_info.int_opt_given )
    cout << "This is the integer you input: " << 
      args_info.int_opt_arg << "." << endl;

  if (args_info.flag_opt_given)
    cout << "The flag option was given!" << endl;

  cout << "The flag is " << ( args_info.flag_opt_flag ? "on" : "off" ) <<
    "." << endl ;

  if (args_info.enum_opt_given) {
    cout << "enum-opt value: " << args_info.enum_opt_arg << endl;
    cout << "enum-opt (original specified) value: " 
	 << args_info.enum_opt_orig << endl;
  }

  if (args_info.secret_given)
    cout << "Secret option was specified: " << args_info.secret_arg
	 << endl;

  cout << args_info.def_opt_arg << "! ";

  cout << "Have a nice day! :-)" << endl ;

  cmdline_parser_free (&args_info); /* release allocated memory */

  return 0;
}

gcc -c cmdline1.c
g++ -c main1.cc
g++ -o sample1 cmdline1.o main1.o

$ ./sample1 -s "hello" --int-opt 1234
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
You inserted hello for --str-opt option.
This is the integer you input: 1234.
The flag is off.
Have a nice day! :-)

$ ./sample1 *.h -i -100 -x
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
file: cmdline1.h
file: cmdline2.h
file: cmdline.h
file: getopt.h
This is the integer you input: -100.
The flag is on.
Have a nice day! :-)

$ ./sample1
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
sample1: `--int-opt' (`-i') option required!

$ ./sample1 -i 10 --enum-opt h
...
enum-opt value: hello
enum-opt (original specified) value: h
...

$ ./sample1 -i 10 --enum-opt b
...
./sample1: ambiguous argument, "b", for option `--enum-opt'

This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Usage: sample1 -iINT|--int-opt=INT [-h|--help] [--detailed-help] [--full-help]
         [-V|--version] [-sfilename|--str-opt=filename] [-mINT|--my-opt=INT]
         [--flag-opt] [-F|--funct-opt] [--long-opt=LONG] [--def-opt=STRING]
         [--enum-opt=STRING] [-DINT|--dependant=INT] [FILE]...

  -h, --help              Print help and exit
      --detailed-help     Print help, including all details and hidden options,
                            and exit
      --full-help         Print help, including hidden options, and exit
  -V, --version           Print version and exit
  -s, --str-opt=filename  A string option, for a filename

A brief text description before the other options.

  -m, --my-opt=INT        Another integer option, this time the description of
                            the option should be "quite" long to require
                            wrapping... possibly more than one wrapping :-)
                            especially if I
                            require a line break
  -i, --int-opt=INT       A int option (mandatory)

more involved options:
  the following options
  are more complex
      --flag-opt          A flag option  (default=off)
  -F, --funct-opt         A function option

last option section:
      --long-opt=LONG     A long option
      --def-opt=STRING    A string option with default  (default=`Hello')
      --enum-opt=STRING   A string option with list of values  (possible
                            values="foo", "bar", "hello", "bye"
                            default=`hello')
  -D, --dependant=INT     option that depends on str-opt

An ending text.

This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Usage: sample1 -iINT|--int-opt=INT [-h|--help] [--detailed-help] [--full-help]
         [-V|--version] [-sfilename|--str-opt=filename] [-mINT|--my-opt=INT]
         [--flag-opt] [-F|--funct-opt] [--long-opt=LONG] [--def-opt=STRING]
         [--enum-opt=STRING] [-DINT|--dependant=INT] [FILE]...

  -h, --help              Print help and exit
      --detailed-help     Print help, including all details and hidden options,
                            and exit
      --full-help         Print help, including hidden options, and exit
  -V, --version           Print version and exit
  -s, --str-opt=filename  A string option, for a filename

A brief text description before the other options.

  -m, --my-opt=INT        Another integer option, this time the description of
                            the option should be "quite" long to require
                            wrapping... possibly more than one wrapping :-)
                            especially if I
                            require a line break
  -i, --int-opt=INT       A int option (mandatory)

more involved options:
  the following options
  are more complex
      --flag-opt          A flag option  (default=off)
  -F, --funct-opt         A function option

  A function option is basically an option with no argument.  It can be used,
  e.g., to specify a specific behavior for a program.

  Well, this further explanation is quite useless, but it's only to show an
  example of an option with details, which will be printed only when
  --detailed-help is given at the command line.

last option section:
      --long-opt=LONG     A long option
      --def-opt=STRING    A string option with default  (default=`Hello')
      --enum-opt=STRING   A string option with list of values  (possible
                            values="foo", "bar", "hello", "bye"
                            default=`hello')
  -S, --secret=INT        hidden option will not appear in --help
  -D, --dependant=INT     option that depends on str-opt

An ending text.

gengetopt 

This program generates a C function that uses getopt_long function
to parse the command line options, validate them and fill a struct.

Usage: gengetopt [OPTION]...

  -h, --help                    Print help and exit
      --detailed-help           Print help, including all details and hidden
                                  options, and exit
      --full-help               Print help, including hidden options, and exit
  -V, --version                 Print version and exit

Main options:

  -i, --input=filename          input file (default std input)
  -f, --func-name=name          name of generated function
                                  (default=`cmdline_parser')
  -a, --arg-struct-name=name    name of generated args info struct
                                  (default=`gengetopt_args_info')
  -F, --file-name=name          name of generated file  (default=`cmdline')
      --output-dir=path         output directory
      --header-output-dir=path  header output directory
      --src-output-dir=path     source output directory
  -c, --c-extension=ext         extension of c file  (default=`c')
  -H, --header-extension=ext    extension of header file  (default=`h')
  -l, --long-help               long usage line in help
      --default-optional        by default, an option is considered optional if
                                  not specified otherwise
  -u, --unnamed-opts[=STRING]   accept options without names (e.g., file names)
                                  (default=`FILE')

The parser generated is thought to be used to parse the command line arguments.
However, you can also generate parsers for configuration files, or strings that
contain the arguments to parse, by using the following two options.

  -C, --conf-parser             generate a config file parser
  -S, --string-parser           generate a string parser (the string contains
                                  the command line)

Additional options:
  -G, --include-getopt          adds the code for getopt_long in the generated
                                  C file
  -n, --no-handle-help          do not handle --help|-h automatically
      --no-help                 do not add --help|-h automatically
  -N, --no-handle-version       do not handle --version|-V automatically
      --no-version              do not add --version|-V automatically
  -e, --no-handle-error         do not exit on errors
      --show-required[=STRING]  in the output of help will specify which
                                  options are mandatory, by using the optional
                                  passed string  (default=`(mandatory)')
      --strict-hidden           completely hide hidden options
  -g, --gen-version             put gengetopt version in the generated file
                                  (default=on)
      --set-package=STRING      set the package name (override package defined
                                  in the .ggo file)
      --set-version=STRING      set the version number (override version
                                  defined in the .ggo file)
      --show-help               show the output of --help instead of generating
                                  code
      --show-full-help          show the output of --full-help (i.e., including
                                  hidden options) instead of generating code
      --show-detailed-help      show the output of --detailed-help (i.e.,
                                  including details and hidden options) instead
                                  of generating code
      --show-version            show the output of --version instead of
                                  generating code

Please refer to the info manual for further explanations.

../src/gengetopt --show-help -i ../src/cmdline.ggo \
	--set-package="gengetopt" \
	--set-version="" > help_output.texi

gengetopt --input=cmdline.ggo --no-handle-version \
	--no-handle-help --no-handle-error

$ ./gengetopt --zzzz
./gengetopt: unrecognized option `--zzzz'
Run gengetopt --help to see the list of options.

> ls --width=80

> ls --width 80

> ls -a -l
> ls -l -a

> cp --archive source dest

> cp --archive --verbose source dest
> cp --verbose --archive source dest
> cp --archive source --verbose dest
> cp --archive --verbose dest source

> ls -- -file
> tar -c -f - . > ../foo.tar

> ls -a -l -t --width=80

> ls -alt --width=80

> ls --all -fs

> ls --width 60  # ok, value is "60"
> ls --width=60  # ok, value is "60"
> ls -w60        # ok, value is "60"
> ls -w 60       # ok, value is "60"
> ls -w=60       # unexpected, value is "=60"
> ls -T7 -w60    # ok, value for -T is 7, value for -w is 60
> ls -T7w60      # unexpected, value for -T is "7w60", no -w at all

option "myopt" ... ... values="FOO","180","BAR" enum ...

enum enum_myopt {
myopt__NULL = -1, myopt_arg_FOO = 0, myopt_arg_180, myopt_arg_BAR };

option "myopt" ... ... values="+foo","-all","-foo" enum ...

enum enum_myopt { myopt__NULL = -1,
	myopt_arg_PLUS_foo = 0,
	myopt_arg_MINUS_all, myopt_arg_MINUS_foo };

defgroup "<group name>" {groupdesc="<group description>"} {required}
groupoption <long> <short> "<desc>" <argtype> group="<group name>" \
	{argoptional} {multiple}

defgroup "my grp2"
defgroup "grp1" groupdesc="an option of this group is required" required
groupoption "opta" a "string a" group="grp1" multiple
groupoption "optA" A "string A" string group="grp1" argoptional
groupoption "optAmul" M "string M" string group="grp1" argoptional multiple
groupoption "optb" b "string b" group="grp1"
groupoption "optc" - "string c" group="my grp2"
groupoption "optd" d "string d" group="my grp2"

$ ./test_groups
test_groups: 0 options of group grp1 were given. One is required
$ ./test_groups -a          OK
$ ./test_groups -a -a       OK (the same option given twice)
$ ./test_groups -a -b
test_groups: 2 options of group grp1 were given. One is required
$ ./test_groups -a -c       OK
$ ./test_groups -a --optc -d
test_groups: 2 options of group my grp2 were given. At most one is required

defmode "<mode name>" {modedesc="<mode description>"}
modeoption <long> <short> "<desc>" <argtype> mode="<mode name>" \
	{argoptional} {multiple} {required}

package "test_modes"
version "1.0"

section "some non mode options"

option "no-mode" N "a generic option not beloging to any mode" optional
option "no-mode2" - "another generic option not beloging to any mode" string optional

section "some modes just for testing"

defmode "mode 2"
defmode "my mode"
defmode "mode1" modedesc="any option of this mode is in contrast with any \
option of the other mode\nNotice that this description is quite long so \
it may spawn many lines...              \
fortunately gengetopt will wrap it for you :-)"

modeoption "opta" a "string a" multiple mode="mode1" optional
modeoption "optA" A "string A" string argoptional mode="mode1" required
modeoption "optAmul" M "string M" 
        argoptional string mode="mode1" multiple optional
modeoption "optb" b "string b" mode="mode1" optional

modeoption "optc" - "string c" mode="mode 2" optional
modeoption "optd" d "string d" mode="mode 2" required

modeoption "mopt" m "option of my mode" int optional mode="my mode" optional

test_modes -N

test_modes -a
./test_modes: '--optA' ('-A') option required

test_modes -a -A -N

test_modes -a -A -N --optc
test_modes: option --optc conflicts with option --opta
test_modes: option --optc conflicts with option --optA
test_modes: '--optd' ('-d') option required

test_modes 1.0

Usage: test_modes [-h|--help] [-V|--version] [-N|--no-mode] [--no-mode2=STRING]
  or : test_modes -d|--optd [--optc]
  or : test_modes -ASTRING|--optA=STRING [-a|--opta]
         [-MSTRING|--optAmul=STRING] [-b|--optb]
  or : test_modes [-mINT|--mopt=INT]

  -h, --help              Print help and exit
  -V, --version           Print version and exit

some non mode options:
  -N, --no-mode           a generic option not beloging to any mode
      --no-mode2=STRING   another generic option not beloging to any mode

some modes just for testing:

 Mode: mode1
  any option of this mode is in contrast with any option of the other mode
  Notice that this description is quite long so it may spawn many lines...
  fortunately gengetopt will wrap it for you :-)
  -a, --opta              string a
  -A, --optA[=STRING]     string A
  -M, --optAmul[=STRING]  string M
  -b, --optb              string b

 Mode: mode 2
      --optc              string c
  -d, --optd              string d

 Mode: my mode
  -m, --mopt=INT          option of my mode

int
<cmd_parser_name>_config_file(char * const filename,
	struct gengetopt_args_info *args_info,
	struct <cmd_parser_name>_params *params);

int
<cmd_parser_name>_ext (int argc,
	char **argv,
	struct gengetopt_args_info *args_info,
	struct <cmd_parser_name>_params *params);

int
<cmd_parser_name>_required (struct gengetopt_args_info *args_info,
	const char *program_name);

<option_name> = {<option_val>}

<option_name>

include "filename"

/* test_conf_parser.c test */

/* test all kinds of options and the conf file parser */

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <stdlib.h>
#include <stdio.h>

#include "test_conf_parser_cmd.h"

static struct my_args_info args_info;

int
main (int argc, char **argv)
{  
  unsigned int i;
  int result = 0;

  struct test_conf_parser_cmd_parser_params *params;

  /* initialize the parameters structure */
  params = test_conf_parser_cmd_parser_params_create();

  /* call the command line parser */
  if (test_conf_parser_cmd_parser (argc, argv, &args_info) != 0) {
    result = 1;
    goto stop;
  }

  /* 
     override command line options,
     but do not initialize args_info, check for required options.
     NOTICE: we must NOT skip the 0 assignment to initialize,
     since its default value is 1 and override defaults to 0
     while check_required is already set to its default value, 1
  */
  params->initialize = 0;
  params->override = 1;

  /* call the config file parser */
  if (test_conf_parser_cmd_parser_config_file
      (args_info.conf_file_arg, &args_info, params) != 0) 
    {
      result = 1;
      goto stop;
    }

  printf ("value of required: %s\n", args_info.required_arg);
  printf ("value of string: %s\n", args_info.string_arg);
  printf ("value of no-short_given: %d\n", args_info.no_short_given);
  printf ("value of int: %d\n", args_info.int_arg);
  printf ("value of float: %f\n", args_info.float_arg);

  printf ("value of multi-string_given: %d\n", args_info.multi_string_given);
  for (i = 0; i < args_info.multi_string_given; i++)
    printf ("  value of multi-string: %s\n", args_info.multi_string_arg [i]);

  printf ("value of multi-string-def_given: %d\n",
          args_info.multi_string_def_given);
  for (i = 0; i < args_info.multi_string_def_given; ++i)
    printf ("  value of multi-string-def: %s\n",
            args_info.multi_string_def_arg [i]);
  if (!args_info.multi_string_def_given && args_info.multi_string_def_arg [0])
    printf ("default value of multi-string-def: %s\n",
            args_info.multi_string_def_arg [0]);

  printf ("value of opta: %s\n", args_info.opta_arg);

  printf ("noarg given %d times\n", args_info.noarg_given);
  printf ("noarg_noshort given %d times\n", args_info.noarg_noshort_given);

  printf ("opt-arg given: %d\n", args_info.opt_arg_given);
  printf ("opt-arg value: %s\n", (args_info.opt_arg_arg ? args_info.opt_arg_arg : "not given"));

  if (args_info.file_save_given) {
    if (test_conf_parser_cmd_parser_file_save (args_info.file_save_arg, &args_info) == EXIT_FAILURE)
      result = 1;
    else
      printf ("saved configuration file %s\n", args_info.file_save_arg);
  }

 stop:
  /* deallocate structures */
  test_conf_parser_cmd_parser_free (&args_info);
  free (params);

  return result;
}

# required option
required "this is a test"
float 3.14
no-short
string another

./test_conf_parser -r bar -i 100 --float 2.14 --conf-file test_conf.conf
value of required: this is a test
value of string: another
value of no-short: 1
value of int: 100
value of float: 3.140000

value of required: bar
value of string: another
value of no-short: 1
value of int: 100
value of float: 2.140000

/* test_conf_parser_ov2.c test */

/* test all kinds of options and the conf file parser */
/* differently from test_conf_parser_ov.c, first scan the conf file and
   then the command line */

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <stdlib.h>
#include <stdio.h>

#include "test_conf_parser_cmd.h"

static struct my_args_info args_info;

int
main (int argc, char **argv)
{
  struct test_conf_parser_cmd_parser_params *params;

  /* initialize the parameters structure */
  params = test_conf_parser_cmd_parser_params_create();

  /* 
     initialize args_info, but don't check for required options
     NOTICE: the other fields are initialized to their default values
  */
  params->check_required = 0;

  /* call the config file parser */
  if (test_conf_parser_cmd_parser_config_file
      ("../../tests/test_conf2.conf", &args_info, params) != 0)
    exit(1);

  /* 
     override config file options,
     do not initialize args_info, check for required options.
  */
  params->initialize = 0;
  params->override = 1;
  params->check_required = 1;

  /* call the command line parser */
  if (test_conf_parser_cmd_parser_ext (argc, argv, &args_info, params) != 0)
    exit(1) ;

  printf ("value of required: %s\n", args_info.required_arg);
  printf ("value of string: %s\n", args_info.string_arg);
  printf ("value of no-short_given: %d\n", args_info.no_short_given);
  printf ("value of int: %d\n", args_info.int_arg);
  printf ("value of float: %f\n", args_info.float_arg);

  /* release memory */
  test_conf_parser_cmd_parser_free (&args_info);
  free (params);

  return 0;
}

./test_conf_parser_ov2 -r "bar" --float 2.14 -i 100
value of required: bar
value of string: another
value of no-short: 1
value of int: 100
value of float: 2.140000

./test_conf_parser_ov4 -r "bar" -i 100
./test_conf_parser_ov4: `--required' (`-r') option given more than once

# test options that can be given more than once
option "string"      s "string option" string optional multiple
option "int"         i "int option" int optional multiple

/* test options that can be given more than once */

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <stdlib.h>
#include <stdio.h>

#include "test_multiple_cmd.h"

static struct gengetopt_args_info args_info;

int
main (int argc, char **argv)
{ 
  int i = 0;

  if (test_multiple_cmd_parser (argc, argv, &args_info) != 0)
    exit(1) ;

  for (i = 0; i < args_info.string_given; ++i)
    printf ("passed string: %s\n", args_info.string_arg[i]);

  for (i = 0; i < args_info.int_given; ++i)
    printf ("passed int: %d\n", args_info.int_arg[i]);

  return 0;
}

./multiple_example -s world -s hellow -s bar -s foo -i 200 -i 100

passed string: world
passed string: hello
passed string: bar
passed string: foo
passed int: 200
passed int: 100

./test_multiple -s"foo","bar","hello" -i100,200 -s "world"

option "string"      s "string option" string optional multiple(4)

option "string"      s "string option" string optional multiple(1-4)

option "string"      s "string option" string optional multiple(-5)

int <parser_name>_string (const char *cmdline,
	struct test_first_cmdline_cmd_struct *args_info,
	const char *prog_name);
int <parser_name>_string_ext (const char *cmdline,
	struct test_first_cmdline_cmd_struct *args_info,
	const char *prog_name,
	struct <cmd_parser_name>_params *params);

# test for multiple parsers, this is the main file
# test_main_cmdline_cmd.ggo

option "first-cmd" F "the first command line to parse" required \
	typestr="first command" string multiple
option "second-cmd" S "the second command line to parse" required \
	typestr="second command" string multiple

# test for multiple parsers, this is the first command line file
# test_first_cmdline_cmd.ggostr

option "option-a" a "option a of the first command line to parse"
optional int option "multi" M \
	"multiple option of the first command line to parse" \
	optional string multiple

# test for multiple parsers, this is the second command line file
# test_second_cmdline_cmd.ggostr

option "option-a" a "option a of the second command line to parse" \
	optional string
option "option-b" b "option a of the second command line to parse" \
	optional string
option "my-multi" M \
	"multiple option of the second command line to parse" \
	optional string multiple

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <stdio.h>
#include <stdlib.h>

#include "test_main_cmdline_cmd.h"
#include "test_first_cmdline_cmd.h"
#include "test_second_cmdline_cmd.h"

int
main(int argc, char **argv)
{
  struct gengetopt_args_info main_args_info;
  struct test_first_cmdline_cmd_struct first_args_info;
  struct test_second_cmdline_cmd_struct second_args_info;
  int exit_code = 0;
  unsigned int i, j;

  if (test_main_cmdline_cmd_parser (argc, argv, &main_args_info) != 0) {
    exit_code = 1;
    return exit_code;
  }

  for (j = 0; j < main_args_info.second_cmd_given; ++j) {
    printf("second cmdline: %s\n", main_args_info.second_cmd_arg[j]);
    if (test_second_cmdline_cmd_parser_string 
	(main_args_info.second_cmd_arg[j], &second_args_info, argv[0]) == 0) {
      if (second_args_info.option_a_given)
	printf("  --option-a: %s\n", second_args_info.option_a_arg);
      if (second_args_info.option_b_given)
	printf("  --option-b: %s\n", second_args_info.option_b_arg);
      for (i = 0; i < second_args_info.my_multi_given; ++i)
	printf("  --my-multi: %s\n", second_args_info.my_multi_arg[i]);

      test_second_cmdline_cmd_parser_free (&second_args_info);
    }
  }

  for (j = 0; j < main_args_info.first_cmd_given; ++j) {
    printf("first cmdline: %s\n", main_args_info.first_cmd_arg[j]);
    if (test_first_cmdline_cmd_parser_string 
	(main_args_info.first_cmd_arg[j], &first_args_info, argv[0]) == 0) {
      if (first_args_info.option_a_given)
	printf("  --option-a: %d\n", first_args_info.option_a_arg);
      for (i = 0; i < first_args_info.multi_given; ++i)
	printf("  --multi: %s\n", first_args_info.multi_arg[i]);

      test_first_cmdline_cmd_parser_free (&first_args_info);
    }
  }

  test_main_cmdline_cmd_parser_free (&main_args_info);

  return exit_code;
}

./test_multiple_parsers \
	--first-cmd="-M400 -a10 --multi 100\,200\,300" \
	--second-cmd="-a20 -b10 --my-multi=a\,b\,c\,d\,e\,f" \
	-F"-M500 -M600" -S"--my-multi g"
second cmdline: -a20 -b10 --my-multi=a,b,c,d,e,f
	--option-a: 20
	--option-b: 10
	--my-multi: a
	--my-multi: b
	--my-multi: c
	--my-multi: d
	--my-multi: e
	--my-multi: f
second cmdline: --my-multi g
	--my-multi: g
first cmdline: -M400 -a10 --multi 100,200,300
	--option-a: 10
	--multi: 400
	--multi: 100
	--multi: 200
	--multi: 300
first cmdline: -M500 -M600
	--multi: 500
	--multi: 600

gnulib-tool --import getopt

ACLOCAL_AMFLAGS = -I gl/m4

...
AC_PROG_CC
gl_EARLY
...

...
# For gnulib.
gl_INIT
...

AC_CONFIG_FILES(... gl/Makefile ...)

SUBDIRS = gl

...
AM_CPPFLAGS = -I$(top_srcdir)/gl -I$(top_builddir)/gl
...
LDADD = gl/libgnu.a
...

gnulib-tool --update

foo_LDADD = @LIBOBJS@

EXTRA_DIST = gnugetopt.h

• Audience		What is gengetopt and who it is for.
• Copying		Your rights.
• Installation		Download and Installation
• Basic Usage		How to run Gengetopt; syntax of .ggo files
• Invoking gengetopt		gengetopt command line options
• Terminology		Definitions of options, values, and so forth.
• Options with enumerated values		Options accepting only a list of values
• Group options		Groups of mutually exclusive options
• Mode options		Mutually exclusive group of options
• Parser function additional parameters		Customizing invocation of the generated parser
• Configuration files		Parsing a configuration file
• Multiple Options		Multiple options
• String Parsers and Multiple Parsers		Using multiple parsers in the same program
• No getopt_long		What if getopt_long is not available?
• Bugs		What is lame and/or buggy in Gengetopt 2.23
• Mailing Lists		For discussions and announces
• Index		Index.

	Index Entry	Section

-
	`--arg-struct-name`:	Invoking gengetopt
	`--conf-parser`:	Invoking gengetopt
	`--default-optional`:	Basic Usage
	`--default-optional`:	Invoking gengetopt
	`--detailed-help`:	Basic Usage
	`--detailed-help`:	Basic Usage
	`--detailed-help`:	Basic Usage
	`--full-help`:	Basic Usage
	`--full-help`:	Basic Usage
	`--full-help`:	Basic Usage
	`--func-name`:	Invoking gengetopt
	`--gen-version`:	Invoking gengetopt
	`--header-output-dir`:	Invoking gengetopt
	`--include-getopt`:	Invoking gengetopt
	`--include-getopt`:	Include the getopt_long code into the parser
	`--long-help`:	Invoking gengetopt
	`--no-handle-error`:	Invoking gengetopt
	`--no-handle-help`:	Invoking gengetopt
	`--no-handle-version`:	Invoking gengetopt
	`--no-help`:	Invoking gengetopt
	`--no-version`:	Invoking gengetopt
	`--output-dir`:	Invoking gengetopt
	`--show-full-help`:	Invoking gengetopt
	`--show-help`:	Invoking gengetopt
	`--show-required`:	Invoking gengetopt
	`--show-version`:	Invoking gengetopt
	`--src-output-dir`:	Invoking gengetopt
	`--string-parser`:	Invoking gengetopt
	`--unnamed-opts`:	Invoking gengetopt
	`-C,--conf-parser`:	Configuration files
	`-h,--detailed-help`:	Basic Usage
	`-h,--help`:	Basic Usage
	`-h,--help`:	Basic Usage
	`-S,--string-parser`:	String Parsers and Multiple Parsers
	`-V,--version`:	Basic Usage

<
	<cmd_parser_name>_config_file:	Configuration files
	<cmd_parser_name>_ext:	Configuration files
	<cmd_parser_name>_required:	Configuration files

A
	argoptional:	Basic Usage
	args:	Basic Usage
	argtype:	Basic Usage
	argument, defined:	Terminology
	argv:	Basic Usage
	Audience:	Audience
	autoconf:	Installation
	autoconf:	Installation
	autoconf:	Use automake/autoconf
	autoconf:	Use getopt_long sources
	automake:	Installation
	automake:	Installation
	automake:	Use automake/autoconf
	automake:	Use getopt_long sources

C
	check_ambiguity:	Parser function additional parameters
	check_required:	Parser function additional parameters
	Conditions for copying Gengetopt:	Copying
	configuration files:	Configuration files
	Copying conditions:	Copying

D
	default:	Basic Usage
	dependon:	Basic Usage
	desc:	Basic Usage
	description:	Basic Usage
	details:	Basic Usage
	details:	Basic Usage
	details:	Basic Usage
	download:	Installation
	download:	Installation

E
	enum:	Options with enumerated values
	enumerated options:	Options with enumerated values

G
	gengetopt options:	Invoking gengetopt
	getopt_long:	No getopt_long
	getting started with Gengetopt:	Basic Usage
	Git:	Installation
	gnulib:	Installation
	gnulib:	Use Gnulib
	group options:	Group options

H
	hidden:	Basic Usage
	hidden:	Basic Usage
	how to use Gengetopt:	Basic Usage

I
	include:	Configuration files
	initialize:	Parser function additional parameters
	installation:	Installation
	invoking:	Invoking gengetopt

K
	Known Bugs:	Bugs

L
	libtool:	Installation
	libtool:	Installation
	Limits:	Bugs
	long:	Basic Usage
	long option, defined:	Terminology

M
	mailing list:	Mailing Lists
	Misfeatures:	Bugs
	mode options:	Mode options
	multiple:	Basic Usage
	multiple option, defined:	Terminology
	multiple options:	Multiple Options
	multiple parsers:	String Parsers and Multiple Parsers

O
	on/off:	Basic Usage
	option without name:	Basic Usage
	option, defined:	Terminology
	optional:	Basic Usage
	override:	Parser function additional parameters

P
	PACKAGE:	Audience
	package:	Basic Usage
	PACKAGE:	Basic Usage
	PACKAGE_NAME:	Audience
	PACKAGE_NAME:	Basic Usage
	parameter:	Basic Usage
	parameter, defined:	Terminology
	parameters:	Parser function additional parameters
	parser parameters:	Parser function additional parameters
	print_errors:	Parser function additional parameters
	purpose:	Basic Usage

R
	required:	Basic Usage
	required option, defined:	Terminology
	requirements:	Installation

S
	section:	Basic Usage
	short:	Basic Usage
	short option, defined:	Terminology
	string parsers:	String Parsers and Multiple Parsers

T
	Terminology:	Terminology
	text:	Basic Usage
	tutorial:	Basic Usage
	typestr:	Basic Usage

U
	usage:	Basic Usage

V
	value, defined:	Terminology
	values:	Basic Usage
	values:	Options with enumerated values
	VERSION:	Audience
	version:	Basic Usage
	VERSION:	Basic Usage
	versiontext:	Basic Usage

W
	Who should use Gengetopt:	Audience
	wrapping:	Basic Usage
	wrapping:	Basic Usage

• Include the getopt_long code into the parser
• Use automake/autoconf

GNU Gengetopt 2.23

Table of Contents

Gengetopt

Audience

Gengetopt Copying Conditions

1 Installation

1.1 Download

1.2 Anonymous Git Checkout

1.3 What you need to build gengetopt

2 Basic Usage

3 Invoking gengetopt

4 Terminology

5 Options with enumerated values

6 Group options

7 Mode options

8 Parser function additional parameters

9 Configuration files

9.1 Further details on the configuration file parser

10 Multiple Options

11 String Parsers and Multiple Parsers

12 What if getopt_long is not available?

12.1 Include the getopt_long code into the generated parser

12.2 Use automake/autoconf to check for the existence of getopt_long

12.2.1 Use Gnulib

12.2.2 Use getopt_long sources

13 Known Bugs and Limitations

13.1 Getopt and subsequent calls

14 Mailing Lists

Index

Footnotes

12.1 Include the `getopt_long` code into the generated parser

12.2 Use automake/autoconf to check for the existence of `getopt_long`