opt command line parser

1. Nutshell		What is opt, in a nutshell?
2. Opt		What is opt, in a deeper philosophical sense?
3. Etc		What else?

 -- The Detailed Node Listing ---

Nutshell

1.1 What the user sees		How to use programs that use opt
1.2 What the programmer sees		How to write programs that use opt

Opt

2.1 Philosophical digression
2.2 What is Opt?
2.3 User Interface
2.4 Programmer Interface

What is Opt?

2.3 User Interface
2.4 Programmer Interface

User Interface

2.3.1 Direct command line options
2.3.2 Options from a named file
2.3.3 Environment strings
2.3.4 Rudimentary builtin menu
2.3.5 Standard usage messages

Programmer Interface

2.4.1 Example code
2.4.2 Registering options
2.4.3 Setting some strings
2.4.4 Registering functions (hooks)
2.4.5 Misc

Registering options

2.4.2.1 Delimited options
2.4.2.2 Positional options
2.4.2.3 Flexible options
2.4.2.4 Default values
2.4.2.5 Modifying option attributes
2.4.2.6 Registering array options
2.4.2.7 Registering options in C++
2.4.2.6 Registering array options

Etc

3.1 Installation
3.2 Adding opt to existing code: a recipe
3.3 So, you don't like global variables?
3.4 Single file
3.5 Extensions
3.6 Bugs
Warranty
Copying

1. Nutshell

opt is a subroutine library which facilitates the convenient input of parameters to a C program. Parameters are parsed from a command line, with further facilities for reading options from files, from environment strings, or from an interactive environment.

The aim of the opt package is to permit programs to be both user- and programmer- friendly. The package attempts to provide a direct and relatively full-featured input interface to the ultimate user of the program, and at the same time to impose a minimal amount of work on the programmer to "add" options parsing to existing software.

opt is similar in its effects to the standard UNIX (and also to the GNU) getopts packages, and I have tried (though possibly not as hard as I could have) to keep them as similar as possible whenever feasable. But opt does takes a somewhat different philosophy. Variables are "registered" to strings, and whenever the strings are used on the command line, the variables are updated accordingly. This tends to be a little more compact (and in my view more convenient) than the loop and case-statement approach used by getopt. Also, opt has a few more bells and whistles.

1.1 What the user sees		How to use programs that use opt
1.2 What the programmer sees		How to write programs that use opt

1.1 What the user sees

Code written with opt can read parameters from the command line; for example running the program

birthday -m 9 -d 11 -y1989 -v

can set paramters month=9, day=11, and year=1989, and also turn on the verbose flag, inside the birthday program. Note that the space between the single-character option name and the value is optional. Some parameters can also be set using long names, for instance:

birthday --month=9 --day 11 -y1989

Note that the `=' can only be used with the long form of the options, but it is optional and white space can also be used to separate the option name from its value. Note also that the long name `--month' and the variable name month only happen to be the same in this example; they aren't in general. Alternatively, you can use

birthday @file.opt

to read the paramters from the file `file.opt'. There is also an interactive menu. If you type

birthday --menu

at the command line, then you'll see this on the screen:

birthday m Month 4 d Day of month 24 y Year 1993 v Verbose FALSE p Use Pade Approximants FALSE g Gregorian FALSE (Type ? for Help) ->

By invoking the menu, the user is able to see what all the available options are, even the obscure ones. The prompt `->' is waiting for your response; type `m 9' and return to set the value of month to 9. Set any other parameters as you see fit. Enter a blank line, and the you'll again see a list of parameters and values. Then type `=' and the program will run with those parameters, and then return to the prompt. You can change the parameters and run again if you like. Type `.' to exit.

Note that the programmer may optionally disable the menu, so some applications that use opt may not allow the --menu option.

Finally, the program is somewhat self-documenting. Type

birthday --help

at the command line, and then you'll see a message like this:

Usage: birthday [options] To invoke the menu, type: birthday --menu The options are: -m, --month <INT> Month -d, --day <INT> Day of month -y <INT> Year -v <INTLEVEL> Verbose -p <BOOL> Use Pade Approximants -g <BOOL> Gregorian

and then the program exits. There are several other features provided by opt that will be discussed in later sections.

1.2 What the programmer sees

/* birthday.c */

#include <stdio.h>
#include <opt.h>                /* part of opt package */

/* Parameters that user has access to via opt package;
 * They are typically (but not necessarily) global variables.
 * Their default values are provided in the assignement statements.
 */
int month=9;
int day=11;
int year=1989;
int verb=0;
int pade=0;
int greg=0;

/* All of what the program itself does is in the birthday() function;
 * This function does what a non-options parsing main() might do.
 */
int birthday(int argc, char **argv)
{
    if (month == 9 && day == 11 && year == 1989)
        printf("Happy birthday, Max\n");
    else if (month == 4 && day == 24 && year == 1993)
        printf("Happy birthday, Sky\n");

    if (verb)
        printf("Hello, world: %4d/%02d/%02d\n",year,month,day);

    return OPT_OK;
}

/* all of the options parsing is in the new main() function */

int main(int argc, char **argv)
{
    /* optrega() registers short name '-m' and long name '--month' to
     * variable 'month', and provides brief description "Month"
     */
    optrega(&month,OPT_INT,'m',"month","Month");
    optrega(&day,  OPT_INT,'d',"day",  "Day of month");
    /* optreg() only provides short name '-y' */
    optreg(&year,OPT_INT,'y',"Year");
    /* register some flag variables... */
    optreg(&verb,OPT_INTLEVEL,'v',"Verbose");
    optreg(&pade,OPT_BOOL,'p',"Use Pade Approximants");
    optreg(&greg,OPT_BOOL,'g',"Gregorian");

    /* the function birthday() is registered with opt */
    optMain(birthday);

    /* opt() is the routine that actually parses the argc/argv
     * variables
     */
    opt(&argc,&argv);
    opt_free();
    /* and when it's done, argc/argv will contain the leftover
     * argc/argv variables, including the same argv[0] as in
     * the original argc/argv
     */

    /* Now that variables are parsed, run birthday() */
    return birthday(argc,argv);
}

The opt package consists of the header file `opt.h', which must be #include'd in any code that uses opt, and the library file `libopt.a', which is linked to the program at compile time

cc -Idir_with_opt_h -Ldir_with_libopt_a birthday.c -lopt

2. Opt

2.1 Philosophical digression
2.2 What is Opt?
2.3 User Interface
2.4 Programmer Interface

2.1 Philosophical digression

Programs that provide a convenient user interface, especially those with gooey user interfaces (GUI's), generally require a fair bit of programming to produce. But for short programs that will not be used a lot, "programmer friendly" is more important than "user friendly." If a program grows in size or usefulness, the programmer can then go back and put in a better interface. But in doing so, the programmer trades away the "programmer friendliness" of the original code to end up with software that exhibits "user friendliness".

Suppose you want to write a program that depends on some parameters. As a programmer, it is convenient to set the parameters (in the vernacular, to "hardcode" them) to desired values right in the program. It is not really very convenient, though, because you have to recompile the program every time you want to run it with different values. This is especially inconvenient when the user and the programmer are different people.

It is usually more convenient (for the user) if the parameters can be specified at run time. There is, of course, more than one way to do this. You can specify parameter values in an input file, for instance. Then the program has to open the file, read the values, assign them to the appropriate variables, and then compute accordingly. It's a little inconvenient for the programmer, and a little inconvenient for the user, but if there are a large number of parameters, this is often the best approach. Even for a small number of parameters, it is useful to at least have the option of saving parameter values in a file.

Another approach is to have the program "ask" the user what parameter values are desired. After typing `birthday' for instance, the program might respond with

What is the number of the month?_

to which the user would reply, say, "9". Then

Enter the day of the month and the year?_

to which the user would type "11 1989" or perhaps "11,1989" depending on the format that the program expected for input. This style of program sometimes seems friendly at first, since the user doesn't have to know a lot about the program to run it, but just has to answer the questions. It can get to be pretty awkward after awhile, though, particularly if there are a lot of options, and especially if the program is to be used in shell scripts. It is not too hard to write the program to do this (it is basically a series alternating printf's and scanf's), but for a lot of parameters, it can get pretty tedious.

One of the most popular approaches is to specify the options and parameter values directly from the command line. The user types

birthday -m 9 -d 11 -y 1989

and this specifies in one compact line values for month, day, and year. This is a bit of a compromise; the user has to know what all the options are, and the programmer has to do a little string parsing. The motivation for the opt package is to bridge this gap: to on the one hand simplify the programmer's task of converting command line strings into parameter assignments, and on the other hand to provide the user a little more information about the available options and a little more convenience in setting those options and parameter values.

2.2 What is Opt?

I know I've said this already, but... opt is a subroutine library for communicating options and parameter values to a C program via the command line, parameter files, environment variables, or a rudimentary builtin interactive menu.

The aim of the opt package is to permit programs to be both user- and programmer- friendly. The package attempts to provide a direct and relatively full-featured input interface to the ultimate user of the program, and at the same time to impose a minimal amount of work on the programmer to "add" options parsing to existing software.

The next sections basically parallel the `Nutshell' chapter, but add a little more detail. First, the opt interface will be described, as it appears to the user. This comprises the advertisement for incorporating opt into your code. Then it will be shown how to write code that uses opt for its user interface.

2.3 User Interface
2.4 Programmer Interface

2.3 User Interface

Currently, opt supports the following modes of interface to the user:

• Direct command line options
• Options from a named file
• Environment strings
• Rudimentary builtin menu
• Standard usage messages

2.3.1 Direct command line options
2.3.2 Options from a named file
2.3.3 Environment strings
2.3.4 Rudimentary builtin menu
2.3.5 Standard usage messages

2.3.1 Direct command line options

birthday -m9 -d11 -y1989  ;Sets values of month, day, and year
birthday -d11 -y1989 -m9  ;Doesn't matter what order
birthday -m9              ;Set month=9, day and year to their defaults
birthday -m 9             ;Space is permitted between m and 9
birthday - m9             ;Not valid to have space beweeen - and m
birthday -m9-d11          ;Not valid; need space between each
                          ;delimited option

Some kinds of options are of a different form. Among these are "flags" which signal whether a given option is on off. Thus, one might signal that a program is to operate in verbose mode with a command line of the form `birthday -m9 -v'. Alternatively, one can write `birthday -m9 -v+' to explicitly turn the verbose option on, or `birthday -m9 -v-' to explicitly turn verbose off. Unlike options which assign values, flag parameters can be assigned with a single delimiter. Thus, one might have a verbose (`v') flag, a gregorian (`g') flag, and a "use Pade approximant" (`p') flag. In this case, one can write commands of the following forms:

birthday -v -g -p ;Invoke all flags birthday -vgp ;Invoke all flags, in a more compact notation birthday -pv+g- ;Invoke p-flag, while explicitly ;turning v-flag on, g-flag off.

Invoking a flag is not always the same as setting the flag to ON. Depending on how the flags are defined in the program, invoking a flag may set its value to ON, to OFF, or toggle it to the opposite of its value before invocation. For instance, if the `p'-flag is a toggle, the command `birthday -p -m9 -p' toggles it twice, so that the effect of the two invocations are to cancel each other out. The motivation for toggles and other kinds of flags will become apparent when the command line is extended to files and environment variables and interactive menus.

2.3.2 Options from a named file

It is clear that a program with many options begins to get unwieldy on the command line, and it is desirable to save options in a file, and not have to retype them every time the program is run. The opt package permits this with command lines of the form `birthday @bday.opt'. Here `bday.opt' is a file which contains options which are used by the program birthday. The form of the options file `bday.opt' is like that of the command line itself. Thus, if the file is composed of the string `-m9 -d11 -y1989 -vg' then it is as if that string replaced `@bday.opt' on the command line.

A file permits some luxuries that are not available on the command line directly. One of these is that you are not limited to a single line, and another is that you can add comments in the file. Thus if the file looks like this:

;file: bday.opt ;Comments are preceded by a semi-colon -m9 ;September -g ;Use gregorian -d11 -y1989 ;Can still have several options on one line

Then `birthday @bday.opt" is exactly equivalent to "birthday -m9 -g -d11 -y1989'.

It is possible to mix direct command line options with file options. Thus `birthday -v @bday.opt -p' is equivalent to `birthday -v -m9 -g -d11 -y1989 -p'. This is particularly useful if you want to make many runs in which only a few parameters are changed at a time. For instance,

birthday @defaults.opt birthday @defaults.opt -m10 birthday @defaults.opt -v

might represent three runs of the program "birthday", the first with a default set of options, the second with the same options except m=10, and the third the same as the first, except that verbose is turned ON.

It is also possible to nest files, so that one might have two files:

;file: bd1.opt -m5 ;set some option values -y 1997 @bd2.opt ;get more options from file bd2.opt

and

;file: bd2.opt -d 11 ;set day=11 -y 1989 ;set year=1989

and then the command line `birthday @bd1.opt' conceptually expands to be the equivalent `birthday -m5 -y 1997 -d 11 -y1989'. This is a completely valid command line, even though the 'y' option appears twice; it is the last value of a variable which the program uses, in this case y=1989.

Of course, recursive nesting will only get you into trouble.

There is a useful abbreviation for files: @@ stands for the default options filename which is always the program name with the extension ".opt". Thus `birthday @@' is equivalent to `birthday @birthday.opt'

You can also write to an opt file; the directive `%file.opt' writes the current options to the file `file.opt' and then exits. Here, `%%', invoked for a program called `birthday', is an abbreviation for `%birthday.opt'.

2.3.3 Environment strings

The program which uses the opt package can be instructed to look for an environment variable for options. If birthday sets `BIRTHDAY' as its option environment variable, and if the environment string `BIRTHDAY=-m9 -y1989' is set, then running `birthday' is equivalent to running `birthday -m9 -y1989'. The environment options are assigned before any command line options, so they can be over-ridden: thus the command `birthday -m10' resets m to be equal to 10 instead of m=9 suggested by the environment string, but one still has y=1989. The environment string is therefore a useful place for storing default options that you don't want to have to keep typing them each time you run the program. In the UNIX C-shell you can set an environment string with the `setenv' command:

setenv BIRTHDAY "-m9 -y1989"

while in the Bourne shell, you'd write

BIRTHDAY="-m9 -y1989" export BIRTHDAY

Note that UNIX environment strings are not the same thing as shell variables In MS-DOS, one uses the command "set"; the format is

set BIRTHDAY=-m9 -y1989

with no quotes. To unset, type "set BIRTHDAY=", and to view just type "set". (However, it's been ages since I've used opt on MS-DOS; I'd be surprised if it still worked on that platform. Of course I'm always surprised when anything works on that platform.)

2.3.4 Rudimentary builtin menu

Although the above methods provide flexible means of getting parameter values to a program which is run in background or batch mode, it is also useful to alter parameters interactively. The opt package provides a convenient way to do this, with an interactive menu. To invoke the menu type `$' (or `--menu') at the end of the command line. For instance, typing `birthday -m4 -y1993 $' will return a menu that looks something like

birthday m Month 4 d Day of month 11 y Year 1993 v Verbose FALSE p Use Pade Approximants FALSE g Gregorian FALSE (Type ? for Help) ->

The prompt `->' is an invitation to the user to write a segment of a command line. For instance a reply of `-m4 -vg' will come back with a bare prompt:

->

Responding with an empty line will give a new menu that looks like

m Month 4 d Day of month 11 y Year 1989 v Verbose TRUE p Use Pade Approximants FALSE g Gregorian TRUE (Type ? for Help) ->

When you are ready to run the program with these values, type `='. Actually, there are a number of things you can type at the command prompt; type a plain `?' for the following description:

- Options delimiter ? Help = Run program and return to menu ! Shell to Operating System $ Exit menu + Additional options @<filename> Get options from file @@ Get options from file [birthday.opt] %<filename> Put options in file %% Put options in file [birthday.opt] . Quit ->

It is also possible that `?c' will give further information about the option specified by `c', although this requires that the programmer supplied extra information (usually, the brief description is all that is available). For example,

-> ?d d: Use day of month, should be less than 32 ->

If you don't want the user to have access to the menu for some reason, then you can invoke the function `optDisableMenu()' before calling `opt()', to achieve this. You might want to do this to avoid stuff about menus appearing in the usage message, for instance.

2.3.5 Standard usage messages

birthday --help

Usage: birthday [options]
To invoke the menu, type:
        birthday --menu
The options are:
 -m, --month        <integer>       Month
 -d, --day          <integer>       Day of month
 -y                 <integer>       Year
 -v                 <flag>          Verbose
 -p                 <flag>          Use Pade Approximants
 -g                 <flag>          Gregorian

2.4 Programmer Interface

First an example source code will be shown so that the programmer gets an idea of what it takes to incorporate opt into his or her favorite application. Subsequent sections will then go into more detailed explanation.

2.4.1 Example code
2.4.2 Registering options
2.4.3 Setting some strings
2.4.4 Registering functions (hooks)
2.4.5 Misc

2.4.1 Example code

The easiest way to see how to use the opt package is with an example. The following program illustrates most of the features that you'd actually want to use (and several you probably don't care about).

/* testopt.c */ #include <stdio.h> #include <stdlib.h> #include <opt.h> int month=4; int day=24; int year=1993; char *who=NULL; int go(int argc, char **argv) { if (argc>1) { printf("In program %s, Extra option: %s\n",argv[0],argv[1]); } if (optinvoked(&month)) { printf("User set month...\n"); } if (month == 9 && day == 11 && year == 1989) { printf("Happy birthday, Max\n"); } else { printf("Hello, %s: %4d/%02d/%02d\n",(who==NULL ? "world" : who), year,month,day); } return OPT_OK; } int checkyear(void *v) { if (year == 2000) { printf("Watch out for that year=2000 bug!\n"); return OPT_ERROR; } return OPT_OK; } int quit() { printf("Bye...\n"); return OPT_OK; } int write_altversion() { printf("AltVersion XXX\n"); optExitNumber(12); return OPT_EXIT; } int fix_mon(void *v) { int m; /* fix whatever int variable v is pointing to */ m = *((int *)v); if (m < 1 || m > 12) m=1; *((int *)v) = m; return OPT_OK; } main(int argc, char **argv) { optreg(&month,OPT_INT,'m',"Month"); optlongname(&month,"month"); opthook(&month,fix_mon); optrega(&day,OPT_INT,'d',"day","Day"); opthelp(&day,"Use day of month, should be less than 32"); optreg_INT(&year,'y',"Year"); optreg(&year,OPT_INT,'Y',"Year"); optdescript(&year,"What Year"); opthook(&year,checkyear); optregp(&who,OPT_STRING,"who","Who to say hello to"); optexec("altversion",write_version,"Write version number and exit"); optEnvVarName( "OPT" ); optMain(go); optQuit(quit); opt(&argc,&argv); go(argc,argv); opt_free(); }

2.4.2 Registering options

It is necessary for the programmer to somehow tell the package which options are associated with which variables in the program, and what descriptions opt should use in the usage message and the menu. This is done with a function call that "registers" (or associates(1)) a variable and a name. These functions (one for each variable, in general) are usually called at the beginning of the code.

Opt can handle three kinds of options:

Delimited options

Options that are "flagged" by the user using a command line switch such as `-n' or `--size'.

Positional options

Options that do not have an associated switch and simply appear on the command line as bare arguments.

Flexible options

Options that can appear either as a delimited or a positional argument.

2.4.2.1 Delimited options
2.4.2.2 Positional options
2.4.2.3 Flexible options
2.4.2.4 Default values
2.4.2.5 Modifying option attributes
2.4.2.6 Registering array options
2.4.2.7 Registering options in C++

2.4.2.1 Delimited options

Delimited options are the standard options you'd expect an option handling package to work with. Delimited options are flagged by the user with a switch that starts with `-' or `--'.

`Opt' provides a variety of commands for registering delimited options with different variable types, and using the "short", or "long" delimited option forms (or both).

For example,

optreg(&day,OPT_INT,'d',"Day");

where day is the name of the variable as it appears (for instance as a global variable) in the C program; OPT_INT tells opt that the variable is an `int', d is the alphabetic character that is used on the command line to alter the parameter day, and "Day" is a string that will be used in the menu and the standard usage messages.

You can register a long (string) name as well as the short (one character) name. The function name has an extra `a' (mnemonic: all) at the end.

optrega(&month,OPT_INT,'m',"month","Month");

With this registration in place, `-m 4' and `--month=4' have the same effect; to change the value of the variable month to four. If you want to register a long name to a variable without also having a short name (this is sometimes desirable if there are a lot of options), this can be done with a call to `optrega' that sets the short name to the null character; e.g.,

optrega(&month,OPT_INT,'\0',"month","Month");

The variable OPT_INT is of type `opt_TYPE'; this is an enumerated type and is defined in the header file `opt.h'. The available option types are: OPT_INT, OPT_SHORT, OPT_LONG, OPT_CHAR, OPT_UINT, OPT_USHORT, OPT_ULONG, OPT_UCHAR, OPT_FLOAT, OPT_DOUBLE, OPT_BOOL, OPT_TOGGLE, OPT_NEGBOOL, OPT_NEGTOGGLE, OPT_INTLEVEL, OPT_STRING, OPT_CSTRING, OPT_UNDELIM, and OPT_UNDELIMC. There is also a type OPT_NUL that is used internally.

Most of these are self-explanatory:

OPT_INT int OPT_SHORT short int OPT_LONG long int OPT_UINT unsigned int OPT_USHORT unsigned short int OPT_ULONG unsigned long int OPT_FLOAT float OPT_DOUBLE double

All of these are invoked on the command line with the form `-x#' or with `-x #' where `#' is the value of the number. Along these same lines is the type

OPT_CHAR char

which can only be invoked as `-x#' and not `-x #'. The latter form will assign the x variable to the character value NULL ('\0'), and `#' will be treated as the next option.

There are a variety of options for boolean (yes/no, 1/0, on/off) flags:

OPT_BOOL int Probably this is the one that you want. Invoking this option sets the value to 1; and subsequent invocations have no effect. OPT_TOGGLE int Each invocation changes the value -- either from 0 to 1 or from 1 to 0. OPT_NEGBOOL int Like OPT_BOOL but invoking the option sets the value of the variable to 0. OPT_NEGTOGGLE int Like OPT_TOGGLE, in fact a lot like OPT_TOGGLE. I can't think of why you would want to use it. OPT_FLAG int Deprecated! Use OPT_TOGGLE instead. OPT_NEGFLAG int Deprecated! Use OPT_NEGTOGGLE instead. OPT_ABSFLAG int Deprecated! Use OPT_BOOL instead. OPT_ABSNEGFLAG int Deprecated! Use OPT_NEGBOOL instead. In my own experience, I have found absolute flags are usually preferable to toggle flags. The problem with toggles is that you can easily lose track of the current state of the toggle, especially when options can be specified in files, environment variables, and the menu, as well as the command line itself. OPT_INTLEVEL int This is a kind of a combination of flag and int: OPT_INTLEVEL is an integer that can take on only positive values, usually less than ten. I find this useful for "verbose" since I can not only turn verbose ON, but I can have a range from slightly verbose to extremely verbose. For this flag, each invocation increases the level; eg, `-v -v' sets verbose=2, and `-v-' turns verbose off.

There are two types of strings, variable and constant. Which of these to use depends on how the variable is declared:

char *vstring=NULL; /* variable string */ char cstring[80]; /* constant string */ char *cstring="hello"; /* this is a constant string too */

The difference is that cstring already has space allocated for it, so to have cstring be "string" one has to use `strcpy(cstring,"string")', and note that the pointer cstring itself does not change. By contrast, to use vstring, space must be allocated dynamically. In this case, one has to change the value of the pointer vstring with something like

vstring = (char *)malloc(strlen("string")+1); strcpy(vstring,"string");

OPT_STRING char * OPT_CSTRING char *

By the way, if you are using `OPT_CSTRING', you should make sure that it has room for a string of length `OPT_MAXSTRLEN'. But in general, you should prefer `OPT_STRING' of the two. (Note, `OPT_STRING' used to be called `OPT_VSTRING' but the latter form is now discouraged.)

2.4.2.2 Positional options

The second kind of option that `opt' provides is the positional option. These are similar to delimited options except that they are not flagged by a delimiter switch on the command line. The user specifies values for positional options by simply writing those values as bare arguments on the command line. The processing of positional options is determined by the order in which they appear on the command line, hence the name.

To register a positional option, use the `optregp' command. For example:

char* input = NULL; ... optregp(&input,OPT_STRING,"input-file","File to process");

In this example, we have associated the variable `input' with a positional option of type OPT_STRING (a dynamically allocated string). `"input-file"' is a long name associated with the option. It is not actually used in option processing for pure positional parameters, but is used to refer to the positional argument in the usage message that `opt' generates. In addition, if the option is subsequently made "flexible" see section 2.4.2.3 Flexible options, then the option may be set either positionally OR using a delimited option of the form:

--input-file=fred.txt

Undelimited command line arguments are assigned to positional options in the order in which those positional options were registered. If there are insufficient command line arguments to process all registered positional options, then the remaining postional options are simply never invoked. If there are more command line arguments than positional options, then the remaining command line arguments are returned to the `argv' array after `opt' processing has finished.

Note: At the time of writing, such extra undelimited arguments also cause opt processing to terminate immediately, even if there are as yet unprocessed delimited arguments on the command line. This is probably a mistake and will be fixed in some future release.

Positional options can be registered using any of the types described under 2.4.2.1 Delimited options.

A delimited option can be turned into a positional (or flexible) option by using the `optmode()' function on that option see section 2.4.2.5 Modifying option attributes.

In earlier versions of `opt', positional parameters were handled using a special variable type, `OPT_UNDELIM', that was equivalent to `OPT_STRING', but with positional semantics. This usage is still available in `opt' but is deprecated.

2.4.2.3 Flexible options

The third kind of option is a flexible option. Flexible options are simply positional options that can also be set by the user using a delimited switch as well. This can be handy in some cases, for instance when setting a positional option from a file.

To register a flexible option, you can use the `optregf()' function:

char* input = NULL; ... optregf(&input,OPT_STRING,'f',"input-file","File to process");

In this example, we have associated the variable `input' with a flexible option of type OPT_STRING (a dynamically allocated string). The user may set this option either positionally, using the normal rule that positional options are processed in the order that they were registered, OR by using a delimited option of the form `-f foo.dat' or `--input-file=foo.dat'.

An existing positional or delimited option can be turned into a flexible option by invoking either the `optmode(...,OPT_FLEXIBLE)' or `optmode_n(...,OPT_FLEXIBLE)' functions on that option.

2.4.2.4 Default values

To give an option a default value, simply assign an appropriate value to the corresponding registered variable, before or after it is registered. Consider the following example:

int year=1999; ... optrega(&year,OPT_INT,'y',"year","Year of interest");

If the user does not invoke the `-y' option, then the variable `year' will retain the value of 1999.

2.4.2.5 Modifying option attributes

If a variable is registered, then you can change or add to its attributes; for instance:

optreg(&var,OPT_INT,'c'); optlongname(&var,"variance");

The various registration functions (`optreg()', etc) return an integer which is the index of the registered option. Sometimes (eg, instance when there is no variable associated with the registration) this integer is a more useful identifier of a given option. The above, for instance, is equivalent to:

n = optreg(&var,OPT_INT,'c'); optlongname_n(n,"variance");

void optchar(void *v, char c)

Associates the single-character name with the variable pointed to by v.

void optchar_n(int n, char)

Associates the single-character name with the n'th registered variable.

void optlongname(void *v, char *longname)

Associates the long name to the variable pointed to by v.

void optlongname_n(int n, char *longname)

Associates the long name to the n'th registered variable.

void optmode(void *v, int mode)

mode can be one of OPT_DELIMITED, OPT_POSITIONAL, OPT_FLEXIBLE. Makes the option associated with the variable pointed to by v have the corresponding mode.

void optmode_n(int n, int mode)

As `optmode()', but applies to the n'th option.

void optdescript(void *v, char *descript)

Changes the brief description of the variable pointed to by v.

void optdescript_n(int n, char *descript)

Changes the brief description of the n'th registered variable.

void opthelp(void *v, char *help)

Associates a longer help string with the variable pointed to by v. This is the string the user will see upon typing `?c' at the menu prompt, where `c' is the single-character name.

void opthelp_n(int n, char *help)

Associates a longer help string with the n'th registered variable.

void optarraydelim(void *v, char delim)

Resets the delimiter (default is comma) for the array variable. Note that using optarraydelim(NULL,delim) resets the delimiter for all array options.

void optarraydelim_n(int n, char delim)

Resets the delimited for the n'th registered variable.

2.4.2.6 Registering array options

As well as registering scalar variables, you can also register dynamically allocated arrays, and manipulate their values with command line options, parameter files, environment strings, or on the menu. As a user, you would type for instance `program -x 1,2,3' to set the array values to 1, 2, and 3. As a programmer, you need to keep track not only of the array pointer but of the size of the array, so to register an array option requires an extra argument. For example

int nx=0; double *x=NULL; ... optreg_array(&nx, &x, OPT_DOUBLE,'x',"Array of x values");

As well as the optreg_array function, you can also use optrega_array, optregc_array, optregcb_array, optregs_array, and optregsb_array. These are essentially equivalent to the scalar versions, except that the first argument is a pointer to the size of the array.

After the options have been processed, the array x[] will have nx elements. In the above example, nx would be 3, and x[0] would be 1, x[1] would be 2, and x[2] would be 3. It would be a mistake to refer to x[3], since that is beyond the array bounds, but since the programmer has access to nx, that shouldn't be a problem.

Note that opt can only handle arrays of simple types (strings, characters, and numbers); arrays of OPT_BOOL's or OPT_INTLEVEL's are not supported.

The default delimeter for array values is a comma; this can be changed using the optarraydelim(void *v,char delim) function.

See the file `test/tarray.c' for examples of this usage.

2.4.2.7 Registering options in C++

opt also provides a rudimentary C++ interface. You can always use the plain C code inside your C++ programs, but you may find it a little more convenient to use the OptRegister function. This function can be used like optrega except that it has a lot more flexibility. Also, if you want to register a standard type, like OPT_INT or OPT_DOUBLE but not a specialty like OPT_UNDELIM or OPT_INTLEVEL, then you can just leave out the type specifier -- C++ knows what you mean. For example:

// Can invoke with -N500 or --nPulses=500 OptRegister(&N, 'N', "nPulses","total Number of pulses"); // Can only invoke with long name --delta=0.01 OptRegister(&delta,"delta","average time between pulses"); // Can only invoke with short name -x3.14159 OptRegister(&x,'x',"x marks [the horizontal position of] the spot") // You have to specify flags as such, otherwise they are // treated as ordinary integers. Note that the variable is // still an integer. Currently there is no support for the // C++ bool type, which is unfortunate. OptRegister(&flag,OPT_BOOL,'f',"flag","boolean variable"); // The descriptions are optional, so you can have very simple commands OptRegister(&y,'y'); // But beware that there can be ambiguity between longname and description. // The first string is assumed to be the longname OptRegister(&z,'z',"third coordinate value"); // error! // You can also register positional options using OptRegister OptRegister(&y, OPT_POSITIONAL, "y-value", "The value of y"); // Or flexible options OptRegister(&y, OPT_FLEXIBLE, "y-value", "The value of y", OPT_FLEXIBLE); // If you specify both a type and a mode, specify the type first OptRegister(&flag,OPT_BOOL,OPT_FLEXIBLE,'f',"flag","boolean variable");

See the example file `test/testcc.cc' for a working example.

Note that using these routines requires that `libopt.a' or `opt.o' be compiled using a C++ compiler. This is normally handled automatically by the installation procedure. If you want to include a single file with your distribution containing the opt code, then use `optcc.cc' rather than `opt.c'. Both of these are generated automatically as part of the opt install procedure.

Beware that there is a problem with gcc 3.0 and 3.1 on Solaris. The problem has been traced to the compiler itself, and the maintainers have promised that it will be fixed in the next release. If you use the environment variable CPLUS_INCLUDE_PATH to tell the compiler where `opt.h' is located, then you will get error messages during compilation. One solution is to use the explicit -I... directive during compilation. Another is to disable the C++ interface in opt by #define'ing the variable OPT_NOCPLUSINTERFACE before #include'ing `opt.h'. This however will disable the overloaded OptRegister function, and you'll have to use the bulkier optreg functions from the C interface.

2.4.3 Setting some strings

The following functions set strings which the opt package uses for various things.

void optUsage(char *s)

Sets the usage statement that the program will print as part of the help message.

void optTitle(char *s)

Sets the title, which appears as the first line in the menu. If not set, then the program name is used.

void optProgName(char *s)

Sets the program name, which appears in the usage message. Any leading directories in s are stripped off. If the program name is not set explicitly, then it is set when `opt()' is called. The programmer might want to set the program name using this function, if for some reason argv[0] does not contain the command that runs the program, or to ensure that the usage message can be displayed using the `optPrintUsage()' function, before `opt()' has been invoked.

void optVersion(char *s)

Sets the version number of the program that you are writing. When the user types `program --version', then this is the version number that is printed. Note that if the function optVersion is not used, then `--version' will do nothing (except get a warning message that `version' is not a registered option).

void optEnvVarName(char *s)

Sets the name of the environment variable where the opt package will look for initial command line options. If not set, the opt will not be check any environment variable for options processing.

void optDefaultString(char *s)

The program itself can define a default command line to be processed before the environment string and before the actual command line. To be honest, I can't imagine when you'd want to use this in real life.

void optDefaultFile(char *s)

The program can define a file name, eg `~/.programrc' or `/etc/program.opt', in which to look for default options for the program. If the file exists, then its options are read in before reading the environment string or the command line.

2.4.4 Registering functions (hooks)

Hooks are means by which the user can write routines which the opt package calls during its processing. This enables the programmer to customize the behavior of opt to the program at hand. Of course opt has to be informed of the function (in the same way that variables have to be registered, so do functions). The hook function should always return an integer, and a value of zero is the default that tells opt that all is okay. (You can also return `OPT_OK', which is defined to be zero in `opt.h'.) The return value tells opt what to do after the hook has been run. [** Warning: I am thinking of changing these. --jt **]

OPT_OK

Default. Keep processing options.

OPT_ERROR

Signals to opt that the hook was not successful. Currently, opt doesn't do anything differently from what it does if `OPT_OK' is returned.

OPT_EXIT

Program exits using the C command `exit(n);' The value of n will be zero unless it has been set by the function `optExitNumber(n)'.

OPT_QUIT

Program exits, as with `OPT_EXIT', but it will first check to see if a quit-hook has been defined with the `optQuit()' function. If one has, then it will run the quit-hook and then exit.

OPT_ABORT

If you are in the menu, you should be returned to the prompt (assuming you configured opt to `--enable-longjmp' (default) at compile time); but if you are running from the command line, the program will quit calling a quit-hook if one has been defined.

There are basically two kinds of hooks. The first kind is associated with a specific variable, and it is run whenever that option is invoked. These hooks take a single argument, a `void *' that points to the associated variable. The second kind of hook is not associated with a specific variable, and it takes no arguments. It might be associated with a command line string (such as `--version' which you might want to use to make the program write a version number and exit; but see the optVersion function in 2.4.3 Setting some strings.), or with the general behavior of opt, such as the quit hook described below. Here, `OPT_PFI' is declared `typedef int (*OPT_PFI)()' in the header file `opt.h'; it is a pointer to a function returning an integer. (Currently we exploit C's loose typecasting rules, so that `OPT_FPI' refers to a function with any number of arguments, as long as it returns an integer. In future versions, we may define `OPT_PFI_V' and `OPT_PFI_ARG' types, to indicate functions that take arguments `void *' and `int,char **' respectively.)

The first kind of hook is registered with the function `opthook()'. For instance, if you register a hook with a statement such as

int fix_mon(void *v) { ... } int month=9; ... optreg(&month,OPT_INT,'m',"Month"); opthook(&month,fix_mon)

then the function `fix_mon' will be called when the 'm' option is invoked. For instance, the function might determine whether the integer month variable was between 1 and 12, and if not, to fix it in some way. Note that the hook function `fix_mon' takes a single `void *' argument; when opt calls the hook function, it will use a pointer to the variable month as the argument. You can use the argument to get (and manipulate) the value of the variable month. However, if the variable is global, then you can also manipulate the month directly. So the following two examples serve the same purpose.

int fix_mon(void *v) { /* don't bother using the argument v; * just manipulate month directly */ if (month < 1 || month > 12) month=1; return OPT_OK; }

and

int fix_mon(void *v) { int m; /* fix whatever int variable v is pointing to */ m = *((int *)v); if (m < 1 || m > 12) m=1; *((int *)v) = m; return OPT_OK; }

The second example is not as pretty to look at, but it is more general. It does not have to know which variable it is fixing, and in fact you can `opthook' this function to several variables, and it will apply the `fix_mon' algorithm to those variables as they are invoked.

`void opthook(void *v, OPT_PFI fcn)'

associates a hook `fcn' with the variable pointed to by v. Whenever the option associated with v is invoked, eg from the command line, the hook is called.

`void opthook_n(int n, OPT_PFI fcn)'

associates a hook `fcn' with the n'th option. n is the value returned by the registration function `optreg'.

`int optexec(char *longname, OPT_PFI fcn, char *descript)'

associates a hook `fcn' to the string pointed to by longname. For instance, the command `optexec("altversion",print_version,"Write version info and exit");' will cause the function `print_version()' to be called whenever the string `--altversion' appears on the command line. The function `print_version()' takes no argument, and depending on its return value, the program will either exit or keep going after printing the version string. (Note that `--version' is an opt builtin; see the optVersion function in 2.4.3 Setting some strings.)

`optMain(OPT_PFI fcn)'

The most commonly used hook in an opt program, at least by me. This function is run when the user types `=' at the opt menu prompt. Usually, the programmer writes `fcn(argc,argv)' to do whatever it is that the program is supposed to do (essentially the same as `main(argc,argv)' but without the command line parsing that opt is taking care of). The arguments `argc,argv' that `fcn' sees are the command line strings that are "leftover" after opt has finished parsing; `argv[0]' is retained however, so that `fcn' behaves just like a `main' function would behave. When `fcn' is finished, you will be returned to the command line prompt. If opt was configured at compile time with the `--enable-longjmp' (default), then if you interrupt (^C) `fcn' while it is running, you will be returned to the command prompt (instead of exiting the program completely).

`optRun(OPT_PFI run)'

This is essentially the same as `optMain', except that the function `run()' takes no arguments. If you set this hook and the hook in `optMain', then this hook will be ignored.

`optQuit(OPT_PFI fcn)'

is a hook that is run just before the program that is using opt exits.

`optAdditionalUsage(OPT_PFI fcn)'

This hook is run at the end of the usage message, and can be used to provide the user with additional usage information.

`void optExitNumber(int n)'

If opt has to exit, then call exit(n);

2.4.5 Misc

int optinvoked(void *v)

Returns the number of times the option associated with the variable pointed to by v was invoked by the user.

void optPrintUsage()

Print the current usage message to standard out.

void opt_free()

If you are worried about memory leaks, you should call this routine when you are finished using opt routines. Most of the time, that means you can invoke `opt_free()' right after `opt(&argc,&argv)', but after `opt_free()', you won't be able to use `optinvoked' for example. Note that this will not free all the memory that opt allocated -- for instance, it makes copies of string parameters that are specified on a command line. But also note that opt does not generally take a lot of memory, so if you leave off this command, you will nearly always be just fine.

3. Etc

3.1 Installation
3.2 Adding opt to existing code: a recipe
3.3 So, you don't like global variables?
3.4 Single file
3.5 Extensions
3.6 Bugs
Warranty
Copying

3.1 Installation

Because opt does not require exotic systems services or esoteric libraries, installation on a variety of platforms should be straightforward. What follows is a guide to installing OPT on a UNIX system, but I have heard of at least one successful install on a Microsoft operating system.

First you have to un-archive the `opt-XXX.tar.gz' file, where `XXX' is the version number, using commands along these lines:

gzip -d opt-XXX.tar.gz tar xvf opt-XXX.tar cd opt-XXX

Then, it's bascially a generic GNU installation, with configure, make, and make install. More details can be found in the `INSTALL' file that should be in the distribution, but those are details about the generic installation procedure, and contain no opt-specific notes.

1. You configure with the command `./configure' where the initial `./' is to ensure that you are running the configure script that is in the current directory. You can also use the configure command with options. Type `./configure --help' to see what those options are. One of the most useful is the `--prefix=PATHNAME' option, which tells you where to install it. In this example, the file `libopt.a' will be installed in the directory `PATHNAME/lib', the header file `opt.h' will be installed in `PATHNAME/include', and the info file `opt.info' will be installed in `PATHNAME/info'. Some opt-specific options are:

   `--disable-longjmp'

   If longjmp is enabled (default), then hitting `^C' during a run launched from the menu prmopt will return you to the menu prompt; if longjmp is disabled, then `^C' exits the program entirely. You should only disable longjmp if you have trouble compiling.

   `--with-readline'

   If your system has GNU readline installed(2), you can specify this option to obtain readline features (line editing, history recall, etc) in the opt menu. If you will be using the menu even a little bit, these features are very convenient.

   `--enable-flagonezero'

   By default, flag values of true and false are recorded (to the .opt file for instance) with `+' or `-', respectively; eg, -v+ turns on the v-flag. But if you invoke --enable-flagonezero, then true and false are encoded as `1' and `0' instead. If you have a lot of long option names, it looks a little cleaner (some might argure) to have `--verbose=0' rather than the default `--verbose=-'.

2. The next step is easy, just type `make'. If this fails, you may need to reconfigure in the previous step. Or, you may have a defective version of opt, or you may be compiling it on a new platform

3. Although it is not necessary, you are encouraged to type `make check'. This runs a number of tests to make sure that the opt package you just compiled is actually working. The tests in the `test/' directory also serve as example code to show you how to use the opt package in your own programs.

4. The last step is to type `make install' but you should be sure you have permission to write to the directories where `libopt.a' and `opt.h' will be copied. This is by default `/usr/local/lib' and `/usr/local/include', but that can be changed at the configure step (see `INSTALL' for details). Unless you are installing opt into your personal directory, you will probably have to become "root" before you do this step.

3.2 Adding opt to existing code: a recipe

/* yourprogram.c */
#include <stdio.h>

int N=5;           /* Global variable */

int
main(int argc, char **argv)
{
        /** do some complicated thing  **
         ** that depends on value of N **/
}

You want to use the opt package to make the variable N into a parameter that can be altered on the command line. Here is the recipe.

/* yourprogramonopt.c */ #include <stdio.h> #include <opt.h> int N=5; /* Global variable */ int youroldmain(int argc, char **argv) { /** do some complicated thing ** ** that depends on value of N **/ } int main(int argc, char **argv) { optreg(&N,OPT_INT,'N',"Number that complicated thing depends on"); optMain(youroldmain); opt(&argc,&argv) return youroldmain(argc,argv); }

Basically, you need to include the `opt.h' header file, register the variables that will be command line parameters, register your original `main' function (only now renamed not to conflict with the new `main()'), call the `opt()' function itself, and then call your original `main()' function (now renamed).

If you don't want to use a different `main' function, then you don't have to. In fact the only drawback with this approach is that the user won't be able to use the `"="' command to run the program from within the menu. In such a case, you may want to disable the menu anyway, using the `optDisableMenu()' function.

If the "complicated thing that depends on N" depends on argc,argv, then the argc,argv that `youroldmain()' will see will be the leftover arguments on the command line that come after the `-N 5', or the arguments that come after `--' on the command line.

When the users use your program in the menu mode, they can try different values of N, eg

-> N 5 ;user types `N 5' in response to prompt `->' -> = ;user says to do the complicated thing 5 ;output of complicated thing, followed by prompt -> N 500 = ;user tries another value, and says run with that 2 2 5 5 5 ;computer responds -> N 12345678 ;user types in too large a value, computer hangs ^C ;user hits ^C -> ;computer responds with menu prompt, so user can ;try again with some other value

3.3 So, you don't like global variables?

One, they're not as bad as you might think. Remember, these are not obscure variables that will be interacting in odd ways with different components of a complicated whole; these are the variables that you want to give the user direct access to.

Two, although the examples I've given (and the codes I write) use global variables for the user-alterable parameters, it is possible to use opt without global variables. I will leave this as an exercise for the reader who gives a damn.

3.4 Single file

You may find it inconvenient, however, to include the full distribution of opt, with all of its automake'd Makefiles, its multiple source files, and the extra test and extension directories. As long as your distribution is not an extension to opt whose purpose is ever fancier options parsing, but instead does something useful and just uses opt for its command line processing, then you are permitted to include only the minimal source needed to make `libopt.a'. In fact, to simplify this task, you can do a `make opt.c' in the `src/' directory and a single file, called `opt.c' of course, will be generated. (It is possible that the opt distribution will already have an `opt.c' made for you.) You are free to include `opt.c' along with `opt.h' in your distribution. You don't even need to make a `libopt.a' if you don't want to. Just have your `Makefile' include lines to this effect:

opt.o: opt.c opt.h $(CC) $(CFLAGS) -c opt.c yourprogram.o: yourprogram.c opt.h ... yourprogram: yourpgram.o ... opt.o $(CC) $(LDFLAGS) -o yourprogram yourprogram.o ... opt.o

Note that when you make `opt.c', a pair of GPL-style copyright-like paragraphs will appear. (They are not actually copyright statements, but that's a long story: see Copying.) You are required to keep those paragraphs intact, and make sure it includes a pointer so that users of your distribution can find my full opt distribution, if they want it.

3.5 Extensions

`tkopt'

is a Tk/Tcl script that is used as a front end to programs that have an opt interface. To use it type

tkopt program [options]

and a window will pop up which will permit you to edit all the registered options and parameters, and to run the program. The beauty of `tkopt' is that it knows nothing about the program `program' beforehand. It learns what the options are by running `program --help' and parsing the standard usage message that is output. It also runs `program %tmp.opt' and then reads the `tmp.opt' file to determine the defaults.

`opt.pl'

is an old Perl options processing library that is no longer supported, and no longer included with distributions of opt, but in it's place...

`Opt.pm'

is a Perl package module which can be use'd by other Perl scripts to achieve an opt-like interface. The main bug is that you can already get pretty good option parsing with only a few lines of Perl, and there exist other packages (eg, Getopt::Long) that perform quite powerful processing. What Opt.pm provides is nearly identical behavior to the C version. Thus, you can use tkopt as a front-end to perl scripts using Opt.pm just like you can use it for C programs linked with libopt.a.

`READLINE'

If you configure opt with the `--with-readline' feature, then GNU readline features (line editing, previous line retrieval, etc) will be available in the menu mode of opt. To link your program to this code, you'll need to have the `readline' and `termcap' libraries available. But this is all done automagically (where by "magic" I mean code that is embarassingly complicated) by the configure script. So if `libopt.a' is built with this option enabled, it will actually incorporate the `readline' and `termcap' libraries within itself, and you don't need to do anything different on the linking step. In particular, you do NOT need to add `-lreadline -ltermcap' to the `cc' command line. If it fails, and you don't feel like trying to figure out why, just reconfigure without the `--with-readline' option. It's nice, but not really crucial.

3.6 Bugs

Using opt promotes the use of global variables for the parameters that opt sets. Global variables are generally considered harmful to your health, but in my experience, this has rarely been a problem for variables that you want the user to have access to anyway. I have seen various convoluted schemes for getting around this, but I have not been convinced of their usefulness.

Another bug is that opt doesn't look much like the standard and GNU's getopt package, even though it does pretty much the same thing. Partly this is a design choice; I wanted something that was very easy to "attach" to the code. In particular, with opt, you register options and associate them with variables; this tends to be a little more compact (and in my view more convenient) than the loop and case-statement approach used by getopt. Also, opt has a few more bells and whistles. If I were smart, I would have built opt as an add-on to the standard getopt.

Warranty

Copying

The subroutines and source code in the opt package are free.

However, I was paid to write this software. That is to say, I wrote this software while being paid by the University of California to work for the Department of Energy at Los Alamos National Laboratory. I like my job, and am grateful to the Laboratory for the opportunity to do interesting work and collect a nice paycheck. However, I do NOT own the copyright on this software, and the conditions for redistributing opt reflect that.

These conditions, encrypted in legalese, are described in the file `COPYING' that should be included in the opt distribution. For practical purposes, this is the same as the GNU General Public License, although I read it as saying that the US Government paid for this software, and the US Government doesn't consider itself bound by the more restrictive aspects of the GPL. But the rest of you are.

My own imprecise interpretation of the GPL, as it applies to opt, follows. I should say that this is a heavily edited version of a `Copying' section that I copied from some other GNU package (now forgotten).

Everyone is free to use this software and free to redistribute it on a free basis. The opt library is not in the public domain; there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to prevent or inhibit others from further sharing any version of this software that they might get from you.

Specifically, I want to make sure that you have the right to give away copies of opt, that you receive source code or else can get it if you want it, that you can change opt or use pieces of it in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, I cannot and do not give you the "right" to deprive anyone else of these rights. For example, if you distribute copies of the opt-related code, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for my own protection, I must make certain that everyone finds out that there is no warranty for opt. If this software is modified by someone else and passed on, I want the recipients to know that what they have is not what I distributed, so that any problems introduced by others will not reflect on my reputation, feeble though it may be.

Let me say that by opt-related, I mostly mean opt-derived. If your software does something substantially different from opt, but uses opt for its command line processing, then you can do what pretty much you like with that code: sell it for a profit, design weapons of mass destruction, etc. That's my own view. I should note that a more common interpretation of the GPL holds that if you use a GPL'd library in your code, then your code must be GPL'd. Just because I don't hold this view doesn't mean you are off the hook; it just means that I am unlikely to sue you if you use my package under this less restrictive interpretation.

But in any case, you should make it clear to the users of your code that the options parsing is done by software that is free; you should tell them that free software is a wonderful concept; and you should provide the opt source code, or at least provide the users with a pointer to where the code is available. (Currently, that is `http://nis-www.lanl.gov/~jt/Software'.)

Happy hacking...

Footnotes

(1)

When I say "register" I mean it as a verb, in the sense of "register your handgun", and not as a noun, meaning an immediate memory location on a microprocessor. I apologize to any old assembler-coders who may find this language confusing.

(2)

If it doesn't, you can get readline from any GNU mirror site.

Table of Contents

1. Nutshell

1.1 What the user sees
1.2 What the programmer sees

2. Opt

2.1 Philosophical digression
2.2 What is Opt?
2.3 User Interface

2.3.1 Direct command line options
2.3.2 Options from a named file
2.3.3 Environment strings
2.3.4 Rudimentary builtin menu
2.3.5 Standard usage messages

2.4 Programmer Interface

2.4.1 Example code
2.4.2 Registering options

2.4.2.1 Delimited options
2.4.2.2 Positional options
2.4.2.3 Flexible options
2.4.2.4 Default values
2.4.2.5 Modifying option attributes
2.4.2.6 Registering array options
2.4.2.7 Registering options in C++

2.4.3 Setting some strings
2.4.4 Registering functions (hooks)
2.4.5 Misc

3. Etc

3.1 Installation
3.2 Adding opt to existing code: a recipe
3.3 So, you don't like global variables?
3.4 Single file
3.5 Extensions
3.6 Bugs
Warranty
Copying

Short Table of Contents

1. Nutshell
2. Opt
3. Etc

About this document

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four