|
|
| int cmdparams_parse |
( |
CmdParams_t * |
parms, |
|
|
int |
argc, |
|
|
char * |
argv[] | |
|
) |
| | |
Parse the command line and the module's default arguments structure, creating and populating a hash table, indexed by argument name, that contains all the arguments specified. All values in the hash table are strings, regardless of the declared type of the argument. Parsing proceeds as follows:
1. All tokens after the first in the command line (argv) are parsed for flags, argument name-value pairs, file references ( in the table below - the file contains arguments, which are then parsed as well), or unnamed values.
Command-line tokens can take any of the following forms:
| --name | 'name' is the multi-byte name of a flag. If this token is present on the command-line, the flag named 'name' is 'set'. cmdparams_isflagset(parms, "name") will return 1. name cannot begin with a digit |
| --name value | 'name' is the name of an argument, and 'value' is the value of that argument. cmdparams_get_XXX() will convert the string value to the desired type and return that value. 'name' cannot begin with a digit. |
| -<chars> | <chars> is a set of one or more characters. If such characters are present on the command-line, then the flags named by each of those characters are 'set'. |
| name=[]value | 'name' is the name of an argument, and 'value' is the value of that argument. 'name' cannot begin with a digit. White space following the = is optional |
| @filename | 'filename' specifies the name of a file containing tokens to be parsed in the same way the cmd-line is parsed. |
| value | unnamed values are also stored in the hash table. They can be accessed by providing the argument number to the API functions (eg., if 'value' is the value of the nth argument, then that value can be accessed by providing n as the argument number, as in cmdparams_getarg(parms, n)). |
2. The declared module_args structure provides a mechanism for declaring, in module code, the arguments expected to appear on the cmd-line. The declaration includes the argument data type and its default value, among other attributes (see module_args), although cmdparams uses these attributes inconsistently (different argument types make use of different sets of these attributes). Arguments provided on the cmd-line, but not in module_args, should be ignored by the module code. After parsing the cmd-line, cmdparams then checks the module_args to ensure that all arguments specified in module_args were indeed provided on the cmd-line. Should an argument be missing, cmdparams assigns the default value to the argument. If an argument is missing and no default value is provided in module_args, cmdparams issues a fatal error (with an exception for the ARG_FLAG type - see table below). Arguments without default values are required to be specified on the cmd-line. NOTE: most of the type declarations are meaningless (eg., ARG_INT, ARG_DOUBLE) as cmdparams stores arguments in their string form, and only converts to a numerical type when a cmdparams_get_XXX() function is called. A few of the type declarations do have meaning:
| ARG_FLAG | Flags are not subject to the requirement that a default value be provided in the module_args structure. This means that flags cannot be made to be required arguments. It also means that specifying a default value for a flag has no effect. To query if a flag is set, cmdparams_isflagset() can be used. |
| ARG_NUME | The range field of module_args specifies a comma-separated list of acceptable enumeration ids. Each id in the list is associated with an integer (the enumeration value, which starts at 0 for the first value in the list, and then increases by 1 for each successive item in the list). If the range field includes "myid1, myid2, myid3", then myid1 is associated with 0, myid2 is associated with 1, and myid3 is associated with 3. To obtain the value of an ARG_NUME argument, call cmdparams_get_int(). The value returned is the enumeration value. Putting this all together, if the range field of the color argument contains "red,orange,yellow,green,blue,purple", and the cmd-line contains color=green, cmdparams_get_int() returns 3, because the id red is associated with the value 0, orange is associated with 1, etc. cmdparams will fail if the cmd-line specifies a value for an ARG_NUME argument that is not in the list specified in the range field (eg, color=aqua will cause a failure). This argument type is designed especially for use with driver programs that can provide menus of options, such as CGI forms. |
| ARG_FLOATS, ARG_DOUBLES, ARG_INTS | The cmd-line for an argument of this type contains a comma-separated list of values. cmdparams will parse this list and store each value in the hash table under the name <argname>_<n>_value, where <argname> is the name of the argument in module_args and <n> is the 0-based index into the list. The number of elements in the original list is stored in a new hash-table item keyed by the string <argname>_nvals. For example, if "lat=0.0,5.0,10.0" is provided on the cmd-line, and the following module_args element is present: {ARG_FLOATS, "lat", "", "", ""}, params_get_int (params, "lat_nvals") would return 3 and params_get_float (params, "lat_1_value") would return the value 5.0 . The number of array values supplied at run time need not match the number in the speficied in the value field of the module_args element. In addition, an entire array of values in their specified type is stored (if the type of argument is ARG_INTS, then the values are stored as ints - NOT as strings). To obtain this array, cmdparams_get_intarr(), cmdparams_get_flaotarr(), or cmdparams_get_doublearr() can be used. |
| ARG_FLOAT, ARG_DOUBLE, ARG_INT | The range field of module_args specifies a range of acceptable values. Should a cmd-line value for this argument be provided that is not within this range, cmdparams fails with an out-of-range error. The range is a string with the following grammar (curlies denote optional elements, single quotes denote literals, '|' denotes alternation):
{ '(' | '[' } { <number1> } ',' { <number2> } { ')' | ']' }
() denote open endpoints, [] denote closed endpoints (default is closed), <number1> and <number2> are a real numbers, the lower and upper endpoints of the range. If <number1> is omitted, then -infinity is assumed. If <number2> is omitted, then +infinity is assumed. |
If any declared module argument (in module_args) cannot be assigned a value during the above process, processing of the argument list ceases and the function returns the value -1. ARG_FLAG arguments are exempt from this rule - it is not a requirement that processing results in any flag to be set.
If a parameter value (or name) has embedded white space, it must be quoted.
An extern module_args declaration is required, though it can be empty. A member with a module_args.type of ARG_END, must terminate the the list of parsed members; any members following it in the declarator will be ignored.
- Bug:
- Multiple assignments to a given parameter name could result in unpredictable values. The last token in the command line should be parsed last and take precedence. Thus, for example, an assignment following an @filename declaration will supersede the assignment in the corresponding file, and vice versa
- Bug:
- Parsing of tokens in included files does not properly deal with embedded white space in quoted strings.
Definition at line 1132 of file cmdparams.c.
|
