reprex (version 0.3.0)

reprex: Render a reprex

Description

Run a bit of R code using rmarkdown::render() and write the rendered result to user's clipboard. 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

  • read from current selection or active document in RStudio (with reprex_addin())

  • provided directly as expression, character vector, or string

  • read from file

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

Usage

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

Arguments

x

An expression. If not given, reprex() looks for code in input or on the clipboard, in that order.

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.

outfile

Optional basename for output files. When NULL (default), reprex writes to temp files below the session temp directory. If outfile = "foo", expect output files in current working directory, like foo_reprex.R, foo_reprex.md, and, if venue = "r", foo_rendered.R. If outfile = NA, expect output files in a location and with basename derived from input, if sensible, or in current working directory with basename derived from tempfile() otherwise.

venue

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

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", "so", "ds", "html" and FALSE for "r" and "rtf".

si

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

style

Logical. Whether to style code with styler::style_text(). Read more about opt().

show

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

comment

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

tidyverse_quiet

Logical. Sets the option tidyverse.quiet, which suppresses (TRUE, the default) or includes (FALSE) the startup message for the tidyverse package. 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_safe() for more. Read more about opt().

Value

Character vector of rendered reprex, invisibly.

Syntax highlighting

A secondary use case for reprex is to produce syntax highlighted code snippets, with or without rendering, to paste into presentation software, such as Keynote or PowerPoint. Use venue = "rtf".

This feature is experimental and currently rather limited. It probably only works on macOS and requires the installation of the highlight command line tool, which can be installed via homebrew. This venue is discussed in an article

Details

The usual "code + commented output" is returned invisibly, put on the clipboard, and written to file. 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, or Discourse. Note that this function requires the packages httr & xml2 or RCurl & XML, depending on your knitr version. When venue = "r", upload.fun is set to identity, so that figures remain local. In that case, you may also want to set outfile. You can supplement or override these options with special comments in your code (see examples).

Examples

Run this code
# NOT RUN {
# 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
tmp <- file.path(tempdir(), "foofy.R")
writeLines(c("x <- 1:4", "mean(x)"), tmp)
reprex(input = tmp)

# read from file and write to similarly-named outfiles
reprex(input = tmp, outfile = NA)
list.files(dirname(tmp), pattern = "foofy")

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

# write rendered reprex to file
tmp <- file.path(tempdir(), "foofy")
reprex({
  x <- 1:4
  y <- 2:5
  x + y
}, outfile = 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")
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)
  }, outfile = tmp)
list.files(dirname(tmp), pattern = "foofy")

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

## target venue = Stack Overflow
## https://stackoverflow.com/editing-help
ret <- reprex({
  x <- 1:4
  y <- 2:5
  x + y
}, venue = "so")
ret

## 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)"))
# }
# NOT RUN {
# }

Run the code above in your browser using DataLab