# How to specify and use nested options for a function?

I want to write a function that takes options that are nested. For example, suppose the function has one main option, "method" which can take two values, "a" and "b". Also, when method is "a", it can take one sub-option, "depth", whereas, when the method is "b", the sub-option that can be specified is "totTime".

Basically, the options and suboptions that make sense are

method->"a", depth->5 or method->"b", totTime->10

One should not, for example, use the combination method->"a", and totTime->10.

One way to deal with this is

In[53]:= Options[f] = {method -> "a", depth -> 5, totTime -> 10}

Out[53]= {method -> "a", depth -> 5, totTime -> 10}

f[x_, OptionsPattern[]] :=
Module[
{},
If[OptionValue[method] == "a", {x, OptionValue[method],
OptionValue[depth]},
{x, OptionValue[method], OptionValue[totTime]}
]
]

We get proper output, despite "wrong" input

In[59]:= f[2, method -> "b", depth -> 6]

Out[59]= {2, "b", 10}

In[60]:= f[2, method -> "a", totTime -> 2]

Out[60]= {2, "a", 5}

However, the above set of options that the user specifies in the input to the function do not make sense as the sub-option, depth is not related to method "b". How can one make sure that the user does not enter nonsensical combinations of options and sub-options, without relying solely on the documentation.

I am looking for a method that works even if there are a ton of options and sub-options. That is, Ideally, I do not want to write a huge number of warnings saying that different combinations do not make sense. Someway to nudge the user toward proper input (e.g., sublists) would be useful.

• Do your default Options specified in In[53] not contradict your requirement that "method->"a", and totTime->10" are not allowed? The reason In[60] returns {2,"a",5} is that you've provided the default value of 5 for "depth". Aug 12 '15 at 21:37

You can do this by moving method from an option to a parameter and explicitly listing the options in OptionsPattern. With this approach Options is not used.

ClearAll[f]

f[x_, method : "a", OptionsPattern[{depth -> 5}]] :=
{x, method, OptionValue[depth]}

f[x_, method : "b", OptionsPattern[{totTime -> 10}]] :=
{x, method, OptionValue[totTime]}

This creates two definitions on the symbol f that will match to the named method pattern in the parameter list. You can add additional options to OptionsPattern.

f[2, "a", depth -> 2]
(* {2, "a", 2} *)

f[2, "a", totTime -> 2]
OptionValue::nodef: Unknown option totTime for {depth->5}. >>
(* {2, "a", 5} *)

f[2, "b", totTime -> 2]
(* {2, "b", 2} *)

f[2, "b", depth -> 2]
OptionValue::nodef: Unknown option depth for {totTime->10}. >>
(* {2, "b", 10} *)

An error is thrown when an incorrect option is supplied for a particular method. However, f still returns a result in these cases. I'm not certain on how to get the function to abort when there is an error in its OptionsPattern match.* In any case the error will prompt the user to look at the parameters.

If there is a lot of shared code between the two methods then I would suggest a private function to hold this code that both versions of f can call separate from the option specific bits.

Hope this helps.

* That can be done, a bit baroquely, like this:

ClearAll[f]

f[x_, method : "a", OptionsPattern[{depth -> 5}]] :=
With[{body =
Check[
{x, method, OptionValue[depth]},
$Failed, OptionValue::nodef ] }, body /; body =!=$Failed
]

f[x_, method : "b", OptionsPattern[{totTime -> 10}]] :=
With[{body =
Check[
{x, method, OptionValue[totTime]},
$Failed, OptionValue::nodef ] }, body /; body =!=$Failed
]

Or more cleanly using the undocumented functionality of Fail and RuleCondition:

ClearAll[f]

f[x_, method : "a", OptionsPattern[{depth -> 5}]] :=
Check[
{x, method, OptionValue[depth]},
Fail,
OptionValue::nodef
] // RuleCondition

f[x_, method : "b", OptionsPattern[{totTime -> 10}]] :=
Check[
{x, method, OptionValue[totTime]},
Fail,
OptionValue::nodef
] // RuleCondition

Test:

f[2, "b", depth -> 2]
OptionValue::nodef: Unknown option depth for {totTime->10}. >>

f[2, "b", depth -> 2]
• @Mr.Wizard Very nice enhancement. Any chance WRI will promote these to the documentation? Aug 12 '15 at 22:35
• I think it wouldn't hurt to ask, but I suspect that if they were going to they would have done so by now. Aug 12 '15 at 23:03

Many built-in functions use a Method option, and suboptions are given within that option, nested, rather than flat as in your examples. The value of Method is extracted and processed, e.g. with ChartingConstructMethod and ChartingparseMethod, then used as needed. I suggest that you do something similar. Simplistically:

Options[f] = {method -> {"a", depth -> 5}};

f[x_, OptionsPattern[]] :=
Module[{mv = OptionValue[method]},
Check[
Switch[First @ mv,
"a", OptionValue[Rest @ mv, depth],
"b", OptionValue[Rest @ mv, totTime]
],
$Failed, OptionValue::optnf ] ] Now: f[2, method -> {"a", depth -> 6}] f[2, method -> {"b", totTime -> 2}] 6 2 f[2, method -> {"b", depth -> 6}] f[2, method -> {"a", totTime -> 2}] OptionValue::optnf: Option name totTime not found in defaults for {depth->6}. >>$Failed