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)"))
}