prog::getOptions

Get and verify options within a procedure

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

prog::getOptions(n, arguments, allOptions, <ErrorOnUnexpected>, <optionTypes>)

Description

prog::getOptions called within a procedure collects and verifies all options from the list of arguments of the calling procedure.

When you write your own procedure, prog::getOptions lets you embed the collection and verification of all options of the procedure. When a user calls your procedure, prog::getOptions scans all the arguments and provides a data structure that contains all option values. See Example 1.

The prog::getOptions function returns a list that contains a table of all valid options along with their values and a list of unexpected arguments. For expected options, prog::getOptions returns the following values:

If an option can have only TRUE or FALSE values, a user of your procedure can provide the option name, instead of providing an option-value pair. If a user provides an option without specifying its value, prog::getOptions returns the Boolean value TRUE for that option. See Example 2.

prog::getOptions returns a list with two components: a table of expected options and a list of unexpected arguments. You can access the components of that list separately by using the index operator (see _index). See Example 3.

By default, the prog::getOptions function does not error when it finds an unexpected argument. To switch to issuing errors on unexpected arguments, use the parameter ErrorOnUnexpected. See Example 4.

The procedure that includes prog::getOptions must accept the arguments in the following order: first nonoptional parameters, and then all options. The prog::getOptions function lets you specify the number n of the argument from which the function starts verifying options. The prog::getOptions function assumes that the first n - 1 arguments are parameters and, therefore, does not verify them. See Example 5.

The parameter optionTypes lets you specify acceptable types for the option values. You can specify acceptable types for some or all of the expected options provided in the allOptions table. See Example 6.

The first three parameters of prog::getOptions (n, arguments, and allOptions) are required. ErrorOnUnexpected and optionTypes are optional. You must provide the parameters of prog::getOptions using the order shown in the Calls section of this page. Therefore, if you want to use the fifth parameter optionTypes, you also must explicitly use the fourth parameter ErrorOnUnexpected.

The second parameter of the prog::getOptions function, arguments, is a list of all arguments of your procedure. prog::getOptions scans the arguments provided in that list. Although prog::getOptions accepts any list as a second argument, the calling procedure always must provide a list of all its arguments (both parameters and options) to avoid potential errors. The syntax [ args()] provides a list of all arguments of the calling procedure. See Example 7.

Examples

Example 1

To embed the option collection and verification step into your procedure, call prog::getOptions function within that procedure. To test the behaviour of prog::getOptions, create a function f that calls prog::getOptions to scan and verify the arguments of f. For example, create the function f that accepts only one option All:

f := () -> prog::getOptions(1, [args()], table(All = TRUE)):

prog::getOptions returns a list. The first entry of the list is a table containing all expected options and their values. The second entry is a list of unexpected arguments. For example the function call f() does not contain any unexpected arguments:

f();

The function call f(Unexpected) contains the unexpected argument Unexpected:

f(Unexpected);

Example 2

When users call the procedure that includes prog::getOptions, they can specify new values for any of the valid options of that procedure. In this case, prog::getOptions returns the new values. If a user uses the option without specifying its value, prog::getOptions returns the Boolean value TRUE for that option. If a user does not explicitly use an expected option, prog::getOptions returns the default value of that option provided in the allOptions table. For example, in the function call f(Proc = op, Warning), the prog::getOptions function returns the following values:

  • If a user provides a value for the option, prog::getOptions returns that value.

  • If a user does not use the option in a procedure call, prog::getOptions returns the default value for that option.

f := () -> prog::getOptions(1, [args()],
                               table(All = FALSE,
                                     Proc = id,
                                     Warning = FALSE))[1]:
f(Proc = op, Warning)

Example 3

To access the table of expected options and the list of unexpected arguments separately, use the index operator (see _index):

f := () -> prog::getOptions(1, [args()],
                                  table(All = TRUE))[1]:
g := () -> prog::getOptions(1, [args()],
                                  table(All = TRUE))[2]:
ExpectedOptions = f(Unexpected);
UnexpectedOptions = g(Unexpected)

Example 4

When a user supplies unexpected arguments to your procedure, prog::getOptions can collect these arguments and return them as a list. Also, prog::getOptions can stop and issue an error when it finds the first unexpected argument. To issue an error instead of listing unexpected arguments, use TRUE as the fourth parameter of prog::getOptions:

f := () -> prog::getOptions(1, [args()], table(All = TRUE), TRUE):
f(Unexpected)
Error: The argument number 1 is invalid.
  Evaluating: f

Example 5

The prog::getOptions function does not distinguish parameters from options automatically. If some arguments of a procedure are parameters, exclude them from option verification. Otherwise, the prog::getOptions function lists those parameters as unexpected arguments. For example, prog::getOptions lists 1 and 2 as unexpected arguments of the function call f(1, 2, All):

f := () -> prog::getOptions(1, [args()], table(All = TRUE))[2]:
UnexpectedOptions = f(1, 2, All);

If you set the prog::getOptions function to error on unexpected arguments, it will error on the parameters too:

f := () -> prog::getOptions(1, [args()], table(All = TRUE), TRUE):
f(1, 2, All);
Error: The argument number 1 is invalid.
  Evaluating: f

To exclude first n parameters of a function from option verification, provide the number n + 1 as a first argument of prog::getOptions. In a function call, specify all n parameters before you specify options. For example, to avoid checking the first two arguments in the function call f(1, 2, All), use the following syntax:

f := () -> prog::getOptions(3, [args()], table(All = TRUE))[2]:
UnexpectedOptions = f(1, 2, All);

When you use prog::getOptions, you must provide all nonoptional parameters first, and then provide the options. The following syntax does not work because prog::getOptions assumes that the first two arguments in the function call f(1, All, 2) are parameters, and the number 2 is an option:

f := () -> prog::getOptions(3, [args()], table(All = TRUE), TRUE):
f(1, All, 2);
Error: The argument number 3 is invalid.
  Evaluating: f

Example 6

To specify acceptable types of the option values, use a table that contains acceptable options as indices and their expected types as entries. For example, specify that the All option must be of the type DOM_BOOL, and the Proc option must be of the type Type::Function:

f:= () -> prog::getOptions(1, [args()],
                              table(All = TRUE, Proc = id),
                              TRUE,
                              table(All = DOM_BOOL,
                                    Proc = Type::Function)
                              )[1]:

Now, options can have only values of the correct types:

f(All = FALSE, Proc = id)

If you try to use a value of the wrong type, the function issues an error:

f(All = FALSE, Proc = 0)
Error: The type of argument number 2 is incorrect.
  Evaluating: f

Also, you can define and use a procedure for performing the type check. For arguments of the valid type, the procedure must return TRUE or an expression that can be evaluated to TRUE by the bool function:

f := () -> prog::getOptions(
                    2, [args()],
                    table(File = ""), TRUE,
                    table(File = (X -> contains({DOM_STRING,
                                                 DOM_INT},
                                                 type(X))))
                           )[1]:
f(FALSE, File = 0), f(TRUE, File = "test.log")

Example 7

Using arguments to separate options from parameters is not recommended because it can lead to errors. Always use the first parameter of prog::getOptions to specify how many parameters you have. Although prog::getOptions accepts any list as a second argument, the best practice is to use only args(). The following example demostrates that using arguments to separate options from parameters can result in the wrong error message. Although this error message correctly indicates that one of the options has a value of the wrong type, the index of the argument is wrong:

f := () -> prog::getOptions(1, [args(2..args(0))],
                            table(Option1 = TRUE), 
                            TRUE,
                            table(Option1 = DOM_BOOL)):
f(x, Option1 = 1, Option2)
Error: The type of argument number 1 is incorrect.
  Evaluating: f

To get the correct error message for this example, use the first parameter of prog::getOptions to exclude x from option verification:

f := () -> prog::getOptions(2, [args()], table(Option1 = TRUE), 
                            TRUE, table(Option1 = DOM_BOOL)):
f(x, Option1 = 1, Option2)
Error: The type of argument number 2 is incorrect.
  Evaluating: f

Parameters

n

A positive integer that specifies the number of the first option in the list of arguments. When calling the procedure, a user must provide all nonoptional paramaters before the options.

arguments

A list of all arguments of the procedure. Use args() to access all arguments.

allOptions

A table that contains all acceptable options as indices and their default values as entries: table(Option = defaultValue)

ErrorOnUnexpected

A Boolean constant TRUE or FALSE. If the value is TRUE, prog::getOptions issues an error when it finds an unexpected argument. If the value is FALSE, prog::getOptions collects all unexpected arguments and returns them as a list. By default, ErrorOnUnexpected = FALSE.

optionTypes

A table that contains acceptable options as indices and their expected types as entries: table(Option = optionType). Here optionType must be a valid second argument of the testtype function or a procedure that returns TRUE (or an expression that can be evaluated to TRUE by the bool function) for arguments of the valid type. If you want to specify optionTypes, you also must explicitly specify ErrorOnUnexpected.

Return Values

List that contains a table and a list. The table contains all valid options of the calling procedure and their values. For expected options that are not specified in the procedure, the values are their default values. The list contains all unexpected arguments in the procedure.

See Also

MuPAD Functions

Was this topic helpful?