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

    }