Export objects via name vector

[egnha]

Tag @exportNames allows one to export objects using a vector of names. Example:

fs <- lapply(1:10, function(a) {function(x) a + x})
names(fs) <- paste0("f_", 1:10)
for (nm in names(fs)) assign(nm, fs[[nm]])

#' @exportNames names(fs)
NULL

Such a tag is handy if one needs to export batches of closures, say (e.g., in a DSL).

[hadley]

Can you give me more of an example where you'd use this?

[egnha]

@hadley My experience with writing R packages is admittedly rather limitied, but here's one specific example from ML that I think is not too contrived.

One might want to provide probability estimators for a bunch of binary classifiers in a programmatic manner, according to a common pattern. It might then make sense to write a single unified doc for the family of estimators, and just one doc line to do a batch export. Then something like @exportNames could eliminate tedium and boilerplate code.

More concretely:

# Suppose `mdl_params` is a list of model-specific parameters, named by S3 method
# Suppose also that `make_estimator()` makes estimators out of those parameters
estprob <- function(x, ...) UseMethod("estprob")
for (mdl in names(mdl_params))
  assign(paste0("estprob.", mdl), make_estimator(mdl_params[[mdl]]))
estimators <- paste0("estprob.", names(mdl_params))

#' @exportNames estimators
NULL

Technically, that won't work in the current implementation of @exportNames (as I now realize!), since one would then want to generate S3method() lines in NAMESPACE, rather than export()'s. But @exportNames could be modified to handle that. I believe the basic purpose of @exportNames remains valid.

[hadley]

I'd rather provide @evalNamespace by analog to @evalRd. That's a bit more general and would still solve your problem.

[egnha]

Interesting suggestion. But I'm not sure I understand what you have in mind, exactly. Here's my guess, please correct me if I'm wrong: @evalNamespace would allow you to reproduce

#' @exportNames names(fs)
NULL

with

#' @export names(fs)
#' @evalNamespace
NULL

Another possibility would be to allow @evalNamespace to selectively evaluate part of a tag, while inserting the rest of the tag literally, perhaps by quoting the part to evaluate. Something like

f_nms <- paste0(names(fs), collapse = ",")
#' @evalNamespace export(~f_nms)
NULL

But having to put the commas in by hand feels clumsy.

[hadley]

@evalNamespace code(...) would just evaluate code and insert the results into the NAMESPACE

[egnha]

If you still think @evalNamespace code(...) would be a useful addition to roxygen, and if I can figure out a reasonable way to do what you've suggested, would it be better in the future for me to post an issue or a (separate) pull request?

[hadley]

A new PR or issue would be best