PARSER - parsing routines in the C utility library.

The parsing routines of the C utility library help you parse command lines and input whose structure is comparable to command lines. Input should begin with the command name, followed by a list of arguments and/or options, separated by white space. For the purposes of these routines, white space consists of one or more space and/or horizontal tab characters. The input ends with the first new-line encountered.

The parsing routines make use of the standard Thinkage abbreviation conventions. Within the program, option keywords are represented with some characters in upper case and some characters in lower case, as in "KeyWord". Some or all of the letters shown in lower case may be omitted by the user in the interest of abbreviation. For example, if the program source code specifies "KeyWord", users entering input to that program could supply any of the following:

keyword
keywd
kwd
kw

and many other variations.

User input may be specified in upper, lower, or mixed case; the parsing routines ignore the case of letters. For example,

KW    kw    Kw    kW

are all valid matches for "KeyWord".

The Options Table:

The parsing routines make use of an Options Table to describe the options and arguments accepted on an input line. Inside a program, 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.

Entries in the table are indexed with integers, beginning with zero for the first entry. For example, Entry 0 might describe the expected form of the command name, while Entries 1-3 describe three possible options for that command. To determine whether the option described by Entry 2 was actually present in a parsed command line, you would use an appropriate parsing routine to query Entry 2 of the parsing table.

To make your program more understandable, you should define symbolic constants for each entry index in the Options Table. The names of these constants should reflect the nature of the corresponding table entry. You can create these constants either through #define directives or by declaring an enumerated class of constants. For example, you might define

enum {
    OP_COMMAND, OP_OPT1, OP_OPT2, OP_OPT3
};

for a command line that begins with a command name and may have three possible options.

The macros defining an Options Table should appear in a location where data objects may be defined. Typically, this will be outside the scope of any function.

Parsing a Command Line:

Once you have defined an Options Table, you can use it to parse a command line. The standard function for parsing a command line is "cl_parse", with the prototype

CL_PARSED *cl_parse( int argc, char **argv,
      CL_DESCRIPTION *optabname);

The "argc" and "argv" arguments are the standard ones passed as arguments to the "main" function of your program. The "optabname" argument is the name of a defined Options Table.

The result of "cl_parse" is a data structure containing the information obtained from the command line. This information is stored in a format that can be queried easily by various parsing functions.

The +HELP Option:

In addition to the options and arguments described in the Option Table, the parsing routines also allow let the user enter

command +HELP

+HELP tells the parsing routines to display "Usage information", giving the expected format of the command line and the options/arguments accepted on the command line. You supply this usage information at the time you create the Options Table.

The parsing routines recognize -HELP as a synonym for +HELP. However, all parsing routine documentation uses +HELP as the standard form.

PARSER - parsing routines in the C utility library.

The Options Table:

Parsing a Command Line:

The +HELP Option:

See Also: