edit and retrieve reusable examples

DESCRIPTION

@@ -33,6 +33,7 @@ Imports:
     pkgload,
     purrr,
     rlang,
+    tibble,
     usethis,
     withr
 Suggests:

NAMESPACE

@@ -1,5 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(roxygen2::roclet_output,roclet_elfReusableExamples)
+S3method(roxygen2::roclet_process,roclet_elfReusableExamples)
 S3method(roxygen2::roxy_tag_parse,roxy_tag_elfReusableExamples)
 S3method(roxygen2::roxy_tag_rd,roxy_tag_elfReusableExamples)
 export(assert_pkg_installed)
@@ -11,6 +13,7 @@ export(expect_pkg_installed_but_not_via_loadall)
 export(is_installed2)
 export(make_skip_if_not_function)
 export(opt_set_local2)
+export(reusableExamples_roclet)
 export(skip_if_pkg_installed_but_not_via_loadall)
 export(skip_if_pkg_not_installed2)
 export(source_pef)

R/examples.R

@@ -113,3 +113,54 @@ roxy_tag_rd.roxy_tag_elfReusableExamples <- function(x, base_path, env) {
   )
   roxygen2::rd_section("examples", res)
 }
+
+#' Roclet to retrieve code from `@elfReusableExamples`
+#' @family example helpers
+#' @family testing helpers
+#' @keywords internal
+#' @export
+reusableExamples_roclet <- function() {
+  roxygen2::roclet("elfReusableExamples")
+}
+
+#' @exportS3Method roxygen2::roclet_process
+roclet_process.roclet_elfReusableExamples <- function(x, blocks, env, base_path) {
+  empty_res <- tibble::tibble(
+    topic = character(),
+    alias = character(),
+    file = character(),
+    name = character(),
+    code = character()
+  )
+  purrr::map(
+    blocks,
+    .f = function(block) {
+      tags <- roxygen2::block_get_tags(block, "elfReusableExamples")
+      full_res <- empty_res
+      for (tag in tags) {
+        res <- tibble::tibble(
+          topic = purrr::pluck(block, "object", "topic"),
+          alias = purrr::pluck(block, "object", "alias"),
+          file = tag$file,
+          name = tag$val$name,
+          code = tag$val$code
+        )
+        full_res <- tibble::add_row(full_res, res)
+      }
+      full_res
+    }
+  )  |>
+    purrr::list_rbind()
+}
+
+#' @exportS3Method roxygen2::roclet_output
+roclet_output.roclet_elfReusableExamples <- function(x, results, base_path, ...) {
+  message("Found these (reusable) examples:")
+  print(results)
+  invisible(NULL)
+}
+
+#' An example documentation of a resuable example
+#' @elfReusableExamples lorem
+#' paste2("ipsum, "dolor")
+paste2 <- paste

inst/examples/elfReusableExamples/parse.R

@@ -3,4 +3,11 @@
 #' zap_fun(1, 2)
 #' @elfReusableExamples bar
 #' zap_fun(2, 3)
-zap_fun <- function(...) sum(...)
+zap_fun <- sum
+
+#' Another example documentation of a resuable example
+#' @elfReusableExamples baz
+#' qux_fun(3, 4)
+#' only the result of this should be returned
+#' qux_fun(4, 5)
+qux_fun <- sum

tests/testthat/_snaps/examples.md

@@ -16,7 +16,7 @@
       [<text>:  6] @usage '<generated>' {parsed}
       
       [[5]]
-      [<text>:  6] @.formals '<generated>' {parsed}
+      [<text>:  6] @.formals '<generated>' {unparsed}
       
       [[6]]
       [<text>:  6] @backref '<generated>' {parsed}
@@ -46,3 +46,29 @@
       zap_fun(2, 3)
       } 
 
+# roclet: can retrieve code and metadata
+
+    Code
+      results
+    Output
+      # A tibble: 3 x 5
+        topic   alias   file   name  code                                             
+        <chr>   <chr>   <chr>  <chr> <chr>                                            
+      1 zap_fun zap_fun <text> foo   "zap_fun(1, 2)"                                  
+      2 zap_fun zap_fun <text> bar   "zap_fun(2, 3)"                                  
+      3 qux_fun qux_fun <text> baz   "qux_fun(3, 4)\nonly the result of this should b~
+
+# roclet: can inform about found resuable calls
+
+    Code
+      roxygen2::roclet_output(reusableExamples_roclet(), results)
+    Message
+      Found these (reusable) examples:
+    Output
+      # A tibble: 3 x 5
+        topic   alias   file   name  code                                             
+        <chr>   <chr>   <chr>  <chr> <chr>                                            
+      1 zap_fun zap_fun <text> foo   "zap_fun(1, 2)"                                  
+      2 zap_fun zap_fun <text> bar   "zap_fun(2, 3)"                                  
+      3 qux_fun qux_fun <text> baz   "qux_fun(3, 4)\nonly the result of this should b~
+

tests/testthat/test-examples.R

@@ -1,10 +1,10 @@
-describe("roxy_tag_elfReusableExamples", {
-  example <- brio::read_file(
-    fs::path_package(
-      package = "elf",
-      "examples", "elfReusableExamples", "parse", ext = "R"
-    )
+example <- brio::read_file(
+  fs::path_package(
+    package = "elf",
+    "examples", "elfReusableExamples", "parse", ext = "R"
   )
+)
+describe("roxy_tag_elfReusableExamples", {
   it(
     "can be parsed",
     expect_snapshot(roxygen2::parse_text(example)[[1]]$tag)
@@ -21,3 +21,16 @@ describe("roxy_tag_elfReusableExamples", {
     }
   )
 })
+describe("roclet", {
+  results <- roxygen2::roc_proc_text(reusableExamples_roclet(), example)
+  it(
+    "can retrieve code and metadata",
+    expect_snapshot(results)
+  )
+  it(
+    "can inform about found resuable calls",
+    expect_snapshot(
+      roxygen2::roclet_output(reusableExamples_roclet(), results)
+    )
+  )
+})