ProcessOptions - validate optional arguments passed to a Maple procedure
|
Calling Sequence
|
|
ProcessOptions(nSkip, ArgList, Defaults, Values)
|
|
Parameters
|
|
nSkip
|
-
|
integer; number of elements to skip over in ArgList
|
ArgList
|
-
|
list; arguments to validate
|
Defaults
|
-
|
table; types and default values for all optional parameters
|
Values
|
-
|
table; on exit, contains an entry for each optional parameter which was either specified by the user or for which a default value is provided in the Defaults table
|
|
|
|
|
Description
|
|
•
|
The ProcessOptions function is used to validate optional arguments to a Maple procedure, and assign default values to optional parameters that are not provided. A expression sequence consisting of the elements of ArgList which were not processed is returned. The Values parameter is updated with a value for each expected optional parameter.
|
•
|
ProcessOptions separates parameters into three groups:
|
|
1. Required data parameters: These parameters provide data necessary for the procedure to function at all. These parameters must come before any optional parameters, and are not generally validated by ProcessOptions. (These parameters can be at least partially validated via parameter type checking.) nSkip should be set to the number of these parameters.
|
|
2. Optional data parameters: These parameters provide additional data for the procedure. They are generally positional and anonymous. That is, their meaning is deduced from the order of their occurrence in the list of all optional parameters. The Defaults table provides types and possibly default values for these parameters via the sub-table Defaults[PositionalParms].
|
|
3. Options: These parameters provide control information for the operation of the procedure. They are generally named (i.e., they are given in the form option_name = option_value, or they can simply be names (i.e., option_name, which are interpreted as setting the corresponding Boolean parameter to true. In both cases, types and possibly default values for these parameters are provided via the sub-table Defaults[OptionParms].
|
•
|
Templates for parameter validation are provided in the Defaults table. This table must have two sub-tables, called OptionParms and PositionalParms. The entries in the OptionParms sub-table must be of one of the forms
|
option_name = [default_value, type, 'makelist']
|
option_name = [default_value, type]
|
option_name = [type, 'makelist']
|
option_name = [type]
|
|
|
|
Entries in the PositionalParms subtable must be of one of the forms
|
n = [default_value, type]
|
n = [type]
|
|
|
|
where n indicates the number of this parameter in the list of positional parameters.
|
|
In the OptionParms sub-table, the type BooleanOpt(t) can be used to recognize a Boolean valued parameter named t, which may be given simply as t or as t = true or t = false. See type[BooleanOpt].
|
|
In the OptionParms sub-table, the keyword makelist indicates that the corresponding parameter right hand side is normally a list, but if it would be a list containing only a single entry then the list brackets can be left off; ProcessOptions will add the list brackets before assigning the value to the Values table (the type specification would have to be set accordingly).
|
•
|
The first nSkip elements of ArgList are skipped over before processing begins. Next, each of the remaining elements of ArgList is then checked to see if it matches an entry in the OptionParms sub-table of the Defaults table. If it does, the corresponding entry in the Values table is set accordingly. If no match is found, the element is checked to see if it matches the type of the next entry in the PositionalParms table. Again, if it does, Values is updated. Finally, if no match is found in either sub-table, the element is considered unrecognized and left undigested. After all elements of ArgList have been scanned, Values is checked to see that it has a value assigned for each index entry in the Defaults[OptionParms] and Defaults[PositionalParms] sub-tables. Any values not so assigned for which the corresponding sub-table entry specifies a default value are set accordingly.
|
•
|
ProcessOptions returns any undigested elements as an expression sequence, which generally should be NULL for proper functioning of the calling routine. (These can be echoed in an error message by using the %0 format control.)
|
|
|
Examples
|
|
>
|
|
>
|
MyProc := proc(x :: algebraic )
local Options, num_reqd;
Options := table();
num_reqd := 1;
ProcessOptions( num_reqd, [args], Defaults, Options );
if not assigned( Options[2] ) then
Options[2] := Options[1];
end if;
<continue with routine>
end proc;
|
In this example, the value of the second positional parameter is set to that of the first positional parameter if at most one positional parameter is provided. If the select parameter is given as select = x, where x is of type symbol, then Options[select] = [x] on return from ProcessOptions().
|
|