[Rd] declare and validate options

[Duncan Murdoch]

On 29/03/2024 10:52 a.m., Antoine Fabri wrote:
> Dear r-devel,
> 
> options() are basically global variables and they come with several issues:
> * they're not really truly owned by a package aside from loose naming
> conventions
> * they're not validated
> * their documentation is not standard, and they're often not documented at
> all, it's hard to know what options exist
> * in practice they're sometimes used for internal purposes, which is at
> odds with their global nature and contribute to the mess, I think they can
> almost always be replaced by objects under a `globals` environment in the
> namespace, it's just a bit more work
> 
> I tried to do as much as possible with static analysis using my package opt
> but it can only go so far : https://github.com/moodymudskipper/opt
> 
> I think we can do a bit better and that it's not necessarily so complex,
> here's a draft of possible design :
> 
> We could have something like this in a package to register options along
> with an optional validator, triggered on `options(..)` (or a new function).
> 
> # similar to registerS3method() :
> registerOption("mypkg.my_option1")
> registerOption("mypkg.my_option2", function(x) stopifnot(is.numeric(x))
> # maybe a `default` arg too to avoid the .onLoad() gymnastics and invisible
> NULL options
> 
> * validation is a breaking change so we'd have an environment variable to
> opt in
> * validation occurs when an option is set AND the namespace is already
> loaded (so we can still set options without loading a namespace) OR it
> occurs later when an applicable namespace is loaded
> * if we register an option that has already been registered by another
> package, we get a message, the validator of the last loaded namespace is
> used, in practice due to naming conventions it doesn't really happen, CRAN
> could also enforce naming conventions for new packages
> * New packages must use registerOption() if they define options, and there
> must be a standard documentation page for those, separately or together
> (with aliases), accessible with `?mypkg.my_option1` etc...
> 
> This could certainly be done in different ways and I'd love to hear about
> other ideas or obstacles to improvements in this area.
> 

I think there are too many packages that would need changes under this 
scheme.

A more easily achievable improvement would be to provide functions to 
support registration, validation and documentation, and leave it up to 
the package author to call those.  This wouldn't give you validation at 
the time a user set an option, but could make it easier to validate when 
the package retrieved the value:  specify rules in one place, then 
retrieve from multiple places, without needing to duplicate the rules.

If those functions could be made simple enough and bulletproof and were 
widely adopted, maybe they'd be copied into one of the base packages, 
but really the only need for that would be to support validation on 
setting, rather than validation on retrieval.

Duncan Murdoch