Let us assume that you are designing a function which can take its own unique options, but also shares option names with Plot
. What is the best way to implement such a function myPlot
? Below I will try to give a complete guide on how to do this.
There are two common approaches:
The default values for Plot
-specific options will be taken directly from Plot
. Changing Plot
options with SetOptions
also affects myPlot
. It is not possible to use SetOptions
on myPlot
with Plot
-specific options. This is only possible with options unique to myPlot
.
myPlot
has its own copy of Plot
's options. Changing Plot
's options does not affect myPlot
. Any of these options can be changed directly on myPlot
using SetOptions
.
Most builtin functions use approach (2).
For the following, it is good to be aware that when an option is specific multiple times, Mathematica always takes the first value.
Inheriting defaults from Plot
Here's how to implement approach (1). We start by setting the defaults of myPlot
's unique options:
Options[myPlot] = { Top -> 10 };
myPlot[f_, opt : OptionsPattern[{myPlot, Plot}]] :=
Plot[f[x], {x, 0, OptionValue[Top]},
Evaluate@FilterRules[{opt}, Options[Plot]]
]
Here, the purpose of specifying Plot
within OptionsPattern
was to avoid error messages when using options that are present in Options[Plot]
but not in Options[myPlot]
.
An additional effect is that now you can use OptionValue
with Plot
-specific options. We do not need this in this specific implementation. However, specifying Plot
within OptionsPatter
is still necessary to avoid errors.
Using Evaluate
before FilterRule
was necessary because Plot
is HoldAll
.
If you put this function in a package, at some point you may want to add syntax information to it. Like this:
SyntaxInformation[myPlot] = {"ArgumentsPattern" -> {_, OptionsPattern[]}}
But now we run into a problem. Plot
-specific options work, but they are coloured in red, as if they were incorrect.
The workaround is using an undocumented entry in SyntaxInformation
, "OptionNames"
:
SyntaxInformation[
myPlot] = {"ArgumentsPattern" -> {_, OptionsPattern[]},
"OptionNames" -> Union[First /@ Options[myPlot], First /@ Options[Plot]]};
Separate defaults for myPlot
and Plot
This is the more common approach, and this is what builtins use.
We start by setting myPlot
's unique options, as well as copying over Plot
's options. Here, we do not change Plot
's defaults.
Options[myPlot] = Join[
Options[Plot],
{Top -> 10}
];
Now we are ready to change some Plot
-specific options from their default values:
SetOptions[myPlot, {PlotRange -> All, PlotStyle -> Red}];
Now we can define myPlot
:
myPlot[f_, opt : OptionsPattern[]] :=
Plot[f[x], {x, 0, OptionValue[Top]},
Evaluate@FilterRules[Join[{opt}, Options[myPlot]], Options[Plot]]
]
We no longer need to list function names in OptionsPattern[]
. But now we need to pass down all options, as set either in opt
or in Options[myPlot]
to the Plot
function. We can simply Join
all of them together, relying on the fact that when duplicates are present, the value will be taken from the first occurrence.
Now the SyntaxInformation can be simpler:
SyntaxInformation[myPlot] = {"ArgumentsPattern" -> {_, OptionsPattern[]}}
The allowed option names will be taken from Options[myPlot]
.
Finally, you can also mix these two approaches. You can have only a subset of Plot
's options present in Options[myPlot]
. I do not recommend that you do this because it can be confusing to users. Either put all of them in there (the more common approach), or none of them at all.