This program generates a C function that uses getopt_long function to parse the command line options, to validate them and fills a struct .
Thus your program can now handle options such as:
myprog --input foo.c -o foo.o --no-tabs -i 100 *.classAnd both long options (those that start with --) and short options (start with - and consist of only one character) can be handled. For standards about short and long options you may want to take a look at the GNU Coding Standards .
gengetopt is free software.
Please see the file LICENSE and COPYING
for details.
Notice that: Use of gengetopt does not impose any particular
license on the generated code: the code generated is not under any
license.
For documentation, please read this file.
gengetopt is perfect if you are too lazy (like me) to write all
stuff required to call getopt_long, and when you have a
program and wish it took options.
Generated code works if you use GNU Autoconf or GNU Automake .
Gengetopt has originally been written by Roberto Arturo Tena Sanchez and currently maintained by Lorenzo Bettini http://www.lorenzobettini.it.
Gengetopt is a GNU program and its
main home page is at GNU site:
http://www.gnu.org/software/gengetopt/gengetopt.html
I do not distribute Windows binaries anymore; since, they can be easily built by using Cygnus C/C++ compiler, available at http://www.cygwin.com/. However, if you don't feel like downloading such compiler, you can request such binaries directly to me, by e-mail (please find my e-mail address at my home page) and I can send them to you.
You may also want to check the md5sum of the archives, which are also digitally signed by me (Lorenzo Bettini) with GNU gpg (http://www.gnupg.org). My GPG public key can be found at my home page (see at the end of this doc).
You can also get the patches, if they are available for a particular release (see below for patching from a previous version).
cvs -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/gengetopt login
cvs -z3 -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/gengetopt co gengetoptFurther instructions can be found at the address: http://savannah.gnu.org/projects/gengetopt .
cd <source code main directory>Note: unless you specify a different install directory by --prefix option of configure (e.g. ./configure --prefix=<your home> ), you must be root to 'make install'.
./configure
make
make install
You can also run some tests by issuing 'make check'.
Files will be installed in the following directories:
getopt_long function is usually in the standard C library, but there may be some C libraries which don't include it; in this case you have to link the program that uses the file generated by gengetopt with the files getopt.c and getopt1.c and include getopt.h in your project. You may also need to link alloca.c.We obviously provide these files in the utility files directory (/prefix/share/gengetopt). These files are part of the GNU C library. You may want to take a look at getopt man page. Read also no_getopt_long.txt. for instuctions on how to check if getopt_long and alloca are part of the library and how to deal with their lacking (using autoconf and automake).
gengetopt has been developed under Linux, using gcc, and bison (yacc) and flex (lex), and ported under Windows with Cygnus C/C++ compiler, available at http://www.cygwin.com/. I used the excellent GNU Autoconf and Automake. I also used Autotools (ftp://ftp.ugcs.caltech.edu/pub/elef/autotools ) which creates a starting source tree (according to GNU standards) with autoconf, automake starting files, and getopt_long (for command line parsing). Moreover Gengen (http://www.lorenzobettini.it/software/gengen/ ) is used for automatically generating the code that generates the command line parser.
Actually, unless you want to develop gengetopt, you don't need all these tools to build gengetopt because I provide generated sources; you don't need neither bison (yacc) nor flex (lex), for the same reason. Actually programs that use lex generated files need to link with library libfl(or libl for lex); anyway configuration phase can discover if this library is missing and in that case it sets the program to link with a source file I provide. This hack works for flex: I don't know about lex generated scanners. But, again, this is a problem only if you develop gengetopt and you use lex.
Should you want to act on the generated code you may want to download Gengen that speeds up this part (http://www.lorenzobettini.it/software/gengen/ ).
gunzip -cd ../gengetopt-1.3-1.3.1.patch.gz | patch -p1and restart the compilation process (if you had already run configure a simple make will do).
package <packname>Where:
version <version>
option <long> <short> <desc> {argtype} {typestr="<type descr>"} {default="<default value>"} {required} {argoptional} {multiple}
option <long> <short> <desc> flag <onoff>
package
Double quoted string. This has the precedence over PACKAGE generated by autoconf.version
Double quoted string. This has the precedence over VERSION generated by autoconf.purpose
What the program does (even on more than one line), it will be printed with the help. Double quoted string.long
The long option, a double quoted string with upper and lower case chars, digits, '-' and '.'. No spaces allowed. The name of the variables generated to store arguments are long options converted to be legal C variable names. This means, '.' and '-' are both replaced by '_'. '_arg' is appended, or '_flag' for a flag.short
The short option, a single upper or lower case char, or a digit. If a '-' is specified, then no short option is considered for the long option (thus long options with no associated short options are allowed).desc
Double quoted string with upper and lower case chars, digits, '-', '.' and spaces. First character must not be a space. This description will be printed during the output of --help. Wrapping will be automatically performed, and \n is interpreted as a newline request.argtype
string, int, short, long, float, double, longdouble or longlong. If no type is specified the option does not accept an argument.typestr
a description for the type of the values for the option (e.g., "filename" instead of simply STRING, or "portnumber" instead of simply INT).default
an optional default value for the option. The value must always be specified as a double quoted string.required
yes or no.argoptional
If this flag is specified then this option has an argument that is optional. In this case, when you specify the argument at command line, please use = in case you use a long option, and avoid spaces if you use short option. For instance, if the option with optional argument is -B|--bar, use the following command line syntax: -B15 or --bar=15, and NOT the following one -B 15 nor --bar 15.
multiple
If this flag is specified then this option can be specified more than once at command line; all the values for this option are stored in an array. See multiple options in the Advanced Features section.onoff
on or off. This is the state of the flag when the program starts. If user specifies the option, the flag toggles.
Comments begins with '#' in any place of the line and ends in
the end of line.
Options can be part of sections,
that provide a more meaningful descriptions of the options. A
section can be defined with the following syntax and all the options
following a section declaration are considered part of that sections:
section "section name"
Here's an example of such a file (the file is called sample1.ggo)
# file sample1.ggo option "str-opt" s "A string option, for a filename" string typestr="filename" no 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 no option "int-opt" i "A int option" int yes section "more involved options" option "flag-opt" - "A flag option" flag off option "funct-opt" F "A function option" no section "last option section" option "long-opt" - "A long option" long no option "def-opt" - "A string option with default" string default="Hello" no |
The simplest way to use gengetopt is to pass this file as the standard input, i.e.:
gengetopt < sample1.ggoby default gengetopt generates cmdline.h and cmdline.c . Otherwise we can specify these names with a command line option:
gengetopt < sample1.ggo --file-name=cmdline1 --unamed-optsThe option --unamed-opts allows the generated command line parser to accept also names, without an option (for instance you can pass a file name without an option in front of it, and also use wildcards, such as *.c, foo*.? and so on). You can specify an optional description for these additional names (default is 'FILES').
In cmdline1.h you'll find the generated C struct:
|
The <option>_given
field is set to non 0 when an argument for <option> has been
specified. Even if <option>_given is 0, the corresponding
<option>_arg is set
to default value (if one has been specified for <option>).
Notice that by default the generated function is called cmdline_parser (see the command line options below, to override this name), and it takes the arguments that main receives and a pointer to such a struct, that it will be filled.
cmdline_parser_free
can be called to deallocate memory allocated by the parser for string
and multiple options.
cmdline_parser_init can be called to initialize the struct (it is not mandatory, since it is done automatically by the command line parser).
And here's how this function can be used inside the main program:
/* main1.cc */ |
Now you can compile main1.cc and the cmdline1.c generated by gengetopt and link all together to obtain sample1 executable:
gcc -c cmdline1.c(Here we assume that getopt_long is included in the standard C library; see 'What you need to build gengetopt' section).
g++ -c main1.cc
g++ -o sample1 cmdline1.o main1.o
Now let's try some tests with this program:
$ ./sample1 -s "hello" --int-opt 1234You can also pass many file names to the command line (this also shows how flags work):
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 -xAnd if we try to omit the --int-opt (or -i), which is required, we get an error:
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! :-)
$ ./sample1Here is the output of --help:
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 2.0Notice how filename is printed instead of STRING for the option --str-opt (since typestr was used in the .ggo file) and how the description of --my-opt is wrapped to 80 columns, and how the \n is actually interpreted as a newline request.
Usage: sample1 -iINT|--int-opt=INT [-h|--help] [-V|--version]
-sfilename|--str-opt=filename -mINT|--my-opt=INT [--flag-opt]
[-F|--funct-opt] --long-opt=LONG --def-opt=STRING [FILES]...
-h, --help Print help and exit
-V, --version Print version and exit
-s, --str-opt=filename A string option, for a filename
-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
more involved options:
--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')
You may find other examples in /prefix/share/doc/gengetopt.
defgroup "<group name>" {groupdesc="<group description>"} {yes}If a group is defined as required, then one (but only one) option belonging to the group has to be specified.
groupoption <long> <short> <desc> <argtype> group="<group name>"
defgroup "my grp2"The group grp1 is required, so either opta or optb has to be specified (but only one of them). Here's the output of some executions:
defgroup "grp1" groupdesc="an option of this group is required" yes
groupoption "opta" a "string a" group="grp1"
groupoption "optb" b "string b" group="grp1"
groupoption "optc" - "string c" group="my grp2"
groupoption "optd" d "string d" group="my grp2"
$ ./test_groups
gengetopt: 0 options of group grp1 were given. One is required
$ ./test_groups -a OK
$ ./test_groups -a -b
gengetopt: 2 options of group grp1 were given. One is required
$ ./test_groups -a -c OK
$ ./test_groups -a --optc -d
gengetopt: 2 options of group my grp2 were given. At most one is required
intoverride tells whether the values read in the configuration file have to override those specified at the command line.
<cmd_parser_name>_configfile (char * const filename,
struct gengetopt_args_info *args_info,
int override,
int initialize,
int check_required);
intNotice, that with this version you can also specify whether the options passed at the command line must override the ones read from the config file. If you set override to 0, and a command line option is given that has already been read from the config file, an error will be raised. Moreover, you have to specify whether the check for missing required options must be performed or not.
<cmd_parser_name>2 (int argc,
char * const *argv,
struct gengetopt_args_info *args_info,
int override,
int initialize,
int check_required);
|
# required optionand we run test_conf_parser like that we will have
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
If, instead we call the test_conf_parser_cmd_parser_configfile with
0 for override argument, we get the following result
value of required: barThis second example use the second version of the command line parser: first call the configuration file parser and then the command line parser (the command line options will override the configuration file options):
value of string: another
value of no-short: 1
value of int: 100
value of float: 2.140000
|
./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 options that can be given more than once
option "int" i "int option" int no multiple |
|
./test_multiple -s "foo" -s "bar" -s "hello" -i 100 -i 200 -s "world"The output of the program will be
passed string: world
passed string: hello
passed string: bar
passed string: foo
passed int: 200
passed int: 100
You can also pass arguments to a multiple option separated by
commas, as in the following:
./test_multiple -s"foo","bar","hello" -i100,200 -s "world"
$ gengetopt --helpThe options should be clear; in particular:
gengetopt 2.12.1
Purpose:
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 [OPTIONS]...
-h, --help Print help and exit
-V, --version Print version and exit
-i, --input=filename input file (default std input)
-f, --func-name=name name of generated function (default=
`cmdline_parser')
--arg-struct-name=name name of generated args info struct (default=
`gengetopt_args_info')
-F, --file-name=name name of generated file (default=`cmdline')
--c-extension=ext extension of c file (default=`c')
--header-extension=ext extension of header file (default=`h')
-l, --long-help long usage line in help
-u, --unamed-opts[=STRING] accept options without names (e.g., file names)
(default=`FILES')
--no-handle-help do not handle --help|-h automatically
--no-handle-version do not handle --version|-V automatically
--no-handle-error do not exit on errors
--gen-version put gengetopt version in the generated file
(default=on)
--conf-parser generate a config file parser
purpose "This program generates a C function that uses getopt_long function option "input" i "input file (default std input)" string typestr="filename" no |
In particular the command line for gengetopt itself is generated with the following command:
gengetopt --input=cmdline.ggo --no-handle-version --no-handle-help --no-handle-errorIndeed when --help|-h is passed on the command line, gengetopt will call cmdline_parser_print_help() and then the lines for reporting bugs. When --version|-V is passed, it will call cmdline_parser_print_version() and then prints a copyright.
$ ./gengetopt --zzzz
./gengetopt: unrecognized option `--zzzz'
Run gengetopt --help to see the list of options.
Actually we want to extend it, so if you have some ideas... The most import one will be to make gengetopt more customizable :-)
Please send all bug reports by electronic mail to: bug-gengetopt at gnu dot org
Lorenzo Bettini http://www.lorenzobettini.it |
Roberto Arturo Tena Sanchez http://arturo.directmail.org |
gengetopt is free software. See the file LICENSE and COPYING for copying conditions. Anyway we won't get offended if you send us a postcard :-)
C/C++ files are formatted with GNU Source-highlight (http://www.gnu.org/software/src-highlite/ ) by Lorenzo Bettini.
Return to GNU's home page.
Please send FSF & GNU inquiries & questions to gnu@gnu.org . There are also other ways to contact the FSF.
Please send comments on these web pages to webmasters@gnu.org , send other questions to gnu@gnu.org .
Copyright (C) 2001 Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
Updated:9 Jan 2001 mhw