Render a reprex

Source: R/reprex.R

Run a bit of R code using rmarkdown::render() and write the rendered result to user's clipboard. If the clipboard is unavailable, the file containing the rendered result is opened for manual copy. The goal is to make it easy to share a small reproducible example ("reprex"), e.g., in a GitHub issue. Reprex source can be

  • read from clipboard

  • provided directly as expression, character vector, or string

  • read from file

  • read from current selection or active document in RStudio

reprex can also be used for syntax highlighting (with or without rendering); see below for more.

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()
)

Arguments

x

An expression. If not given, reprex() looks for code in input. If input is not provided, reprex() looks on the clipboard.

When the clipboard is structurally unavailable, e.g., on RStudio Server or RStudio Cloud, reprex() consults the current selection instead of the clipboard.

input

Character. If has length one and lacks a terminating newline, interpreted as the path to a file containing reprex code. Otherwise, assumed to hold reprex code as character vector. When input specifies a filepath, it also determines the reprex working directory and the location of all resulting files.

wd

An optional filepath that is consulted when input is not a filepath. (By default, all work is done, quietly, in a subdirectory of the session temp directory.)

The most common use of wd is to set wd = ".", which means "reprex right HERE in the current working directory". Do this if you really must demonstrate something with local files.

venue

Character. Must be one of the following (case insensitive):

  • "gh" for GitHub-Flavored Markdown, the default

  • "r" for a runnable R script, with commented output interleaved. Also useful for Slack code snippets; select "R" from the "Type" drop-down menu to enjoy nice syntax highlighting.

  • "rtf" for Rich Text Format (not supported for un-reprexing)

  • "html" for an HTML fragment suitable for inclusion in a larger HTML document (not supported for un-reprexing)

  • "slack" for pasting into a Slack message. Optimized for people who opt out of Slack's WYSIWYG interface. Go to Preferences > Advanced > Input options and select "Format messages with markup". (If there is demand for a second Slack venue optimized for use with WYSIWYG, please open an issue to discuss.)

  • "so" for Stack Overflow Markdown. Note: this is just an alias for "gh", since Stack Overflow started to support CommonMark-style fenced code blocks in January 2019.

  • "ds" for Discourse, e.g., forum.posit.co. Note: this is currently just an alias for "gh".

render

Logical. Whether to call rmarkdown::render() on the templated reprex, i.e. whether to actually run the code. Defaults to TRUE. Exists primarily for the sake of internal testing.

advertise

Logical. Whether to include a footer that describes when and how the reprex was created. If unspecified, the option reprex.advertise is consulted and, if that is not defined, default is TRUE for venues "gh", "html", "so", "ds" and FALSE for "r", "rtf", "slack".

session_info

Logical. Whether to include sessioninfo::session_info(), if available, or sessionInfo() at the end of the reprex. When venue is "gh", the session info is wrapped in a collapsible details tag. Read more about opt().

style

Logical. Whether to set the knitr chunk option tidy = "styler", which re-styles code with the styler package. Read more about opt().

comment

Character. Prefix with which to comment out output, defaults to "#>". Read more about opt().

tidyverse_quiet

Logical. Sets the options tidyverse.quiet and tidymodels.quiet, which suppress (TRUE, the default) or include (FALSE) the startup messages for the tidyverse and tidymodels packages. Read more about opt().

std_out_err

Logical. Whether to append a section for output sent to stdout and stderr by the reprex rendering process. This can be necessary to reveal output if the reprex spawns child processes or system() calls. Note this cannot be properly interleaved with output from the main R process, nor is there any guarantee that the lines from standard output and standard error are in correct chronological order. See callr::r() for more. Read more about opt().

html_preview

Logical. Whether to show rendered output in a viewer (RStudio or browser). Always FALSE in a noninteractive session. Read more about opt().

outfile

[Deprecated] in favor of wd or providing a filepath to input. To reprex in current working directory, use wd = "." now, instead of outfile = NA.

show

[Deprecated] in favor of html_preview, for greater consistency with other R Markdown output formats.

si

[Deprecated] in favor of session_info.

Value

Character vector of rendered reprex, invisibly.

Details

The usual "code + commented output" is returned invisibly, written to file, and, whenever possible, put on the clipboard. An HTML preview displays in RStudio's Viewer pane, if available, or in the default browser, otherwise. Leading "> " prompts, are stripped from the input code. Read more at https://reprex.tidyverse.org/.

reprex sets specific knitr options:

  • Chunk options default to collapse = TRUE, comment = "#>", error = TRUE. Note that error = TRUE, because a common use case is bug reporting.

  • reprex also sets knitr's upload.fun. It defaults to knitr::imgur_upload() so figures produced by the reprex appear properly on GitHub, Stack Overflow, Discourse, and Slack. Note that imgur_upload() requires the packages httr and xml2. When venue = "r", upload.fun is set to identity(), so that figures remain local. In that case, you may also want to provide a filepath to input or set wd, to control where the reprex files are written. You can supplement or override these options with special comments in your code (see examples).

Error backtraces

To use rlang::last_error() or rlang::last_trace() within a reprex, you must place them in a different "chunk" to the code that generates an error. The easiest way to do is to insert a line containing the special comment #' after error-causing code:

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

Read more in rlang's documentation: Errors in RMarkdown.

Syntax highlighting

[Experimental]

A secondary use case for reprex is to produce syntax highlighted code snippets, with or without rendering, to paste into applications like Microsoft Word, PowerPoint, or Keynote. Use venue = "rtf" for this.

This feature is experimental and requires the installation of the highlight command line tool. The "rtf" venue is documented in its own article

Examples

if (FALSE) { # \dontrun{
# 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)"))
} # }