feat: simplify use of vcr in examples

Author: maelle

DESCRIPTION

@@ -56,7 +56,7 @@ Config/testthat/parallel: true
 Config/testthat/start-first: ause_cassette_re_record
 Encoding: UTF-8
 Language: en-US
-Roxygen: list(markdown = TRUE)
+Roxygen: list(markdown = TRUE, roclets = c("collate", "rd", "namespace", "vcr::examplesVCR_roclet"), packages = "vcr")
 RoxygenNote: 7.3.2
 X-schema.org-applicationCategory: Web
 X-schema.org-isPartOf: https://ropensci.org

NAMESPACE

@@ -1,5 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(roclet_output,roclet_examplesVCR)
+S3method(roclet_process,roclet_examplesVCR)
+S3method(roxy_tag_parse,roxy_tag_examplesVCR)
+S3method(roxy_tag_rd,roxy_tag_examplesVCR)
 export(Cassette)
 export(cassette_path)
 export(cassettes)
@@ -8,6 +12,7 @@ export(current_cassette)
 export(current_cassette_recording)
 export(current_cassette_replaying)
 export(eject_cassette)
+export(examplesVCR_roclet)
 export(insert_cassette)
 export(insert_example_cassette)
 export(is_recording)
@@ -23,6 +28,7 @@ export(turned_off)
 export(turned_on)
 export(use_cassette)
 export(use_vcr)
+export(use_vcr_examples)
 export(vcr_config_defaults)
 export(vcr_configuration)
 export(vcr_configure)
@@ -33,3 +39,8 @@ export(vcr_last_response)
 export(vcr_test_path)
 import(rlang)
 importFrom(lifecycle,deprecated)
+importFrom(roxygen2,block_get_tags)
+importFrom(roxygen2,roclet_output)
+importFrom(roxygen2,roclet_process)
+importFrom(roxygen2,roxy_tag_parse)
+importFrom(roxygen2,roxy_tag_rd)

R/examples.R

@@ -2,7 +2,11 @@
 #'
 #' @description
 #' `insert_example_cassette()` is a wrapper around [insert_cassette()] that
-#' stores cassettes in `inst/_vcr/`. Call it in the first line of your examples
+#' stores cassettes in `inst/_vcr/`. Either:
+#' - Use the vcr-specific `@examplesVCR` tag instead of the `@examples` tag.
+#' For this to work you need to register vcr in your DESCRIPTION by running
+#' `vcr::use_vcr_examples()` once per package.
+#' - Call it in the first line of your examples
 #' (typically wrapped in `\dontshow{}`), and call `eject_cassette()` on the
 #' last line.
 #'

R/roxygen-example.R

@@ -0,0 +1,7 @@
+#' @rdname vcr-example
+#' @name vcr-example
+#' @title Trying out our custom tag
+#' @keywords internal
+#' @examplesVCR bla
+#' 1 + 1
+NULL

R/roxygen.R

@@ -0,0 +1,124 @@
+#' @importFrom roxygen2 roxy_tag_parse
+#' @importFrom roxygen2 roxy_tag_rd
+NULL
+
+#' @export
+roxy_tag_parse.roxy_tag_examplesVCR <- function(x) {
+  roxygen2::tag_markdown(x)
+}
+
+#' @export
+roxy_tag_rd.roxy_tag_examplesVCR <- function(x, base_path, env) {
+  roxygen2::rd_section("examples", x$val)
+}
+
+#' @export
+roxy_tag_parse.roxy_tag_examplesVCR <- function(x, ...) {
+  lines <- unlist(strsplit(x$raw, "\r?\n"))
+
+  cassette_name <- trimws(lines[1])
+  package_name <- roxygen2::roxy_meta_get("current_package")
+
+  x$raw <- paste(
+    c(
+      sprintf(
+        "\\dontshow{vcr::insert_example_cassette('%s', package = '%s')}",
+        cassette_name,
+        package_name
+      ),
+      lines[-1],
+      "\\dontshow{vcr::eject_example_cassette()}"
+    ),
+    collapse = "\n"
+  )
+  x$value <- ""
+  roxygen2::tag_examples(x)
+}
+
+
+#' @export
+# https://github.com/shahronak47/informationtag
+examplesVCR_roclet <- function() {
+  roxygen2::roclet("examplesVCR")
+}
+
+#' @importFrom roxygen2 block_get_tags roclet_process
+#' @method roclet_process roclet_examplesVCR
+#' @export
+# https://github.com/shahronak47/informationtag
+roclet_process.roclet_examplesVCR <- function(x, blocks, env, base_path) {
+  x
+}
+
+
+#' @export
+#' @importFrom roxygen2 block_get_tags roclet_output
+roclet_output.roclet_examplesVCR <- function(x, results, base_path, ...) {
+  x
+}
+
+#' Use 'vcr' for examples in your package
+#'
+#' This functions amends DESCRIPTION to set up vcr's roxygen2 machinery.
+#' Call it once when you're setting a new package.
+#'
+#' @param path character path to the package
+#'
+#' @return Nothing: called for file system side effects.
+#' @export
+#'
+use_vcr_examples <- function(path = ".") {
+  rlang::check_installed("desc")
+
+  cli::cli_alert_info("Registering vcr's roxygen2 tag usage in DESCRIPTION")
+
+  current_roxy <- desc::desc_get("Roxygen", file = path)[[1]]
+  if (is.na(current_roxy)) {
+    desc::desc_set(
+      "Roxygen",
+      'list(markdown = TRUE, roclets = c("collate", "rd", "namespace", "vcr::examplesVCR_roclet", packages = "vcr"))'
+    )
+  } else {
+    current <- eval(parse(text = current_roxy))
+    new <- current
+    new[["roclets"]] <- union(
+      current[["roclets"]],
+      c("collate", "rd", "namespace", "vcr::examplesVCR_roclet")
+    )
+    new[["packages"]] <- union(current[["packages"]], "vcr")
+
+    new_string <- paste(deparse(new), collapse = "")
+    desc::desc_set("Roxygen", new_string, file = path)
+  }
+
+  cli::cli_alert_info("Registering vcr build-time dependency in DESCRIPTION")
+  desc::desc_set(
+    "Config/Needs/build",
+    paste_desc(
+      desc::desc_get("Config/Needs/build", file = path),
+      "vcr"
+    ),
+    file = path
+  )
+}
+
+#' Append value if needed
+#'
+#' @param x Existing DESCRIPTION field value
+#' @param y Value to append
+#'
+#' @return A character string
+#' @dev
+#'
+#' @examples
+#' paste_desc(NA, 1)
+#' paste_desc(1, 1)
+#' paste_desc(2, 1)
+paste_desc <- function(x, y) {
+  if (is.na(x)) {
+    return(y)
+  }
+
+  # ensure this is idempotent
+  toString(unique(c(x, y)))
+}