int QccParseParameters(int argc, char *argv[],
const char *format, ...);
int QccParseParametersVA(int argc, char *argv[],
const char *format, va_list ap);
QccParseParametersVA() functions indentically to QccParseParameters(), except that QccParseParametersVA() can be called from a function whose own argument list contains a variable number of arguments implemented via the variable-length argument facilities of stdarg(3) .
Optional parameters can be given in any order on the command line. QccParseParameters() will search through all optional-parameter specifications in format and store the value given on the command line in the location pointed to by the appropriate pointer. Note: if an optional parameter is not found on the command line, QccParseParameters() leaves the value pointed to by the pointer unchanged.
An optional parameter is specified in format in the following form: [-switch flag:name]
switch is the option that appears on the command line (preceded by a `-') to indicate the presence of the optional parameter.
name is an optional label for the value of the parameter; In the case of an error, name will be used to denote the value of the parameter in a usage statement.
switch and name can contain any sequence of characters, except `-', `%', `*', `[', `]', `:', `.', tabs, newlines, carriage returns, single quotes, double quotes, or spaces.
flag indicates the type of the parameter value. Possible flag values are given below.
A mandatory parameter is specified in format in the following form: flag:name
name is an optional label for the value of the parameter; In the case of an error, name will be used to denote the value of the parameter in a usage statement. name can contain any sequence of characters, except `-', `%', `*', `[', `]', `:', `.', tabs, newlines, carriage returns, single quotes, double quotes, or spaces.
flag indicates the type of the parameter value. Possible flag values are given below.
Once the command-line parameters given in argv are matched to the optional and mandatory parameters specified in format, QccParseParameters() uses sscanf(3) in conjunction with the flags above to convert the strings in argv to the appropriate types and to store the resulting values in the appropriate locations.
A multiple parameter is specified by using one of any of the flag values above with a `*' immediately after the `%' in the last mandatory parameter. For example, a %*d indicates that there may be one or more integer parameters given at the end of the command line.
For normal optional and mandatory parameters, QccParseParameters() expects a pointer to the appropriate type and that memory has already been allocated. On the other hand, for a multiple parameter, QccParseParameters() expects a pointer to int followed by a pointer to a pointer to the appropriate type. The number of multiple parameters found on the command line is stored in the integer; QccParseParameters() will automatically allocate an array of the appropriate size consisting of the appropriate number of entries of the appropriate type. For example, for a %*d multiple parameter will require a pointer of type (int *) followed by a pointer of type (int **) passed to QccParseParameters() in the variable-length argument list. QccParseParameters() will store the number of values found on the command line in the location pointed to by the first pointer and the values themselves in the array pointed to by the second pointer.
As described above, strings appearing on the command line are truncated to QCCSTRINGLEN characters; consequently, for the %*s multiple parameter, one passes a pointer of type (QccString **) to QccParseParameters().
See the examples below for some ideas as to how to use a multiple parameter.
If an error occurs during parsing, QccParseParameters() prints a usage statement (which is generated from the format string passed to QccParseParameters()), in addition to an message identifying the QccPack library (as produced by QccPrintQccPackVersion(3) ) and an optional user header (if so set by a call to QccSetUserHeader(3) ), and returns a value of 1. The following conditions will generate a parsing error:
Examples of various command lines and the corresponding program output are illustrated below. Note that the last two command-line examples generate error messages. The first of these error messages occurs because the mandatory parameter (filename) is missing. The second error message occurs because -h is not a valid option for the program.
#define USG_STRING "[-V %:] [-nl %d:num_levels] [-l %f:lambda] %s:filename"
int NumLevels = 10;
QccString Filename;
int Verbose = 0;
float Lambda = 4.5;
int main(int argc, char *argv[])
{
QccInit(&argc, argv);
if (QccParseParameters(argc, argv,
USG_STRING,
&Verbose,
&NumLevels,
&Lambda,
Filename))
QccErrorExit();
printf("Verbose: %d, NumLevels: %d\n",
Verbose, NumLevels);
printf("Lambda: %f, Filename: %s\n",
Lambda, Filename);
QccExit;
}
% prog file1.txt
Verbose: 0, NumLevels: 10
Lambda: 4.500000, Filename: file1.txt
% prog -V file1.txt
Verbose: 1, NumLevels: 10
Lambda: 4.500000, Filename: file1.txt
% prog -nl 123 file1.txt
Verbose: 0, NumLevels: 123
Lambda: 4.500000, Filename: file1.txt
% prog -l 11.5 -nl 123 file1.txt
Verbose: 0, NumLevels: 123
Lambda: 11.500000, Filename: file1.txt
% prog -l 11.5 -nl 123 -V file1.txt
Verbose: 1, NumLevels: 123
Lambda: 11.500000, Filename: file1.txt
% prog
QccPack Version X.X xx-xxx-xxxx,
Copyright (C) 1997, 1998 James E. Fowler,
*ERROR* Usage: prog [-V ] [-nl num_levels] [-l lambda] filename
% prog -h 45 file1.txt
QccPack Version X.X xx-xxx-xxxx,
Copyright (C) 1997, 1998 James E. Fowler,
*ERROR* Usage: prog [-V ] [-nl num_levels] [-l lambda] filename
Example output is#include "libQccPack.h"
#define USG_STRING "[-nl %d:num_levels] %*s:filenames..."
int NumLevels = 10;
int NumFiles;
QccString *Filenames;
int main(int argc, char *argv[])
{
int i;
QccInit(&argc, argv);
if (QccParseParameters(argc, argv,
USG_STRING,
&NumLevels,
&NumFiles,
&Filenames))
QccErrorExit();
printf("NumLevels: %d, NumFiles: %d\nFiles:\n",
NumLevels, NumFiles);
for (i = 0; i < NumFiles; i++)
printf("%s\n", Filenames[i]);
QccExit;
}
% prog -nl 123 file1.txt file2.txt file3.txt
NumLevels: 123, NumFiles: 3
Files:
file1.txt
file2.txt
file3.txt
Optional parameters can appear in any order in the format string; however, all optional parameters must appear before the first mandatory parameter.
QccParseParameters() does not do any type checking; that is, parameter values given in argv are not checked to see if they are "compatible" with the type definitions as implied by format.
When using presence indicators (a single % for flag), it is the responsibility of the calling routine to initialize the corresponding integer value to 0 before calling QccParseParameters(); that is, QccParseParameters() leaves the integer value unchanged if the optional parameter does not appear on the command line.
Any string of non-white-space characters in format that is not preceded by a `[' or a `%' is ignored.
QccInit(3) should be called as the first statement in the main() routine in all application programs using the QccPack library routines; in particular, QccInit(3) should be called before QccParseParameters(). See QccInit(3) for more details. In addition, if a user header is to be defined in the program, QccSetUserHeader(3) must be called before QccParseParameters().