7.4 Quick Start

Since it is generally easier to start with a simple example than it is to look at the options that AutoGen uses itself, here is a very simple AutoOpts example. You can copy this example out of the Info file and into a source file to try it. You can then embellish it into what you really need. For more extensive examples, you can also examine the help output and option definitions for the commands columns, getdefs and autogen itself.

If you are looking for a more extensive example, you may search the autogen sources for files named ‘*opts.def’. xml2ag is ridiculous and autogen is very lengthy, but columns and getdefs are not too difficult. The sharutils sources are fairly reasonable, too.

7.4.1 Example option requirements

For our simple example, assume you have a program named check that takes two options:

1. A list of directories to check over for whatever it is check does. You want this option available as a POSIX-style flag option and a GNU long option. You want to allow as many of these as the user wishes.
2. An option to show or not show the definition tree being used. Only one occurrence is to be allowed, specifying one or the other.

7.4.2 Example option definitions

First, specify your program attributes and its options to AutoOpts, as with the following example.

AutoGen Definitions options;
prog-name     = check;
prog-title    = "Checkout Automated Options";
long-opts;
gnu-usage;    /* GNU style preferred to default */

main = { main-type = shell-process; };

flag = {
    name      = check-dirs;
    value     = L;        /* flag style option character */
    arg-type  = string;   /* option argument indication  */
    max       = NOLIMIT;  /* occurrence limit (none)     */
    stack-arg;            /* save opt args in a stack    */
    descrip   = "Checkout directory list";
    doc       = 'name of each directory that is to be "checked out".';
};

flag = {
    name      = show_defs;
    descrip   = "Show the definition tree";
    disable   = dont;     /* mark as enable/disable type */
                          /* option.  Disable as `dont-' */
    doc       = 'disable, if you do not want to see the tree.';
};

7.4.3 Build the example options

This program will produce a program that digests its options and writes the values as shell script code to stdout. Run the following short script to produce this program:

base=check
BASE=`echo $base | tr '[a-z-]' '[A-Z_]'`
cflags="-DTEST_${BASE} `autoopts-config cflags`"
ldflags="`autoopts-config ldflags`"
autogen ${base}.def
cc -o ${base} -g ${cflags} ${base}.c ${ldflags}
./${base} --help

7.4.4 Example option help text

Running the build commands yields:

exit 0

7.4.5 Using the example options

Normally, however, you would not use the main clause. Instead, the file would be named something like ‘checkopt.def’, you would compile ‘checkopt.c’ the usual way, and link the object with the rest of your program.

The options are processed by calling optionProcess (see section optionProcess):

main( int argc, char** argv )
{
  {
    int optct = optionProcess( &checkOptions, argc, argv );
    argc -= optct;
    argv += optct;
  }

The options are tested and used as in the following fragment. ENABLED_OPT is used instead of HAVE_OPT for the ‘--show-defs’ option because it is an enabled/disabled option type:

  if (  ENABLED_OPT( SHOW_DEFS )
     && HAVE_OPT( CHECK_DIRS )) {
    int    dirct = STACKCT_OPT( CHECK_DIRS );
    char** dirs  = STACKLST_OPT( CHECK_DIRS );
    while (dirct-- > 0) {
      char* dir = *dirs++;
      ...

7.4.6 Example option documentation

The doc clauses are used in the flag stanzas for man pages and texinfo invoking documentation. With the definition file described above, the two following commands will produce the two documentation files ‘check.1’ and ‘invoke-check.texi’. The latter file will be generated as a chapter, rather than a section or subsection.

autogen -Tagman-cmd check.def
autogen -DLEVEL=chapter -Tagtexi-cmd -binvoke-check.texi check.def

The result of which is left as an exercise for the reader.

A lot of magic happens to make this happen. The rest of this chapter will describe the myriad of option attributes supported by AutoOpts. However, keep in mind that, in general, you won’t need much more than what was described in this "quick start" section.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.