As part of establishing a single Communicator library, we have provided copies of MIT functionality for command line argument parsing and printing. This documentation has been largely adapted from the MIT documentation, and we've included their copyright below.
program [options] [variable arguments]When a program is invoked, first options (if any) are specified, and then variable arguments (if any) are specified. Their is a finite set of options, and each option consists of a key (a string that starts with a `-') followed by a fixed number of arguments for that key. For example, an option might be "-copy from to". Here the key is -copy, and the two arguments are from and to. The variable arguments must appear after all options, and is just an arbitrarily long list of strings (often zero).
When a program is called with no online arguments, or with the -help option, it should print out a help line indicating its usage. If a user of this program gives too few or too many arguments to a given key, the program will do its best to detect this and signal some kind of warning or error.
The oas string contains one entry for each key (usually one entry per line, but not required), where an entry can have a variable number of strings. The first string in an entry is the key string, which contains the key and the arguments needed by the key, separated by spaces. The library determines how many arguments a key takes from this string. Next is the description of what the key does, to be used when printing out the usage line. This description should be succint and helpful. Following the description is a default string for each of the arguments of the key. These are the defaults that are to be used if the user doesn't specify the key on the command line. Each default can optionally be NULL, meaning that argument does not have a default. There must be as many default strings as there are arguments to the key. The oas string must be terminated with a single NULL in the slot where the next key would otherwise be.char *oas[] = {"-lex file", "the file containing the lexicon", "default.lex", "-subtract file1 file2", "remove the words in file2 from file1", NULL, NULL, "-set_weight N", "word weight", "5.0", "-disable", "turn off the default checking", NULL };
Before calling any other OA functions, the program should first call GalUtil_OACheckUsage(). This function checks first the programmer's usage in writing the oas list, and second the user's usage (i.e., whether the user used a key with too few arguments, or whether an extra argument was inserted between keys, etc). This function will print out the usage line, and return 0 if the usage failed, and return 1 otherwise. If it returns zero, the program should just exit (since GalUtil_OACheckUsage() will print the usage line). The function GalUtil_OaPrintUsage() prints the usage help line.
To actually extract arguments, use the function GalUtil_OAExtract(). This function takes arc, argv, and the oas list, followed by the key you'd like to extract, followed by pairs of a type specification, and a pointer to where the argument should be stored. For each argument of the key, oa_extract will set the variables according to the requested type. For example, using the above oas one could call:
GalUtil_OAExtract(argc, argv, oas, "-set_weight", GAL_OA_INT, &n);
To specify a description of variable arguments, use the special key "REST". This is the only legal key without a `-', and the OA library treats is specially.
int GalUtil_OACheckUsage(int
argc,
char **argv, char **oas, int *first_real_arg)
This function quickly looks through the
oas
list and through the actual online arguments specified, and verifies that
the usage is correct (to a first approximation). It checks that arguments
are not missing nor that there are extra arguments, and also verifies that
the oas list is formatted correctly. This function must be called once
at the start of the program before GalUtil_OAExtract(). If
first_real_arg
is non-NULL, this integer will be set to the argc of the first fixed argument.
The function returns 0 if there is an error and 1 if usage is correct.
void GalUtil_OAPrintUsage(int
argc,
char **argv, char **oas)
This function prints the help line of
the program. It should be called when the user has not called the program
properly.
int GalUtil_OAExtract(int
argc,
char **argv, char **oas, char *key, ... )
This function is used to extract the arguments
specified by the user. This function is called for a single key, and will
return the arguments of that key casted to a specific type. The number
of type/p_value pairs must be equal to the number of arguments specified
by the key. For example, for the key "-copy from to", there must be
two
pairs of type/value. The exception to this is a binary key (one with zero
arguments, for example "-debug"). In this case, GalUtil_OAExtract() takes
one pair of type/value, and it will set the value to be GAL_TRUE or GAL_FALSE
depending on whether the key was specified. This is just an alternative
to looking at the return value of GalUtil_OAExtract() to determine if the
user specified the key. If the user did not specify the key, then the values
are set to the defaults specified on the oas list. The allowed types are:
Memory management
GalUtil_OAExtract() does not allocate any memory, so when the type is GAL_OA_STRING the pointer will be exactly the corresponding argv.
void GalUtil_OAExtractAsserting(int
argc,
char **argv, char **oas, char *key, ... )
This is the same as the above, but it
aborts (exits) if the user did not specify the argument.
Whether or not the message passed to that function gets printed is determined at runtime by the user's GAL_VERBOSE environment variable, or by the -verbosity arguments of the Hub or server. This allows the user to have run time control over the number and nature of messages which get printed. Setting GAL_VERBOSE to 0 turns off all printing. Incrementing it by 1 turns on printing of additional message classes, until 6, at which point all printing is turned on. Increasing GAL_VERBOSE beyond 6 has no effect. The default verbosity is 3.
Note that MIT servers use the MIT equivalent of these facilities in places, and you should also set SLS_VERBOSE as well.
int GalUtil_SetVerbose(int
verbose_level)
This function sets the verbosity level
for the executable. It can be called at any time. It returns the new verbosity
level. Input values less than zero will be normalized to the default verbosity
of 3.
The following functions are available for increasing degrees of verbosity:
Note that GalUtil_Fatal() and GalUtil_Assert() will quit the program in addition to providing an error message.
void GalUtil_Warn(char *format, ... )
void GalUtil_Debug1(char *format, ... )
void GalUtil_Debug2(char *format, ... )In addition, there are two functions which allow the user to set a minimum verbose level.
void GalUtil_Print(int
level,
char *format, ... )
void GalUtil_CPrint(int
level,
int fore, int back, char *format, ... )
Prints in color or b/w if GAL_VERBOSE
exceeds level.
void GalUtil_VerboseUseBW(void
)
Print for a black and white xterm. Default.
void GalUtil_VerboseUseColor(void
)
Print for a color xterm.
Please send comments and suggestions to:bugs-darpacomm@linus.mitre.org
Last updated October 4, 2001.
Copyright (c) 1998 - 2001
The MITRE
Corporation
ALL RIGHTS RESERVED
Copyright (c) 1998
Spoken Language Systems Group
MIT Laboratory for Computer Science
ALL RIGHTS RESERVED