Экспорт списка функций с помощью roxygen2

Проблема: я хочу экспортировать список функций как часть пакета R, в идеале с помощью roxygen2.

Точнее, я хочу экспортировать функции в списке, а не сам список. Например, рассмотрим список функций, которые генерируются как замыкания, например:

addval <- 1:100
fns <- lapply(addval, function(y) {force(y); function(x) x + y})
names(fns) <- paste0("add_", addval)

Тогда проблема состоит в том, чтобы привязать функции (используя те же имена в fns, например) к среде пакета, а затем включить их среди экспортируемых функций пакета.

Привязать функции к среде пакета можно достаточно легко; один из способов был бы

for (nm in names(fns)) assign(nm, fns[[nm]])

Но можно ли использовать теги roxygen2 для экспорта функций add_1, add_2 и т. д.?

Более конкретно: я бы хотел, чтобы roxygen2 продолжал управлять файлом NAMESPACE вместо меня, и предпочел бы не писать вызовы export() напрямую. Единственный способ, которым я могу это сделать, — это написать код для создания шаблона, например

#' @export add_1
NULL

#' @export add_2
NULL

# ...

или лучше

#' @export
add_1 <- fns[["add_1"]]

#' @export
add_2 <- fns[["add_2"]]

# ...

(и отказаться от вышеуказанного цикла for).

Есть ли у roxygen2 средства, эквивалентные созданию такого стандартного шаблона, или мне придется предоставлять эти средства самостоятельно?

Я имею в виду такую ​​возможность, выражающуюся более кратко, как

#' @exportObjects names(fns)
NULL

где тег @exportObjects будет интерпретировать свой «аргумент» как вектор символов имен объектов для экспорта.

Обновлять

roxygen2 6.0.1+ решает эту проблему с помощью нового тега @evalNamespace, который позволяет вам вставлять литеральные записи в файл NAMESPACE:

ns_export <- function(nms)
  sprintf("export(%s)", paste(nms, collapse = ","))

#' @evalNamespace ns_export(names(fns))

Использование тега @evalNamespace безопаснее, чем использование директивы exportPattern(), потому что при использовании последней нужно быть бдительным, чтобы случайно не назвать объект в пространстве имен пакета, который соответствует регулярному выражению.


person egnha    schedule 07.10.2016    source источник
comment
Мой удаленный ответ показал минимально необходимые элементы (о которых вы, возможно, уже знали). Если вы посмотрите на пакет scales, то увидите, что в нем много замыканий, и все они задокументированы вручную.   -  person hrbrmstr    schedule 07.10.2016
comment
@hrbrmstr - Спасибо за предложение. Не могли бы вы указать мне соответствующий файл в scales? Я пересмотрел вопрос, чтобы сделать его более точным и указать, какую неуклюжесть (и дополнительную работу) я хотел бы избежать.   -  person egnha    schedule 08.10.2016
comment
Таким образом, Хэдли (и др.) не делает их программно, как вы, а вот scales исходный файл с замыканиями. Я не думаю, что вы сможете обойти ручное включение в roxygen2.   -  person hrbrmstr    schedule 08.10.2016
comment
@hrbrmstr - Спасибо за подсказку! Я предполагаю, что вариант использования, который я обрисовал в общих чертах, не должен толковаться достаточно широко, чтобы оправдать его принадлежность к roxygen2 — что было бы очень плохо, поскольку это сделало бы roxygen2 неадекватным (но в остальном хорошим) инструментом для документирования DSL, скажем. , что, как можно ожидать, приведет к большому количеству открытых пользователем замыканий.   -  person egnha    schedule 08.10.2016


Ответы (1)


Вы можете использовать тег @rawNamespace в недавнем roxygen2, это позволяет использовать произвольный синтаксис, допустимый в файле NAMESPACE, включая exportPattern():

#' @rawNamespace exportPattern("^add_.*$")
person krlmlr    schedule 16.10.2016
comment
Это достаточно близко к тому, что мне нужно, спасибо! Кстати, а где этот тег задокументирован? По иронии судьбы кажется, что документация для самого roxygen2 (5.0.1) могла бы быть намного лучше. Я не нашел ссылки на этот тег в тех местах, которые кажутся вероятными (индекс справки roxygen2 и пространство имен пакета виньетки). - person egnha; 17.10.2016
comment
@egnha: новости — хорошее место для поиска, но Лучший способ улучшить документацию — создать проблему или даже запрос на вытягивание на GitHub. - person krlmlr; 17.10.2016
comment
Спасибо за ваше предложение, @krlmlr! Я отправил запрос на включение тега exportNames (#531). - person egnha; 23.10.2016