R reprex reprex 渲染一个reprex

使用 rmarkdown::render() 运行一些 R 代码并将渲染结果写入用户的剪贴板。如果剪贴板不可用，则会打开包含渲染结果的文件以进行手动复制。目标是轻松共享一个可重现的小示例 ("reprex")，例如在 GitHub 问题中。 Reprex 源可以是

• 从剪贴板读取

• 直接以表达式、字符向量或字符串形式提供

• 从文件中读取

• 从 RStudio 中的当前选择或活动文档中读取

reprex 还可以用于语法突出显示(带或不带渲染)；请参阅下文了解更多信息。

用法

reprex(
  x = NULL,
  input = NULL,
  wd = NULL,
  venue = c("gh", "r", "rtf", "html", "slack", "so", "ds"),
  render = TRUE,
  advertise = NULL,
  session_info = opt(FALSE),
  style = opt(FALSE),
  comment = opt("#>"),
  tidyverse_quiet = opt(TRUE),
  std_out_err = opt(FALSE),
  html_preview = opt(TRUE),
  outfile = deprecated(),
  show = deprecated(),
  si = deprecated()
)

参数

x

一种表达。如果未给出，reprex() 会在 input 中查找代码。如果未提供 input，reprex() 将在剪贴板上查找。

当剪贴板在结构上不可用时(例如，在 RStudio Server 或 RStudio Cloud 上)，reprex() 将查阅当前选择而不是剪贴板。

input

特点。如果长度为 1 并且缺少终止换行符，则解释为包含 reprex 代码的文件的路径。否则，假设将 reprex 代码保存为字符向量。当 input 指定文件路径时，它还确定 reprex 工作目录和所有结果文件的位置。

wd

当 input 不是文件路径时参考的可选文件路径。 (默认情况下，所有工作都在会话临时目录的子目录中悄悄完成。)

wd 最常见的用法是设置 wd = "." ，这意味着“在当前工作目录中代表正确的位置”。如果您确实必须使用本地文件演示某些内容，请执行此操作。

venue

特点。必须是以下之一(不区分大小写)：

• "gh" 代表 GitHub-Flavored Markdown ，默认值

• "r" 用于可运行的 R 脚本，带注释的输出交错。对于 Slack code snippets 也很有用；从 "Type" 下拉菜单中选择 "R" 以享受漂亮的语法突出显示。

• Rich Text Format 的 "rtf"(un-reprexing 不支持)

• "html" 适用于适合包含在较大 HTML 文档中的 HTML 片段(不支持 un-reprexing)

• "slack" 用于粘贴到 Slack 消息中。针对选择退出 Slack 所见即所得接口的用户进行了优化。转到首选项 > 高级 > 输入选项，然后选择“使用标记格式化消息”。 (如果需要针对所见即所得进行优化的第二个 Slack 场地，请提出问题进行讨论。)

• "so"为Stack Overflow Markdown。注意：这只是 "gh" 的别名，因为 Stack Overflow 于 2019 年 1 月开始支持 CommonMark 风格的隔离代码块。

• "ds" 用于话语，例如 community.rstudio.com 。注意：这目前只是 "gh" 的别名。

render

逻辑性强。是否在模板化的reprex上调用rmarkdown::render()，即是否实际运行代码。默认为 TRUE 。存在主要是为了内部测试。

advertise

逻辑性强。是否包含说明 reprex 创建时间和方式的页脚。如果未指定，则参考选项 reprex.advertise，如果未定义，则默认为 TRUE(对于 "gh" 、 "html" 、 "so" 、 "ds" )；且 FALSE 对应 "r" 、 "rtf" 、 "slack" 。

session_info

逻辑性强。是否在表示末尾包含 sessioninfo::session_info() (如果可用)或 sessionInfo() 。当venue 为"gh" 时，会话信息包含在可折叠详细信息标签中。阅读有关 opt() 的更多信息。

style

逻辑性强。是否设置knitr chunk选项tidy = "styler"，它使用styler package重新设置代码样式。阅读有关 opt() 的更多信息。

comment

特点。用于注释输出的前缀，默认为 "#>" 。阅读有关 opt() 的更多信息。

tidyverse_quiet

逻辑性强。设置选项 tidyverse.quiet 和 tidymodels.quiet ，它们抑制( TRUE ，默认值)或包含( FALSE ) tidyverse 和 tidymodels 包的启动消息。阅读有关 opt() 的更多信息。

std_out_err

逻辑性强。是否为 reprex 渲染进程发送到 stdout 和 stderr 的输出附加一个部分。如果 reprex 生成子进程或 system() 调用，这可能是显示输出所必需的。请注意，这不能与主 R 进程的输出正确交错，也不能保证标准输出和标准错误中的行按正确的时间顺序排列。有关更多信息，请参阅callr::r()。阅读有关 opt() 的更多信息。

html_preview

逻辑性强。是否在查看器(RStudio 或浏览器)中显示渲染输出。在非交互式会话中始终FALSE。阅读有关 opt() 的更多信息。

outfile

有利于wd或提供文件路径input。要在当前工作目录中表示，请使用wd = "."现在，而不是outfile = NA.

show

有利于html_preview，以提高与其他 R Markdown 输出格式的一致性。

si

有利于session_info.

值

渲染的 reprex 的字符向量，不可见。

细节

通常的“代码+注释输出”以不可见的方式返回，写入文件，并尽可能放在剪贴板上。 HTML 预览显示在 RStudio 的查看器窗格中(如果可用)，否则显示在默认浏览器中。前导 "> " 提示将从输入代码中删除。阅读更多内容https://reprex.tidyverse.org/。

reprex 设置特定的 knitr options ：

• 块选项默认为 collapse = TRUE 、 comment = "#>" 、 error = TRUE 。请注意 error = TRUE ，因为常见的用例是错误报告。

• reprex 还设置 knitr 的 upload.fun 。它默认为 knitr::imgur_upload()，因此 reprex 生成的数字可以正确显示在 GitHub、Stack Overflow、Discourse 和 Slack 上。请注意，imgur_upload() 需要 httr 和 xml2 包。当 venue = "r" 、 upload.fun 设置为 identity() 时，数字保持本地状态。在这种情况下，您可能还需要提供 input 的文件路径或设置 wd ，以控制 reprex 文件的写入位置。您可以在代码中使用特殊注释来补充或覆盖这些选项(请参阅示例)。

错误回溯

reprex 设置 rlang 选项 rlang_backtrace_on_error_report = "full" 。与 knitr 选项 error = TRUE 结合使用，这意味着 rlang 错误将通过完整的回溯显示。这本质上消除了显式调用 rlang::last_error() 或 rlang::last_trace() 的需要，尽管这些函数可以在 reprex 中使用。

在 error-causing 代码和 last_error() 或 last_trace() 调用之间插入包含特殊注释 #' 的行，以满足位于单独块中的要求：

f <- function() rlang::abort('foo')
f()
#'
rlang::last_error()
rlang::last_trace()

请阅读 rlang 文档了解更多信息：Errors in RMarkdown。

语法高亮

reprex 的第二个用例是生成语法突出显示的代码片段(无论是否渲染)，以粘贴到 Microsoft Word、PowerPoint 或 Keynote 等应用程序中。为此，请使用venue = "rtf"。

此函数是实验性的，需要安装highlight 命令行工具。 "rtf" 场地记录在 its own article 中

例子

if (FALSE) {
# put some code like this on the clipboard
# (y <- 1:4)
# mean(y)
reprex()

# provide code as an expression
reprex(rbinom(3, size = 10, prob = 0.5))
reprex({y <- 1:4; mean(y)})
reprex({y <- 1:4; mean(y)}, style = TRUE)

# note that you can include newlines in those brackets
# in fact, that is often a good idea
reprex({
  x <- 1:4
  y <- 2:5
  x + y
})

## provide code via character vector
reprex(input = c("x <- 1:4", "y <- 2:5", "x + y"))

## if just one line, terminate with '\n'
reprex(input = "rnorm(3)\n")

## customize the output comment prefix
reprex(rbinom(3, size = 10, prob = 0.5), comment = "#;-)")

# override a default chunk option
reprex({
  #+ setup, include = FALSE
  knitr::opts_chunk$set(collapse = FALSE)

  #+ actual-reprex-code
  (y <- 1:4)
  median(y)
})

# add prose, use general markdown formatting
reprex({
  #' # A Big Heading
  #'
  #' Look at my cute example. I love the
  #' [reprex](https://github.com/tidyverse/reprex#readme) package!
  y <- 1:4
  mean(y)
}, advertise = FALSE)

# read reprex from file and write resulting files to that location
tmp <- file.path(tempdir(), "foofy.R")
writeLines(c("x <- 1:4", "mean(x)"), tmp)
reprex(input = tmp)
list.files(dirname(tmp), pattern = "foofy")

# clean up
file.remove(list.files(dirname(tmp), pattern = "foofy", full.names = TRUE))

# write reprex to file AND keep figure local too, i.e. don't post to imgur
tmp <- file.path(tempdir(), "foofy")
dir.create(tmp)
reprex({
  #+ setup, include = FALSE
  knitr::opts_knit$set(upload.fun = identity)

  #+ actual-reprex-code
  #' Some prose
  ## regular comment
  (x <- 1:4)
  median(x)
  plot(x)
  }, wd = tmp)
list.files(dirname(tmp), pattern = "foofy")

# clean up
unlink(tmp, recursive = TRUE)

## target venue = R, also good for email or Slack snippets
ret <- reprex({
  x <- 1:4
  y <- 2:5
  x + y
}, venue = "R")
ret

## target venue = html
ret <- reprex({
  x <- 1:4
  y <- 2:5
  x + y
}, venue = "html")
ret

## include prompt and don't comment the output
## use this when you want to make your code hard to execute :)
reprex({
  #+ setup, include = FALSE
  knitr::opts_chunk$set(comment = NA, prompt = TRUE)

  #+ actual-reprex-code
  x <- 1:4
  y <- 2:5
  x + y
})

## leading prompts are stripped from source
reprex(input = c("> x <- 1:3", "> median(x)"))
}