This program generate a C function that uses getopt_long function to parse the command line options, validate them and fill 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.
For documentation, please read this file. As it is a GPL program, we
provide sources (~100k), but if you don't fell like compiling it, you can
download Win32 executable ().
The code generated is not under any license.
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 <arturo@directmail.org>, and currently maintained by Lorenzo Bettini <bettini@gnu.org>.
Gengetopt is a GNU program, so you
can download it from GNU's ftp site:
ftp://ftp.gnu.org/gnu/gengetopt/
or from here:
Gengetopt main home page is at GNU site:
http://www.gnu.org/software/gengetopt/gengetopt.html
or you can also get the pacthes (see below for patching from a previous version).
cd <source code main directory> ./configure make make installNote: 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'.
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. 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.
gengetopt has been developed under Linux, using gcc, and bison (yacc) and flex (lex), and ported under Win32 with Cygnus C/C++ compiler, available at http://www.cygnus.com/ (a .DLL is also distributed togheter with the .exe: you may simply copy it in the same place of the .exe). 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).
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.
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> version <version> option <long> <short> <desc> <argtype> <required> option <long> <short> <desc> flag <onoff> option <long> <short> <desc> noWhere:
packname
Double quoted string with upper and lower case chars, digits, '-' and '.'. No spaces allowed.version
Double quoted string with upper and lower case chars, digits, '-' and '.'. No spaces allowed.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.argtype
string, int, short, long, float, double, longdouble or longlong.required
yes or no.onoff
on or off. This is the state of the flag when the program starts. If user specifies the option, the flag toggles.The third type of option is used when the option does not take any argument. It must not be required.
Comments begins with '#' in any place of the line and ends in the end of line.
Here's an example of such a file (the file is called sample1.ggo)
| # file sample1.ggo
option "str-opt" s "A string option" string no option "int-opt" i "A int option" int yes option "funct-opt" F "A function option" no option "flag-opt" x "A flag option" flag off |
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=cmdline1In cmdline1.h you'll find the generated C struct:
/* cmdline1.h */
/* File autogenerated by gengetopt version 2.2 */
#ifndef _cmdline1_h
#define _cmdline1_h
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
struct gengetopt_args_info {
char * str_opt_arg; /* A string option. */
int int_opt_arg; /* A int option. */
int flag_opt_flag; /* A flag option (default=off). */
int help_given ; /* Wheter help was given. */
int version_given ; /* Wheter version was given. */
int str_opt_given ; /* Wheter str-opt was given. */
int int_opt_given ; /* Wheter int-opt was given. */
int funct_opt_given ; /* Wheter funct-opt was given. */
int flag_opt_given ; /* Wheter flag-opt was given. */
char **inputs ; /* unamed options */
unsigned inputs_num ; /* unamed options number */
} ;
int cmdline_parser (int argc, char **argv, struct gengetopt_args_info *args_info);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* _cmdline1_h */
|
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.
And here's how this function can be used inside the main program:
/* main1.cc */
/* we try to use gengetopt generated file in a C++ program */
/* we don't use autoconf and automake vars */
#include <iostream.h>
#include "cmdline1.h"
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;
cout << "The flag is " << ( args_info.flag_opt_flag ? "on" : "off" ) <<
"." << endl ;
cout << "Have a nice day! :-)" << endl ;
return 0;
}
|
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 g++ -c main1.cc g++ -o sample1 cmdline1.o main1.o(Here we assume that getopt_long is included in the standard C library; see 'What you need to build gengetopt' section).
Now let's try some tests with this program:
$ ./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! :-)You can also pass many file names to the command line (this also shows how flags work):
$ ./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! :-)And if we try to omit the --int-opt (or -i), which is required, we get an error:
$ ./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!If you're curious you may want to take a look at the generated C file.
You may find other examples in /prefix/share/doc/gengetopt.
$ gengetopt --help gengetopt 2.2 Usage: gengetopt [OPTIONS]... -h --help Print help and exit -V --version Print version and exit -iSTRING --input=STRING input file. default std input -fSTRING --func-name=STRING name of generated function -FSTRING --file-name=STRING name of generated file. default cmdline -l --long-help long usage line in help -u --unamed-opts accept filenamesThe options should be clear; in particular:
option "input" i "input file. default std input" string no option "func-name" f "name of generated function" string no option "file-name" F "name of generated file. default cmdline" string no option "long-help" l "long usage line in help" no option "unamed-opts" u "accept filenames" no |
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@gnu.org
| Lorenzo Bettini
http://w3.newnet.it/bettini or http://infostud.dsi.unifi.it/~bettini (very fast if you're in University) <bettini@gnu.org>. |
Roberto Arturo Tena Sanchez
http://arturo.directmail.org <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 cpp2html (http://www.gnu.org/software/cpp2html) 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@www.gnu.org, send other questions to gnu@gnu.org.
Copyright (C) 1999 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: 27 Mar 1999 jonas