-
Notifications
You must be signed in to change notification settings - Fork 271
/
faq.R
56 lines (56 loc) · 1.91 KB
/
faq.R
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
#' Best practices for exporting adverb-wrapped functions
#'
#' @description
#'
#' Functions like [insistently()], [safely()], [slowly()], and
#' [quietly()] help resolve challenging issues in programming. For
#' example, [safely()] modifies a function to return both an error and
#' a result. These functions work by returning an enhanced version of
#' the original function. They are often called **adverb** functions
#' and are typically named with an informative prefix such as `safe_`
#' or `insist_.` For instance, an insistent variant of `scrape_data()`
#' created with `insistently()` might be called `insist_scrape_data()`.
#'
#' Exporting functions created with purrr adverbs in your package
#' requires some precautions. Because the functions created by adverbs
#' contain internal purrr code, creating them once and for all when
#' the package is built might cause problems when purrr is
#' updated. Instead, the function must be created either by the purrr
#' adverb each time the package is loaded in memory (using the
#' [.onload()] hook) or via wrapping the call within another function.
#' This prevents the generated functions from containing outdated
#' internal purrr code (which could even refer to functions that no
#' longer exist in the purrr namespace).
#'
#' Examples are provided below for `insist`, but it would be very
#' similar for functions generated by other adverbs.
#'
#' Using the [.onLoad()] hook:
#' ```
#' #' My function
#' #' @export
#' insist_my_function <- function(...) "dummy"
#'
#' my_function <- function(...) {
#' # Implementation
#' }
#'
#' .onLoad <- function(lib, pkg) {
#' insist_my_function <<- purrr::insistently(my_function)
#' }
#' ```
#'
#' Using a wrapper function:
#' ```
#' my_function <- function(...) {
#' # Implementation
#' }
#'
#' #' My function
#' #' @export
#' insist_my_function <- function(...) {
#' purrr::insistently(my_function)(...)
#' }
#' ```
#' @name faq-adverbs-export
NULL