`opt_util` - Option Scanning Utilities

The opt_util package handles full-word (possibly abbreviated) command-line options as well as single-letter options, and can also break a string into an argc/argv[] array of arguments. I've used this package on UNIX, VxWorks, VMS, Windows, Nintendo DS, Palm Pilot, ... The package also worked well with Tcl/Tk programs such as my gentle Tcl interpreter server; the Tcl interpreter passes a command's arguments in an argc/argv[] array to the C function that implements the command.

This package does not implement GNU-style dash-dash "long" options. Full-word options can already be abbreviated, so I haven't had a need for single-letter options myself. As far as being able to group together single-letter options, I've only found that useful, out of habit, with tar(1).

This file contains a package of functions used to scan and parse UNIX-style command line arguments. The OPT_UTIL utilities support:

single-letter options; e.g., "-a"
single-letter options expecting arguments; e.g., "-o file"
name options; e.g., "-readonly"
name options with arguments; e.g., "-list file"
redirection of standard input and output on systems that don't support it at the shell level; e.g., "> outputFile"

The scanning algorithm used by the OPT_UTIL functions allows name options to be abbreviated on the command line. For example, the "-list file" name option in (4) above can be entered on the command line as "-l file", "-li file", "-lis file", or "-list file". If the one-character abbreviation of a name conflicts with a single-letter option, the single-letter option takes priority.

The following command line

 % program -a -o objectFile -readonly -list file

would be scanned and parsed as follows using the OPT_UTIL package:

 #include "opt_util.h"			-- Option scanning definitions.
 char *argument ;
 int option ;
 opt_init (argc, argv, 0, "ao:{readonly}{object:}", NULL) ;
 while (option = opt_get (NULL, &argument)) {
 switch (option) {
 case 1: ... process "-a" option ...
 case 2: ... process "-o file" option argument ...
 case 3: ... process "-readonly" option ...
 case 4: ... process "-list file" option ...
 case NONOPT:
 ... process non-option argument ...
 case OPTERR:
 ... invalid option or missing argument ...
 }
 }

Applications that will scan multiple command lines using the same set of allowable options can cache the original scan context, resetting it for each new command line (represented by a new argc/argv[] set of arguments):

 static char *option_list[] = {		-- Command line options.
 "a", "o:", "{readonly}", "{object:}", NULL
 } ;
 static OptContext scan = NULL ;
 ...
 for (... each new argc/argv[] set of arguments ...) {
 if (scan == NULL) opt_init (argc, argv, 1, option_list, &scan) ;
 opt_reset (scan, argc, argv) ;
 while (option = opt_get (scan, &argument)) {
 ... process options ...
 }
 }

Note in the example above that the valid command line options are specified in list form rather than in-line.

VxWorks programs can use the OPT_UTIL functions to provide a simple command line invocation consistent between UNIX and VxWorks:

 % program option(s) ...		(UNIX)
 -> sp program, "option(s) ..."	(VxWorks)

The single options string under VxWorks has several advantages over separate positional arguments: (i) it's easier to type in, (ii) it's easier to extend with new options, and (iii) it's more portable. The following code fragment from a program called RPM shows how to declare a main routine expecting command line arguments under both UNIX and VxWorks:

 #ifdef VXWORKS
 int rpm (char *command_line)
 #else
 int main (int argc, char *argv[])
 #endif
 {
 ... local variable declarations ...
 #ifdef VXWORKS
 char **argv ;
 int argc ;
 opt_create_argv ("rpm", command_line, &argc, &argv) ;
 #endif
 ... call the other OPT_UTIL functions to parse the argc/argv[] array of arguments ...
 }