Prepare Reproducible Example Code via the Clipboard

Convenience wrapper that uses the 'rmarkdown' package to render small snippets of code to target formats that include both code and output. The goal is to encourage the sharing of small, reproducible, and runnable examples on code-oriented websites, such as < https://stackoverflow.com> and < https://github.com>, or in email. The user's clipboard is the default source of input code and the default target for rendered output. 'reprex' also extracts clean, runnable R code from various common formats, such as copy/paste from an R session.


CRAN_Status_Badge Travis-CI BuildStatus AppVeyor BuildStatus Coveragestatus lifecycle

Prepare reprexes for posting to GitHub issues, StackOverflow, or Slack snippets. What is a reprex? It’s a reproducible example, as coined by Romain Francois.

Given R code on the clipboard, selected in RStudio, as an expression (quoted or not), or in a file …

  • run it via rmarkdown::render(),
  • with deliberate choices re: arguments and setup chunk.

Get resulting runnable code + output as

  • Markdown, formatted for target venue, e.g. gh or so, or as
  • R code, augmented with commented output.

Result is returned invisibly, placed on the clipboard, and written to a file. Preview an HTML version in RStudio viewer or default browser.

Installation

Install from CRAN:

install.packages("reprex")

or get a development version from GitHub:

devtools::install_github("tidyverse/reprex")

On Linux, you probably want to install xclip or xsel, so reprex can access the X11 clipboard. This is ‘nice to have’, but not mandatory. The usual sudo apt-get install or sudo yum install installation methods should work for both xclip and xsel.

Usage

Let’s say you copy this code onto your clipboard:

(y <- 1:4)
mean(y)

Then call reprex(), where the default target venue is GitHub:

reprex()

A nicely rendered HTML preview will display in RStudio’s Viewer (if you’re in RStudio) or your default browser otherwise.

The relevant bit of GitHub-flavored Markdown is ready to be pasted from your clipboard:

``` r
(y <- 1:4)
#> [1] 1 2 3 4
mean(y)
#> [1] 2.5
```

Here’s what that Markdown would look like rendered in a GitHub issue:

(y <- 1:4)
#> [1] 1 2 3 4
mean(y)
#> [1] 2.5

Anyone else can copy, paste, and run this immediately.

Instead of reading from the clipboard, you can:

  • reprex(mean(rnorm(10))) to get code from expression.

  • reprex(input = "mean(rnorm(10))\n") gets code from character vector (detected via length or terminating newline). Leading prompts are stripped from input source: reprex(input = "> median(1:3)\n") produces same output as reprex(input = "median(1:3)\n")

  • reprex(input = "my_reprex.R") gets code from file

  • Use one of the RStudio add-ins to use the selected text or current file.

But wait, there’s more!

  • Set the target venue to Stack Overflow with reprex(..., venue = "so").

  • Get a runnable R script, augmented with commented output, with reprex(..., venue = "R"). This is useful for Slack, email, etc.

  • Prepare rendered, syntax-highlighted code snippets to paste into Keynote or PowerPoint, with reprex(..., venue = "rtf"). This feature is still experimental; see the associated article for more.

  • By default, figures are uploaded to imgur.com and the resulting URL is dropped into an inline image tag.

  • Use the outfile argument to control where results are left behind. Use outfile = NA to work in current working directory.

  • Get clean, runnable code from wild-caught reprexes with

    • reprex_invert() = the opposite of reprex()
    • reprex_clean(), e.g. when you copy/paste from GitHub or Stack Overflow
    • reprex_rescue(), when you’re dealing with copy/paste from R Console

Please note that the reprex project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

News

reprex 0.2.1

  • The reprex ad is formatted as superscript for venue = "gh" and venue = "so", i.e. it is more subtle (#201).

  • New experimental venue "rtf" produces syntax highlighted snippets suitable for pasting into presentation software such as Keynote or PowerPoint. This venue is discussed in an article (#26).

  • Arguments opts_chunk and opts_knit have been removed from reprex(). The same effect has always been achievable via roxygen comments in the reprex code and the examples have always demonstrated this. Overriding knitr options doesn't seem to come up often enough in real-world reprex() usage to justify these arguments.

  • Internal file system operations use the fs package. This should not make any user-facing changes in reprex and we definitely want to know if it does.

reprex 0.2.0

reprex has a website: https://reprex.tidyverse.org. It includes a contributed article from @njtierney (#103).

reprex has moved to the tidyverse Organization. It is installed as part of the tidyverse meta-package and is suggested to those seeking help.

reprex() gains several arguments and many arguments can now be controlled via an option, in case a user wants their own defaults.

The new reprex_selection() add-in reprexes the current selection, with venue controlled by the option reprex.venue. It can be handy to bind to a keyboard shortcut (#84 @hadley).

If reprex can't write to the user's clipboard (e.g. on RStudio server or Unix-like systems lacking xclip or xsel), it offers to open the output file for manual copy.

Option-controlled arguments for custom defaults

These look like reprex(..., arg = opt(DEFAULT), ...) in the help file. This is shorthand for arg = getOption("reprex.arg", DEFAULT), i.e. the option reprex.arg is consulted and, if unset, the documented default is used. Allows user to define their own default behaviour (#116).

New arguments to reprex():

  • advertise: toggles inclusion of a footer that describes when and how the reprex was created, e.g., "Created on 2017-11-16 by the reprex package (v0.1.1.9000)". Defaults to TRUE (#121, #69).
  • style: requests code restyling via the newly-Suggested styler package. styler can cope with tidyeval syntactical sugar, e.g. df %>% group_by(!! group_var). Defaults to FALSE (#108, #94).
  • tidyverse_quiet: affords control of the startup message of the tidyverse meta-package. Defaults to TRUE, i.e. suppresses the message (important special case of #70, #100).
  • std_out_err: appends 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 has system() calls. Defaults to FALSE (#90, #110).
  • render: determines if the reprex is actually rendered or just returns after producing the templated .R file. For internal testing.

Venues

  • Line wrapping is preserved from source via a Pandoc option (#145 @jimhester, #175).

  • venue = "gh" now targets CommonMark as the standard for GitHub Flavored Markdown (#77).

  • venue = "so" has appropriate whitespace at the start.

  • venue = "ds" is a new value, corresponding to https://www.discourse.org, which is the platform behind community.rstudio.com. This is currently just an alias for the default "gh" GitHub venue, because the formatting appears to be compatible. Adding the "ds" value so Discourse can be documented and to guard against the possibility that some formatting is actually unique.

Other changes

  • The keep.source option is set to TRUE when rendering the reprex, so reprexes involving srcrefs should work (#152).

  • The "undo" functions (reprex_invert(), reprex_clean(), reprex_rescue()) handle input and outfile like reprex() does. The outfile argument is new (#129, #68).

  • The default value for knitr's upload.fun is now set according to the venue. It is knitr::imgur_upload() for all venues except "r", where it is identity (#125).

  • The HTML preview should appear in the RStudio Viewer more consistently, especially on Windows (#75 @yutannihilation).

  • More rigorous use of UTF-8 encoding (#76 @yutannihilation).

  • Expression input handling has been refactored. As a result, formatR is no longer Suggested. Trailing comments -- inline and on their own line -- are also now retained (#89, #91, #114, @jennybc and @jimhester).

  • Custom prompts are now escaped when used in regexes (#98, #99 @jimhester). Embedded newlines are now escaped.

reprex 0.1.2

This was a non-functioning release created by CRAN maintainers by commenting out lines of code relating to the clipboard.

reprex 0.1.1

  • pandoc added to SystemRequirements.

reprex 0.1.0

  • outfile = NA causes outfiles to be left in working directory. Filenames will be based on the input file, if there was one.

  • reprex() strips any leading prompts from input code.

  • Added functions reprex_clean(), reprex_invert(), and reprex_rescue() in order to go backwards, i.e. recover source from a wild-caught reprex.

  • venue = "R" (or "r") can be used to get an R script back, augmented with commented output.

  • comment argument added to specify prefix for commented output.

  • Added an RStudio addin, accessed via "Render reprex".

  • input argument to reprex() and friends handles code as string, character vector, or file path.

  • The reprex is rendered via callr::r_safe() and is thus run in a clean, separate R process, eliminating any leakage of objects or loaded packages to/from the calling session.

  • reprex() gains optional arguments opts_chunk and opts_knit, taking named list as input, in order to supplement or override default knitr chunk and package options, respectively. (#33)

    • This made the explicit upload.fun argument unnecessary, so it's gone. The upload.fun option defaults to knitr::imgur_upload, which means figures produced by the reprex will be uploaded to imgur.com and the associated image syntax will be put into the Markdown, e.g. ![](http://i.imgur.com/QPU5Cg9.png). (#15 @paternogbc)
  • Order of reprex() arguments has changed.

  • reprex() gains the si argument to request that devtools::session_info() or sessionInfo() be appended to reprex code (#6 @dgrtwo). When si = TRUE and venue = "gh" (the default), session info is wrapped in a collapsible details tag. See an example (#55).

  • Reprex code can be provided as an R expression. (#6 @dgrtwo, #35)

  • reprex() uses clipboard functionality from clipr and thus should work on Windows and suitably prepared Unix-like systems, in addition to Mac OS. (#16 @mdlincoln)

reprex 0.0.0.9000

  • I tweeted about this and some people actually used it!

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("reprex")

0.2.1 by Jennifer Bryan, 3 months ago


https://reprex.tidyverse.org, https://github.com/tidyverse/reprex#readme


Report a bug at https://github.com/tidyverse/reprex/issues


Browse source code at https://github.com/cran/reprex


Authors: Jennifer Bryan [aut, cre] , Jim Hester [aut] , David Robinson [aut] , Hadley Wickham [aut] , RStudio [cph, fnd]


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports callr, clipr, fs, rlang, rmarkdown, tools, utils, whisker, withr

Suggests covr, devtools, fortunes, knitr, miniUI, rprojroot, rstudioapi, shiny, styler, testthat

System requirements: pandoc (>= 1.12.3) - http://pandoc.org


Imported by tidyverse.


See at CRAN