# Renaming options of custom functions while preserving backwards compatibility

I have a package with many functions. There is an option name that several functions share. I feel that the current name of this option was not the best choice. I would like to rename it, but at the same time, I would like to preserve backwards compatibility.

If this option name were a symbol, the simple solution would be

oldName = newName

(And, of course, replacing all occurrences of the old name with the new one in the package.)

But in this case, the option name is a string. Even if it weren't, OptionValue does not distinguish between string and symbol names. It is preferable to handle both.

The package uses the standard option handling with OptionsPattern/OptionValue.

What is the best way to rename this option? I am looking to change as little existing code as possible (except for basic find-and-replace of names), and take as little performance hit as possible.

You can try the following:

Attributes[HandleLegacyOption] = {HoldAll};
HandleLegacyOption[o : OptionValue[sym_, opts_, name_]] :=
o //. Fallback[old_] :> OptionValue[sym, opts, old]

This can be used the following way:

Options[f] = {"bar" -> Fallback["foo"], "foo" -> 1};
f[OptionsPattern[]] := HandleLegacyOption@OptionValue["bar"]

f[]
f["bar" -> 2]
f["foo" -> 2]
f["foo" -> 2, "bar" -> 3]
(* 1 *)
(* 2 *)
(* 2 *)
(* 3 *)

As you can see, setting either option works, and the new name takes precedence over the old one.

### How?

Since OptionValue is a very special function, we can't do much other than explicitly leaving OptionValue[…] in the r.h.s. of our definitions. But one thing we can use is the fact that OptionValue[…] constructs are always expanded, no matter where they appear (see also linked question):

g[OptionsPattern[]] := Hold@OptionValue["foo"]
g["bar" -> 1]
(* Hold[OptionValue[g, {"bar" -> 1}, "foo"]] *)

So as long as we have OptionValue[…] explicitly appearing, we have access to:

• The symbol, and thus the defaults
• The explicitly specified options
• The queried options

The function HandleLegacyOption above uses this information by repeatedly querying option values as long as the result is Fallback[oldName]. This essentially defaults the new option to the value of another option.

### Possible extensions

As mentioned earlier, we need OptionValue to appear on the r.h.s. of the definition, otherwise we won't get the automatic expansion of all the information we need. One possible way to (partially) automate this wrapping of OptionValue might be:

HoldPattern[lhs_ // AddLegacyOptionHandling := rhs_] ^:=
Hold[rhs] /.
o_OptionValue :> HandleLegacyOption@o /.
Hold[proc_] :> (lhs := proc)

This automatically wraps all OptionValue expressions on the r.h.s. in HandleLegacyOption, e.g.

f[OptionsPattern[]] // AddLegacyOptionHandling := OptionValue["bar"]

yields the same result as in the first example.

# Alternative solution

Note: This is heavily based on @Henrik Schumacher's answer, so be sure to upvote that one if this is useful

Using the idea of adding special casing for certain symbols to OptionValue, we get the following solution:

processing = False;
OptionValue[sym, opts_, names_] /; ! processing ^:= Block[
{processing = True},
OptionValue[sym, opts, names] //. Fallback[old_] :> OptionValue[sym, opts, old]
]
)

After calling AddLegacyOptionHandling[f], this works exactly as in the examples above.

The following version also supports the fourth argument of OptionValue:

processing = False;
Attributes[OptionWrapper] = {Flat, HoldAll};
OptionValue[sym, opts_, names_, wrapper_ | PatternSequence[]] /; ! processing ^:= Block[
{processing = True},
OptionValue[sym, opts, names, OptionWrapper] //.
Fallback[old_] :> With[
{val = OptionValue[sym, opts, old, OptionWrapper]},
val /; True
] /.
Verbatim[OptionWrapper][val_] :> If[{wrapper} === {}, val, wrapper[val]]
]
)

The code is slightly more complex now as we need to be careful with evaluation leaks. But all in all, this version should support all forms of OptionValue, that is both lists of option names and Hold wrappers, while incurring a negligible performance hit for options that are not set to Fallback[…] and no impact for unaffected functions.

This may be more work than OP was asking to do, so in that respect it might not be an answer to the question. I think that if you are trying to do something that requires adding definitions to OptionValue or other such gymnastics, it's a good sign you should do something else.

I would simply define a replacement rule and a message,

General::mypackagedeprec = "Option name 1 is deprecated and will not be supported in future versions of MyPackage. Use 2 instead."

fixOptionNames[func_] :=    ReplaceAll[
HoldPattern[Rule["oldOptionName", rhs_]] :> (
Message[
MessageName[ func, "deprec"],
"oldOptionName",
"newOptionName"
];
"newOptionName" -> rhs
)
]

And then I would replace all instances of

OptionValue[ MyFunction, options, "oldOptionName"]

with

OptionValue[ MyFunction, fixOptionNames[MyFunction] @ options, "oldOptionName"]

Or even better, if you use the paradigm of having MyFunction call Catch[ iMyFunction[...]] then you can perform the replacement at that point. It does involve manually going through and making adjustments, but that seems the price to pay for renaming an option.

I like the message because it means you alert the users to the new name, and then after a few releases you can redefine fixOptionNames[___] to Identity or remove it entirely, but if you want to accept the old name in perpetuity then you'll need to keep it around.

• The problem is that I almost never use OptionValue[ MyFunction, options, "oldOptionName"]. I usually use OptionValue["someName"]. So far Lukas's solution looks best. As for redefining or modifying OptionValue: that is not something I am willing to do in a published package. Nov 4, 2018 at 17:36
• @Szabolcs Do you still find it problemating to add rules to OptionValue with TagSet? Technically that is not modifying OptionValue. Nov 4, 2018 at 19:27

This is my new approach. It is minimally invasive in the sense that it has to redefine OptionValue to handle only the new option "newopt" for the function f differently.

Now declare a function f in the classical way, but set the defaults for all "old" options to Automatic (or to any other custom symbol):

Options[f] = {
"newopt" -> 1,
"oldopt" -> Automatic
};
f[opts : OptionsPattern[]] := OptionValue["newopt"]

Add a new rule to OptionValue that is associated to f:

optionAliases = <|"newopt" -> {"oldopt"}|>;

f /: OptionValue[f, opts_, "newopt"] := If[
("newopt" /. {opts}) =!= {"newopt"},
First[OptionValue[f, opts, {"newopt"}]],
First[OptionValue[f, opts, optionAliases["newopt"]]] /.
Automatic :> First[OptionValue[f, opts, {"newopt"}]]
];

Now let's see what happens:

f[]
f["newopt" -> 2]
f["oldopt" -> 3]
f["newopt" -> 4, "oldopt" -> 3]
f["oldopt" -> 3, "newopt" -> 5]

1

2

3

4

5

So, this always gives preference to values for "newopt" over values for "oldopt".

Note that we rely on the fact that OptionValue will treat OptionValue[f, opts, {"newopt"}] as before. So this will only work if you call OptionValue["newopt"], not if you request it with several option values at once like in OptionValue[{"opt1", "opt2", ... "newopt", ... }]. One might be able to make it work by specifying an additional rule à la

f /: OptionValue[
f,
opts_,
list_List?(x \[Function] Length[list] >= 2 && MemberQ[list, "newopt"])
] := ...
• Nice solution! Although I wonder whether the global nature of these rules incurs any performance hit... (but that should at least be minimized with the explicit listing of the functions handled this way). And one more note: For me, the TagSet version seems to work just fine - what exactly is the problem for you? Nov 4, 2018 at 16:15
• Oh, it works for you? Ah, the ClearAll[f] cleared the TagSet definition (doh!). The better it is! This should make it really minimally invasive. Nov 4, 2018 at 16:48
• I've added an alternative solution to my answer that was heavily inspired by yours, I hope that's ok (otherwise, feel free to move that part to your answer) Nov 4, 2018 at 17:17
• With some variations of this, it is not actually necessary to add the old option to the Options list of the symbol. That means that (other than the renaming), the modifications necessary for backwards compatibility can be kept isolated, and easily removed at some later time. The compromise is that usage with SetOptions is not backwards compatible. But this is rare. Nov 5, 2018 at 9:16
• Hm. I added the old option to the options list because Mathematic would complain about "oldopt" not being a valid option for f... Nov 5, 2018 at 9:19

I have not heavily tested it but I decided to give it a try because I don't like minor issues with other proposals. E.g. that old options stay in Options or the way legacy rules are applied/used.

Here it is:

ClearAll[LegacyOptions]

LegacyOptions[f_Symbol, rules : {__Rule}] := (
f[a___, (r : Rule | RuleDelayed)[#, val_], b___] := f[a, r[#2, val], b]
) & @@@ rules

So the problem can be that this DownValue gets below any DownValue with OptionsPattern and the the old option will throw an error.

Here it is in action:

foo // ClearAll;

foo // Options = {
"newName" -> 1,
"newName2" :> 1 + 1
};

foo ~ LegacyOptions ~ {
"oldName" -> "newName",
"oldName2" -> "newName2"
};

foo[x_Integer, patt : OptionsPattern[]] := {
x^2,
OptionValue["newName"],
OptionValue[Automatic, Automatic, "newName2", Hold]
};

foo[1, "oldName2" :> 1 + 2, "oldName" -> 4]
{1, 4, Hold[1 + 2]}

Let me know if you manage to break it.

• foo[1, {"newName2" :> 1 + 2, "newName" -> 4}] works but foo[1, {"oldName2" :> 1 + 2, "oldName" -> 4}] does not. Nov 5, 2018 at 2:38
• @MichaelE2 you mean w/wo {}? Yes, I was never a fan of OptionsPattern allowing them ;)
– Kuba
Nov 5, 2018 at 7:06
• I guess they did it to make processing {opts} convenient since Sequence[opts] is such an oxidizing agent. I use it fairly often when, say, writing a solver that needs to to call NDSolve with some user-supplied options and FindRoot with others. I was thinking that a user of a package might want to do the same. I had an idea based on one of halirutan's. Don't know if it's any good though. Nov 5, 2018 at 12:13
• @MichaelE2 yes, probably. Will try to think about a workaround for this issue.
– Kuba
Nov 5, 2018 at 12:45