R: Render a reprex

reprex {reprex} | R Documentation

## 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

### Usage

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

### 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: "gh" for GitHub, the default "so" for Stack Overflow "ds" for Discourse, e.g., community.rstudio.com. Note: this is currently just an alias for "gh"! "r" or "R" for a runnable R script, with commented output interleaved
`advertise` | Logical. Whether to include a footer that describes when and how the reprex was created. Read more about `opt()`.
`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()`.
`opts_chunk, opts_knit` | Named list. Optional knitr chunk and package options that are forwarded to `knitr::opts_chunk$set()` and `knitr::opts_knit$set()`, respectively.
`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()`.
`render` | Logical. Whether to render the reprex or just create the templated `.R` file. Defaults to `TRUE`. Mostly for internal testing purposes.

### 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 http://reprex.tidyverse.org/.

reprex sets specific knitr options, which you can supplement or override via the `opts_chunk` and `opts_knit` arguments or via explicit calls to knitr in your reprex code (see examples). If all you want to override is the `comment` option, use the dedicated argument, e.g.`commment = "#;-)"`.

- 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`.

### Value

Character vector of rendered reprex, invisibly.

### Examples

    ## 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, in general
    reprex({(y <- 1:4); median(y)}, opts_chunk = list(collapse = FALSE))
    # the above is simply shorthand for this and produces same result
    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({
      #' Some prose
      ## regular comment
      (x <- 1:4)
      median(x)
      plot(x)
      }, outfile = tmp, opts_knit = list(upload.fun = identity))
    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

    ## include prompt and don't comment the output
    ## use this when you want to make your code hard to execute :)
    reprex({
      x <- 1:4
      y <- 2:5
      x + y
    }, opts_chunk = list(comment = NA, prompt = TRUE))

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

    ## End(Not run)

[Package reprex version 0.2.0 Index]