Table of Contents

NAME

QccParseParameters - parsing of command-line parameters

SYNOPSIS

#include "libQccPack.h"

int QccParseParameters(int argc, char *argv[], const char *format, ...);
int QccParseParametersVA(int argc, char *argv[], const char *format, va_list ap);

DESCRIPTION

QccParseParameters() parses the command-line parameters passed to it via argc and argv according to a format string. Pointers, which follow format and are accessed via the variable-length argument facilities of stdarg(3) , point to the storage locations for values of the parsed parameters; the composition of format describes the type and sizes of these parameter values.

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) .

FORMAT STRING

format is a null-terminated string that specifies the sequence of expected command-line parameters. The format string consists of the specification of zero or more optional parameters followed by the specification of zero or more mandatory parameters.

OPTIONAL PARAMETERS

The normal usage of an optional-parameter specification in format is to denote that a switch may appear on the command line followed by a value (e.g., -num_levels 32 or -filename foo.bar). An optional parameter is specified in the format string by giving the switch expected on the command-line (e.g., -num_levels, -filename), and indicating the type (float, int, etc.) of the value associated with the switch. It is assumed that the corresponding pointer (in the variable-length argument list that follows format) points memory that is already allocated in the size needed to accommodate the storage of a value of the specified type.

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.

MANDATORY PARAMETERS

Whereas optional parameters may or may not appear on the command line, the presence of mandatory parameters is required. The specification of all mandatory parameters must follow that of all optional parameters in format. The mandatory parameters must appear on the command line in exactly the order that they are specified in format or an error will be generated.

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.

FLAGS

Possible flag values for both optional and mandatory parameters are as follows:
%d
optionally signed integer. The corresponding pointer must be a pointer to int.
%u
unsigned integer. The corresponding pointer must be a pointer to unsigned int.
%f, %e, %g
optionally signed floating-point number. The corresponding pointer must be a pointer to float.
%s
a sequence of non-white-space characters. The corresponding pointer must of type QccString (i.e., a pointer to char) and the array must be large enough to accept the whole sequence plus the terminating NULL character (i.e., QCCSTRING + 1 characters long). Strings appearing on the command line (i.e., in argv) are truncated by QccParseParameters to a maximum length of QCCSTRINGLEN characters; consequently, it is safe to pass a variable of type QccString (see QccConvertToQccString(3) ) to QccParseParameters() without fear of a buffer overrun.
%
presence indicator. The presence indicator, a single % as flag, is valid only for optional parameters and indicates merely whether the optional parameter was found on the command line; there is no value associated with the parameter. Instead, a pointer to int must be given in the variable-length argument list. Upon return of QccParseParameters(), this integer value will be set to 1 if the optional parameter appears on the command-line; otherwise, it is left unchanged. name is normally not specified for presence-indicator arguments.

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.

MULTIPLE PARAMETER

The last mandatory parameter may be a multiple parameter. A multiple parameter allows the user to specify one or more parameters of the same type at the end of the command line. QccParseParameters() will figure out how many parameters are specified; the number of parameters, as well as an array of the parameter values, is returned to the calling routine via the variable-length argument list. For example, a multiple-parameter designation is useful for allowing the user to specify a list of files without restricting the number of these files.

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.

RETURN VALUE

For a successful parsing of the command line, QccParseParameters() returns a value of 0; all parameter values are returned in the locations indicated by the corresponding pointers.

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:

  1. A mandatory parameter is specified in format but is not found on the command line.
  2. An optional parameter is given on the command line but its switch is not found in format.
  3. An optional parameter requires a value to follow the switch (such as %d or %s) but no value is present on the command line.

EXAMPLES

Assume that each of the following code segments is in the file prog.c which produces executable prog.

TYPICAL USE

The typical use of QccParseParameters() is illustrated below.

#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;
}

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.

% 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

MULTIPLE-PARAMETER EXAMPLE

The following code shows how to use the multiple-parameter capability of QccParseParameters() to parse a list of files where the number of files can vary. QccParseParameters() automatically handles the allocation of the array of strings of type QccString, where each string in the array is allocated to size (QCCSTRINGLEN + 1) characters.

#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;
}

Example output is

% prog -nl 123 file1.txt file2.txt file3.txt
NumLevels: 123, NumFiles: 3
Files:
file1.txt
file2.txt
file3.txt

NOTES

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().

SEE ALSO

QccConvertToQccString(3) , QccInit(3) , QccPrintQccPackVersion(3) , QccSetUserHeader(3) , sscanf(3) , QccPack(3)

AUTHOR

Copyright (C) 1997-2021 James E. Fowler


Table of Contents



Get QccPack at SourceForge.net. Fast, secure and Free Open Source software downloads