Merge pull request #743 from r-lib/b-742-examples-if

- Support for @examplesIf roxygen tag (#743).

Author: lorenzwalthert

NEWS.md

@@ -35,6 +35,8 @@
   integrations`, minor other consistency edits (#741, #643, #618, #614, #677,
   #651, #667, #672, #687).
 
+- `@exampleIsf` roxygen tag for conditional examples is now supported (#743).
+
 - The environment variable `save_after_styling` is deprecated in favor of the R
   option `styler.save_after_styling` to control if a file is saved after styling
   with the RStudio Addin. Note than in RStudio >= 1.3.0, you can auto-save edits

R/roxygen-examples-add-remove.R

@@ -29,16 +29,19 @@ remove_roxygen_mask <- function(text) {
 #' #' @examples c(1, 2)
 #' @keywords internal
 remove_roxygen_header <- function(text) {
-  text <- gsub("^\\s*@examples\\s*", "", text, perl = TRUE)
-  starts_with_blank <- text[1] == "\n"
-  c(text[1][!starts_with_blank], text[-1])
+  gsub("^[\\s\t]*@examples(If)?(\\s|\t)*", "", text, perl = TRUE)
 }
 
+#' Add the roxygen mask to code
+#'
+#' @param text Character vector with code.
+#' @param example_type Either 'examples' or 'examplesIf'.
+#' @keywords internal
 #' @importFrom purrr map2_chr
-add_roxygen_mask <- function(text) {
+add_roxygen_mask <- function(text, example_type) {
   space <- ifelse(text == "", "", " ")
   c(
-    paste0("#' @examples", space[1], text[1]),
+    paste0("#' @", example_type, space[1], text[1]),
     map2_chr(space[-1], text[-1], ~ paste0("#'", .x, .y))
   )
 }

R/roxygen-examples-find.R

@@ -7,11 +7,11 @@
 #' @importFrom rlang seq2
 #' @keywords internal
 identify_start_to_stop_of_roxygen_examples_from_text <- function(text) {
-  starts <- grep("^#'\\s*@examples", text, perl = TRUE)
+  starts <- grep("^#'(\\s|\t)*@examples(If\\s|\\s|\t|$)", text, perl = TRUE)
   if (length(starts) < 1L) {
     return(integer())
   }
-  stop_candidates <- grep("^[^#]|^#'\\s*@", text, perl = TRUE)
+  stop_candidates <- grep("(^[^#]|^#'[\\s\t]*@)", text, perl = TRUE)
   stops <- map(starts, match_stop_to_start, stop_candidates) %>%
     flatten_int()
   if (length(stops) < 1L) {

R/roxygen-examples-parse.R

@@ -15,7 +15,8 @@
 #' ))
 #' @keywords internal
 parse_roxygen <- function(roxygen) {
-  connection <- textConnection(emulate_rd(roxygen))
+  emulated <- emulate_rd(roxygen)
+  connection <- textConnection(emulated$text)
   had_warning <- FALSE
   parsed <- withCallingHandlers(
     {
@@ -32,7 +33,7 @@ parse_roxygen <- function(roxygen) {
     }
   )
   close(connection)
-  parsed
+  list(text = parsed, example_type = emulated$example_type)
 }
 
 #' Fix [tools::parse_Rd()] output
@@ -123,22 +124,30 @@ roxygen_remove_extra_brace <- function(parsed) {
 #' `remove_roxygen_mask()` when there are no characters to escape.
 #' @keywords internal
 emulate_rd <- function(roxygen) {
+  example_type <- gsub("^#'(\\s|\t)*@examples(If)?(\\s|\t)*(.*)", "examples\\2", roxygen[1])
   if (needs_rd_emulation(roxygen)) {
     roxygen <- c(
-      "#' Example", "#' @examples",
-      gsub("^#'\\s*@examples\\s*(.*)", "#' \\1", roxygen),
+      "#' Example",
+      gsub("^#'(\\s|\t)*@examples(If)?(\\s|\t)*(.*)", "#' @examples \\4", roxygen),
       "x <- 1"
     )
-
-    roxygen2::roc_proc_text(
+    text <- roxygen2::roc_proc_text(
       roxygen2::rd_roclet(),
       paste(roxygen, collapse = "\n")
     )[[1]]$get_section("examples") %>%
       as.character() %>%
       .[-1]
+    text <- c(
+      if (grepl("^#'(\\s|\t)*@examples(\\s|\t)*$", roxygen[2])) "",
+      text
+    )
   } else {
-    remove_roxygen_mask(roxygen)
+    text <- remove_roxygen_mask(roxygen)
   }
+  list(
+    text = text,
+    example_type = example_type
+  )
 }
 
 #' Check if rd emulation is required with [roxygen2::roc_proc_text()]

R/roxygen-examples.R

@@ -17,16 +17,20 @@ style_roxygen_code_example <- function(example, transformers, base_indention) {
     flatten_chr()
 }
 
-
+#' Style a roxygen code example with exactly one `@example` or `@exampleIf`
+#' @inheritParams style_roxygen_code_example
+#' @param example_one A character vector, one element per line, that contains in
+#'   total at most one example tag.
+#' @keywords internal
 style_roxygen_code_example_one <- function(example_one, transformers, base_indention) {
   bare <- parse_roxygen(example_one)
-  one_dont <- split(bare, factor(cumsum(bare %in% dont_keywords())))
+  one_dont <- split(bare$text, factor(cumsum(bare$text %in% dont_keywords())))
   map(one_dont, style_roxygen_code_example_segment,
     transformers = transformers,
     base_indention = base_indention
   ) %>%
     flatten_chr() %>%
-    add_roxygen_mask()
+    add_roxygen_mask(bare$example_type)
 }
 
 #' Style a roxygen code example segment

man/add_roxygen_mask.Rd

@@ -36,3 +36,16 @@ x <- '\001'
 
 "\01"
 '\01'
+
+#' things
+#'
+#' @examplesIf N
+#' call("\n")
+#' ano("\\.", further = X)
+NULL
+
+#' things
+#'
+#' @examplesIf call("\n")
+#' ano("\\.", further = X)
+NULL

man/style_roxygen_code_example_one.Rd

@@ -36,3 +36,16 @@ x <- "\001"
 
 "\0"
 "\0"
+
+#' things
+#'
+#' @examplesIf N
+#' call("\n")
+#' ano("\\.", further = X)
+NULL
+
+#' things
+#'
+#' @examplesIf call("\n")
+#' ano("\\.", further = X)
+NULL