Handling argument deprecations and their warnings

[unode]

Given the scenario:

1. Argument --new was renamed to --old.
2. --old should still do the same as --new but a warning should be printed.

This use-case can be seen when deprecating an argument in favor of other(s).

A similar use-case would be raising an error when --old is used. This would be useful when incompatible changes are introduced or when, after a deprecation cycle, the option is removed.

is there a common pattern that addresses these use-cases?

[HuwCampbell]

That's an interesting one.

We don't currently have a way of tracking and emitting warnings through optparse itself, although it would be quite easy to do with just normal ADTs as the result of a parse (but you'd have to emit the warning yourself.

[pcapriotti]

The cleanest way to support this from the point of the help text would be to have a way to determine which option name has been matched during parsing. I've pushed a branch readm-name adding this functionality to ReadM. There is also an example Deprecation.hs showing how to implement deprecated option names.

Of course, if you only need to deprecate whole options, you can already do that by just returning the deprecated name unconditionally in the corresponding Parser. As a workaround, you can also deprecate names by creating identical options that differ only in the names, have them optionally return the deprecated name using Maybe, and merge them using <|>. However, the help text won't look as good.