MACROS - macros for creating an Options Table.

The Options Table is a data structure constructed by a sequence of macro calls. In order to use these macro calls, you must put

#include <cl.h>

at the beginning of the source file that constructs the Options Table.

Every Options Table declaration has the form

CL_OPTION_TABLE(optabname)
    /* Macro creating first table entry */
    /* Macro creating next table entry */
               ...
CL_END_OPTION_TABLE

where:

CL_OPTION_TABLE(optabname): is a macro which begins the creation of the Options Table. The "optabname" argument should be a standard C identifier. You will use this name to refer to the Options Table in subsequent C source code.
CL_END_OPTION_TABLE: is a macro which ends the Options Table.

In between these two macros come a sequence of other macros defining possible kinds of input to be found on the command line. Each macro creates an entry in the Options Table. There should be an entry for every possible option, plus every other type of argument that may be accepted.

Option Table Entries:

Each Option Table entry is created with a macro call. Different types of entries use different macros; however, certain features are common to each macro.

The first argument to each macro is a string describing the use of each macro. This is used as part of the usage information displayed in response to the +HELP option.
The second argument to each macro is a single token (unquoted) designating the nature of the option or argument being defined. We will call this argument the "designator".
For options, this is the option keyword (with upper case letters indicating required characters and lower case letters indicating characters that may be omitted).

For arguments, this is a word that may be used in the usage information. For example, if this argument should be a filename, you might specify "file" for this argument.
The third argument to each argument is a set of one or more flags applying to the corresponding option or argument. Flags are specified with symbolic integer constants, defined in <cl.h>. To specify more than one flag, use the "|" OR operator to OR the desired flags together into a single integer.

In addition to these standard arguments, some macros take additional arguments. For example, many macros let you establish a default setting for an option, or additional information to display in response to +HELP.

NOTE: When a macro accepts a "default" argument, the argument should be specified as a string (even if the default value is numeric). If you do not want to specify a default, specify NULL (standing for the null string pointer).

Option Flags:

The following symbols may be used as flags in the macros which create Option Table entries.

CL_ONCE

indicates that the corresponding option/argument may only appear once on the command line. If it appears more than once, the parsing routines generate an error message.

CL_REQUIRED

indicates that the corresponding option/argument must appear somewhere on the command line.

CL_IGNORE

indicates that the corresponding option/argument should be ignored during parsing. An entry is created in the Options Table (which means that the entry has a corresponding index), but the parsing routines otherwise ignore the presence of the entry.

CL_MERGE

is used when an option can have multiple supplied values, as in

=keyword value value value

The CL_MERGE flag indicates that if several of these options appear in the input, the lists of values should be merged into one long list. For example, if the command line contains

=keyword val1 val2  =keyword val3 val4

the parsing routines will treat this like

=keyword val1 val2 val3 val4

If you do not specify CL_MERGE, each list replaces the previous one, so you'll only get the last list on the input line.

CL_VAR_PARMS

is also used when an option can have multiple supplied values. In this case, the "num" argument of the macro defining the Options Table entry specifies the minimum number of values that can be supplied (rather than the exact number expected). The user must mark the end of the value list with "==".

CL_MULTIPLE

is equivalent to CL_MERGE and CL_VAR_PARMS.

CL_NONE

specifies no flags. This is equivalent to the integer zero.

Macro Descriptions:

The rest of this explain file summarizes the macros which can be used to create Options Table entries. For each macro, we list the following information:

Use:     format for invoking the macro
Matches: format of corresponding option/argument
Value:   how to obtain the value of the
         option/argument
Help:    format of usage information generated
         for the entry in response to +HELP

The Value line shows the prototype for a utility library macro that can be used to obtain the value of the option/argument. Such macros take two arguments:

cl: a parsed command line structure
index: an index indicating the Options Table entry whose value you want to determine

The descriptions also use one special piece of notation. When a macro argument is marked with a #, the macro will automatically enclose that argument in quotes to make it a string. You should not put in the quotes yourself, nor should you put in the # character; the # is simply used to mark this special situation.

Command Name:

Use:       CL_COMMAND( usage, #designator, flags )
Matches:   command
Value:     char *cl_string(cl,index)
Help:      designator -- usage

This matches the first argument on the command line, usually the command name itself. There should only be one active CL_COMMAND entry in the Options Table (although there may be others marked with CL_IGNORE). The specified designator is only used when outputting usage information; the parsing routines do not try to match the designator against the actual command name.

When a parsing routine outputs usage information, it always starts with the Help line for the CL_COMMAND entry.

Boolean Options:

Use:       CL_BOOLEAN( usage, #designator, flags, #default )
Matches:   +designator
Matches:   -designator
Value:     long cl_boolean(cl,index)
Help:      +designator   -- usage (flags) [default]

This creates an entry for a Boolean option: one that can take the form +keyword or -keyword. The keyword should be specified as the designator.

The default argument should either be a + or - character, indicating the default for the option if the user does not supply a setting on the command line.

The value returned by "cl_boolean" is 0 for -keyword and 1 for +keyword.

Single Unflagged Arguments:

Use:       CL_UNFLAGGED( usage, #designator, flags, default )
Matches:   arg
Value:     char *cl_string(cl,index)
Help:      designator  (on usage: line)

This matches any argument that does not look like an option. The designator is only used in the usage information, to indicate what kind of argument should be supplied; for example, you might specify FILE for the designator if the argument is expected to be a file name.

Unflagged arguments in the option table are matched in the order they appear on the command line. For example, if you expect the command line to specify an input file followed by an output file, you might created CL_UNFLAGGED entries for INFILE followed by OUTFILE.

The default argument should be the value used if the argument does not appear on the command line. It should be a string enclosed in quotes, even if the value of the argument is actually numeric.

As a special notation, users may put "==" in front of any command line argument they want to be taken as an unflagged argument. For example, suppose a file has the name "-blart"; since this has the format of a Boolean option, the parsing routines would normally interpret the argument as a Boolean option. However, the user could type

cmd ==-example

to indicate that "-example" was an unflagged argument, not an option. The parsing routine skips the "==" and then begins collecting the unflagged argument.

Keyword=String Options:

Use:       CL_STRING( usage, #designator, flags, default,
                      #parm_desc )
Matches:   =designator parameter
Matches:   designator=parameter
Value:     char *cl_string(cl,index)
Help:      =designator parm_desc  -- usage (flags) [default]

This matches any option that supplies a string value in connection with a keyword. The "cl_string" macro returns the string specified by the user.

The "parm_desc" argument is used in usage information output. For example, if you expect such an option to take the form "Keyword=filename", you might specify FILE as the "parm_desc" argument, so that the usage information indicates what kind of string value is required.

Keyword=Integer Options:

Use:       CL_NUMBER( usage, #designator, flags, default,
                      #parm_desc )
Matches:   =designator parameter
Matches:   designator=parameter
Value:     long cl_number(cl,index)
Help:      =designator parm_desc  -- usage (flags) [default]

This is similar to CL_STRING, except that the supplied value is expected to be an integer. The "cl_number" macro returns the integer value specified by the user.

As noted above, the default argument for CL_NUMBER (and other macros like CL_REAL, CL_MNUMBER, and so on) should be specified as a string, enclosed in quotes.

Keyword=Real Options:

Use:       CL_REAL( usage, #designator, flags, default,
                    #parm_desc )
Matches:   =designator parameter
Matches:   designator=parameter
Value:     double cl_real(cl,index)
Help:      =designator parm_desc  -- usage (flags) [default]

This is similar to CL_STRING, except that the supplied value is expected to be a floating point number. The "cl_real" macro returns the floating point value specified by the user.

Keyword=Code Options:

Use:       CL_SET( usage, #designator, flags, #default, range )
Matches:   =designator code
Matches:   designator=code
Value:     long cl_number(cl,index)
Help:      =designator key <-|range|  -- usage (flags) [default]

This type of entry is used for options of the form Keyword=Code, where the Code is itself a type of keyword which can be subject to normal abbreviation processes. For example, a command might accept either

Mode=Random   or   Mode=Sequential

In this case, the keyword is Mode and the codes are Random or Sequential.

The range argument should be a quoted string listing the possible values of the code. Codes should be given in standard format, using upper and lower case letters to show possible abbreviations. The codes in the list should be separated by space characters.

The "cl_number" macro indicates which code was actually supplied by the user by giving an index into the range list. The first code in the list has an index of zero.

If the user specifies a code that doesn't match any of the codes in the range list, the parsing routines consider it an error.

Multiple Unflagged Arguments:

Use:       CL_MUNFLAGGED( usage, #designator, flags, num,
                          default, #parm_desc )
Matches:   arg arg arg
Value:     char **cl_argv(cl,index)[0..<int cl_argc(cl,index)]
Help:      parm_desc ...  (on usage: line)

This gathers up a number of unflagged arguments into an argv/argc pair.

By default, the "num" argument tells how many unflagged arguments to gather; if "num" is 0, the parsing routines gather all the rest of the unflagged arguments remaining on the command line. The CL_VAR_PARMS flag is not effective with this macro.

The "cl_argv" macro returns a list of pointers, pointing to the unflagged arguments as strings. The "cl_argc" macro returns the number of arguments in this list.

Keyword Options with Multiple Values:

Use:       CL_MSTRING( usage, #designator, flags, num,
                       default, #parm_desc )
Matches:   =designator parm_1 ... parm_num
Matches:   =designator parm ... ==
Value:     char **cl_argv(cl,index)[0..<int cl_argc(cl,index)]
Help:      =designator parm_desc ... ==

This is similar to the case of multiple unflagged arguments. It creates an argc/argv pair, where the items in the "argv" are a list of strings specified as values for the keyword option.

If "num" equals zero, the value list may contain any number of values. Normally, the value list is assumed to go to the end of the line; if it does not, the user must mark the end of the list with two equal signs (==) before specifying other arguments on the command line.

Use:       CL_MNUMBER( usage, #designator, flags, num, default, #parm_desc )
Matches:   =designator parm_1 ... parm_num
Matches:   =designator parm ... ==
Value:     long **cl_numv(cl,index)[0..<int cl_argc(cl,index)]
Help:      =designator parm_desc ... ==

This is similar to CL_MSTRING, except that the list of values are integers instead of strings.

Use:       CL_MREAL( usage, #designator, flags, num, default, #parm_desc )
Matches:   =designator parm_1 ... parm_num
Matches:   =designator parm ... ==
Value:     double **cl_realv(cl,index)[0..<int cl_argc(cl,index)]
Help:      =designator parm_desc ... ==

This is similar to CL_MSTRING except that the list of values are floating point numbers instead of strings.

Subcommand Argument Lists:

Use:       CL_SUBCOMMAND( usage, #designator, flags, default )
Matches:   :arg arg arg
Value:     char **cl_argv(cl,index)[0..<int cl_argc(cl,index)]
Help:      :designator arg ...

This gathers all the arguments following the ":" into an argv/argc pair. This format is designed to let you specify a command line to pass onto another command.