[Rd] How to best implement package options?

[Bjørn-Helge Mevik]

Dear developeRs,

I have a package, pls, that implements package options.  The users are
supposed to use a function pls.options() to manipulate them.

If a user changes the options, they are stored in .GlobalEnv.  I was
recently informed that this is against current CRAN submission policies,
so I need to change that.


I have looked at several different packages that implement package
options, and found that:


1) Many packages simply use the global R options, setting default
  options with base::options() inside either .onLoad() or .onAttach().
  Users then are supposed to use base::options() etc. for manipulating
  the options.

  This has the advantages that users can use the standard options
  interface, and the package authors don't need to "reinvent the wheel".

  One disadvantage is the possibility for name collisions between
  package options.  Some packages try to minimise that risk by prefixing
  all options with the package name.


2) Some packages implement their own version of options() (like
  pls.options()), and store a list of options in the package name space.

  This avoids any name collisions, but users have to relate to several
  options interfaces (the ones I've seen work mostly the same as the
  standard options(), though).

  AFAIK, this solution neccessitates calling unlockBinding() on the
  option list, or using assignInMyNamespace() to update it.


3) Finally, I've found one package ('pkgmaker') that implements a
  general mechanism that can be used by other packages to create package
  options.  The mechanism creates options()-like functions in the
  package's name space, and the optins are either stored as a single
  option in base:::.Options, or in the created function's enclosure.

  Again, users need to relate to separate options interfaces, but the
  package authors don't have to "reinvent the wheel".


What is considered "best practice" for implementing package options?
Any of the above, or something different?


-- 
RegaRds,
Bjørn-Helge Mevik