GNU Gengetopt 2.1

September 20th, 2000

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 *.class

And 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 (new).
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:

   * Latest Version (sources, .tar.gz) - md5sum - signature of md5sum
   * Latest Version (win32 executable, zipped) - md5sum - signature of
     md5sum
   * Cygnus DLL for win32 (needed for win32 executable, zipped)

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).

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).

Changes in this release

   * It is made more clear that use of gengetopt does not impose any
     particular license on the generated code.
   * A bug in the generation of code (for some new C++ compilers) was fixed,
     thanks to "James R. Van Zandt" <jrv@vanzandt.mv.com>
   * Some modifications to the man page, also due to James.
   * a directory for examples is specifically created (suggested by James).

Changes in release 2.0

This is quite a totally new release:

   * Gengetopt has become GNU software
   * it is conform to GNU coding standards, and so it uses configure script
     generated by Automake and Autoconf
   * it generates separated files: one header file with the struct used to
     store command line options information, and a C file which contains the
     function which actually uses getopt_long to parse the command line
   * 'required' option is now fully implemented

see also NEWS file and ChangeLog for the complete list of changes between
versions.

Installation

See the file INSTALL for detailed building and installation instructions;
anyway if you're used to compiling Linux software that comes with sources
you may simply follow the usual procedure:

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

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'.

Files will be installed in the following directories:

   * Executables          -> /prefix/bin
   * docs                 -> /prefix/share/doc/gengetopt
   * examples             -> /prefix/share/doc/gengetopt/examples
   * util files           -> /prefix/share/gengetopt

Default value for prefix is /usr/local but you may change it with --prefix
option to configure (see above).

What you need to build gengetopt

Actually you need nothing more than a Unix C/C++ compiler

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.

Patching from a previous version

If you downloaded a pacth, say gengetopt-1.3-1.3.1-patch.gz (i.e. the pacth
to go from version 1.3 to version 1.3.1), cd to the directory with sources
from the previous version (gengetopt-1.3) and type:

gunzip -cd ../gengetopt-1.3-1.3.1.patch.gz | patch -p1

and restart the compilation process (if you had already run configure a
simple make will do).

Usage (a little tutorial)

The command line options, which have to be handled by gengetopt generated
function, are specified in a file (typically with .ggo extension). This file
consist in lines of sentences with the following formats:

package <packname>
version <version>

option <long> <short> <desc> <argtype> <required>
option <long> <short> <desc> flag      <onoff>
option <long> <short> <desc> no

Where:

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.

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.ggo

by 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

In cmdline1.h you'll find the generated C struct:

 /* cmdline1.h */

 /* File autogenerated by gengetopt version 2.1  */

 #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.

Warning for Win32 users

If you run Win32 version, please remember that DOS shell does not translate
wildcards, and thus the previous test which uses '*.h' will not work. Thus
also a 'make check' is destined to fail.

Options

This is the output of gengetopt --help:

$ gengetopt --help
gengetopt 2.1
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 filenames

The options should be clear; in particular:

   * if no --func-name is given, cmdline_parser is taken by default;
   * with --long-help option, the "Usage" line reports all the options; this
     may be unpleasant if options are many;
   * with --unamed-opts we can accept also options without a name, which, in
     most case, means that we can pass many file names to the program (see
     the example above when we call sample1 *.h).

You may have already guessed it: gengetopt uses gengetopt itself for command
line options, and this is its specification file:

  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

Credits

See THANKS file :-)

Feedback

Tell us if you like this software :-)

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

Mailing Lists

The following mailing lists are available:

   * help-gengetopt@gnu.org, for generic discussions about the program and
     for asking for help about it (open mailing list),
     http://mail.gnu.org/mailman/listinfo/help-gengetopt
   * info-gengetopt@gnu.org, for receiving information about new releases
     and features (read-only mailing list),
     http://mail.gnu.org/mailman/listinfo/info-gengetopt

if you want to subscribe to a mailing list just go to the URL and follow the
instructions.

 Lorenzo Bettini                      Roberto Arturo Tena Sanchez
 http://w3.newnet.it/bettini  or      http://arturo.directmail.org
 http://infostud.dsi.unifi.it/~bettini<arturo@directmail.org>,
 (very fast if you're in University)
 <bettini@gnu.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
  ------------------------------------------------------------------------
