Add @examplesIf tag (#993)

* Add @examplesIf tag

* Add NEWS for @examplesIf

Co-authored-by: Kirill Müller <krlmlr+r@mailbox.org>

NAMESPACE

@@ -110,6 +110,7 @@ S3method(roxy_tag_parse,roxy_tag_evalNamespace)
 S3method(roxy_tag_parse,roxy_tag_evalRd)
 S3method(roxy_tag_parse,roxy_tag_example)
 S3method(roxy_tag_parse,roxy_tag_examples)
+S3method(roxy_tag_parse,roxy_tag_examplesIf)
 S3method(roxy_tag_parse,roxy_tag_export)
 S3method(roxy_tag_parse,roxy_tag_exportClass)
 S3method(roxy_tag_parse,roxy_tag_exportMethod)
@@ -165,6 +166,7 @@ S3method(roxy_tag_rd,roxy_tag_encoding)
 S3method(roxy_tag_rd,roxy_tag_evalRd)
 S3method(roxy_tag_rd,roxy_tag_example)
 S3method(roxy_tag_rd,roxy_tag_examples)
+S3method(roxy_tag_rd,roxy_tag_examplesIf)
 S3method(roxy_tag_rd,roxy_tag_family)
 S3method(roxy_tag_rd,roxy_tag_field)
 S3method(roxy_tag_rd,roxy_tag_format)

NEWS.md

@@ -1,5 +1,9 @@
 # roxygen2 (development version)
 
+* The new `@exmaplesIf` tag can be used to create conditional
+ examples. These examples only run if a specified condition
+ holds (#962).
+
 # roxygen2 7.1.1
 
 * When processing cross package markdown links (e.g. `[pkg::fun()]`),

R/rd-examples.R

@@ -3,6 +3,31 @@ roxy_tag_parse.roxy_tag_examples <- function(x) {
  tag_examples(x)
 }
 #' @export
+roxy_tag_parse.roxy_tag_examplesIf <- function(x) {
+ lines <- unlist(strsplit(x$raw, "\r?\n"))
+
+ condition <- lines[1]
+ tryCatch(
+ suppressWarnings(parse(text = condition)),
+ error = function(err) {
+ roxy_tag_warning(x, "failed to parse condition of @examplesIf")
+ }
+ )
+
+ dontshow <- paste0(
+ "\\dontshow{if (",
+ condition,
+ ") (if (getRversion() >= \"3.4\") withAutoprint else force)(\\{ # examplesIf}"
+ )
+
+ x$raw <- paste(
+ c(dontshow, lines[-1], "\\dontshow{\\}) # examplesIf}"),
+ collapse = "\n"
+ )
+
+ x <- tag_examples(x)
+}
+#' @export
 roxy_tag_parse.roxy_tag_example <- function(x) {
  x <- tag_value(x)
 
@@ -20,6 +45,10 @@ roxy_tag_rd.roxy_tag_examples <- function(x, base_path, env) {
  rd_section("examples", x$val)
 }
 #' @export
+roxy_tag_rd.roxy_tag_examplesIf <- function(x, base_path, env) {
+ rd_section("examples", x$val)
+}
+#' @export
 roxy_tag_rd.roxy_tag_example <- function(x, base_path, env) {
  path <- file.path(base_path, x$val)
  if (!file.exists(path)) {

tests/testthat/test-rd-examples.R

@@ -77,6 +77,21 @@ test_that("warns if path doesn't exist", {
  )
 })
 
+test_that("@examplesIf", {
+ out <- roc_proc_text(rd_roclet(), "
+ #' @name a
+ #' @title a
+ #' @examplesIf foo::bar()
+ #' maybe-run-this-code
+ #' @examplesIf foobar()
+ #' and-this
+ NULL")[[1]]
+
+ verify_output(test_path("test-rd-examplesIf.txt"), {
+ out$get_section("examples")
+ })
+})
+
 test_that("% in @examples escaped before matching braces test (#213)", {
  out <- roc_proc_text(rd_roclet(), "
  #' @name a

tests/testthat/test-rd-examplesIf.txt

@@ -0,0 +1,10 @@
+> out$get_section("examples")
+\examples{
+\dontshow{if (foo::bar()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+maybe-run-this-code
+\dontshow{\}) # examplesIf}
+\dontshow{if (foobar()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+and-this
+\dontshow{\}) # examplesIf}
+} 
+

tests/testthat/testNamespace/DESCRIPTION

@@ -6,4 +6,4 @@ Author: Hadley <hadley@rstudio.com>
 Maintainer: Hadley <hadley@rstudio.com>
 Encoding: UTF-8
 Version: 0.1
-RoxygenNote: 7.1.0.9000
+RoxygenNote: 7.1.1.9000