Author: Matthew Lincoln
Date: 2022-02-18

# Developing with clipr

#### Matthew Lincoln

#### 2022-02-18

## Calling clipr safely

To check whether the system has been properly configured to allow access to the clipboard, you may run `clipr_available()` which will either return `TRUE` or `FALSE`. This will be particularly useful for Linux-based systems, where clipr’s functionality depends on the installation of additional software. If you wish to display system requirements and configuration messages to X11 and Wayland users, `dr_clipr()` will print these.

## Interactive & non-interactive use

If you use clipr in your own package, you must not try to call it in non-interactive sessions, as this goes against CRAN repository policy:

> Packages should not write in the user’s home filespace (including clipboards), nor anywhere else on the file system apart from the R session’s temporary directory (or during installation in the location pointed to by TMPDIR: and such usage should be cleaned up). Installing into the system’s R installation (e.g., scripts to its bin directory) is not allowed.

> Limited exceptions may be allowed in interactive sessions if the package obtains confirmation from the user.

For this reason, `write_clip()` will error by default in non-interactive use, which includes CRAN tests.

If you want to use `write_clip()` non-interactively, you may either set the environment variable `CLIPR_ALLOW=TRUE` or call `write_clip(..., allow_non_interactive = TRUE)`.

## Testing on CRAN and CI

A few best practices will also help you responsibly test your clipr-using package on headless systems like CRAN or other testing infrastructure like Travis:

1. Examples that will try to use `read_clip()` or `write_clip()` ought to be wrapped in `\dontrun{}`
2. Tests calling clipr should be conditionally skipped, based on the output of `clipr_available()`. This is necessary to pass CRAN checks, as otherwise `write_clip` will error out.
3. If you are using a headless system to check your package build on Linux, consult the GitHub Actions workflow for this package, which includes code for setting the `DISPLAY` and `CLIPR_ALLOW` environment variables, installing `xclip` and `xsel`, and running a pre-build script that will set up `xclip`/`xsel` to run headlessly under XVFB.

## Using clipr with Shiny

clipr won’t do what you expect when you call it with Shiny.

clipr talks to the clipboard of the system that is running R. If you create a Shiny app and tell one of its functions to either read from or write to the clipboard, it can only access the clipboard of the server it is running on. R running on the remote server has no way to access the local clipboard belonging to your end user.

However, you can instruct the user’s internet browser to write to the user’s clipboard by using rclipboard.