Renaming options of custom functions while preserving backwards compatibility

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;
AddLegacyOptionHandling[sym_] := (
  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};
AddLegacyOptionHandling[sym_] := (
  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 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"])
 ] := ...

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.