Simplifying File-based Examples with @examplesTempdir in R Packages

The CRAN File Writing Policy

If you’ve ever submitted a package to CRAN with file writing capabilities, you’ve likely encountered this 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. …

-– CRAN Repository Policy - Revision: 6286

If you’re like me, you’ve probably had a few packages flagged for this issue and the reviewers gently remind you to fix it with:

Please ensure that your functions do not write by default or in your examples/vignettes/tests in the user’s home filespace (including the package directory and getwd()). This is not allowed by CRAN policies. Please omit any default path in writing functions. In your examples/vignettes/tests you can write to tempdir().

– CRAN Cookbook: Code Issues

This makes perfect sense - we don’t want our package examples creating files in users’ working directories when they run example() or read the documentation.

The Traditional Solution: Manual tempdir() Wrappers

For years, the standard approach has been to manually wrap our example code with temporary directory handling:

#' @examples
#' \dontshow{.old_wd <- setwd(tempdir())}
#'
#' # Your example code here
#' write.csv(mtcars, "example.csv")
#' file.exists("example.csv")
#'
#' \dontshow{setwd(.old_wd)}

This pattern:

1. Saves the current working directory
2. Switches to a temporary directory
3. Runs your example code (which can create files safely)
4. Restores the original working directory

The \dontshow{} ensures these setup/teardown lines don’t appear in rendered documentation so users can focus on the actual example code. It’s a bit clunky, but it works.

Enter @examplesTempdir: A Cleaner Approach

Back in 2018, I wrote about this pattern as a way to handle the CRAN requirement. But honestly, I’m tired of typing those same directory management lines over and over.

That’s why I created the @examplesTempdir tag in my new {rocleteer} package (Package website) (it’s in incubator status). It transforms this:

#' @examplesTempdir
#' # Your example code here
#' write.csv(mtcars, "example.csv")
#' file.exists("example.csv")

Into the complete wrapped version automatically during roxygen processing shown above.

How to Use @examplesTempdir

1. Install {rocleteer} from GitHub:

# install.packages("remotes")
remotes::install_github("coatless-rpkg/rocleteer")

2. Add {rocleteer} to your package’s DESCRIPTION file:

# In your DESCRIPTION file
Suggests:
    rocleteer

Remotes:
    coatless-rpkg/rocleteer
    
Roxygen: list(markdown = TRUE, packages = "rocleteer")

3. Use @examplesTempdir instead of @examples when your examples need to create files:

#' My Function That Creates Files
#'
#' @examplesTempdir
#' # This runs in tempdir() automatically
#' df <- data.frame(x = 1:5, y = letters[1:5])
#' write.csv(df, "test.csv")
#' read.csv("test.csv")

4. Document your package as usual with devtools::document() or roxygen2::roxygenize().

Example: peeky

As I work to onboard more packages to CRAN like peeky, I’ve been gently reminded of the file writing policy. So, to dog food my own package, I’ve added @examplesTempdir to the package’s documentation!

It made the examples cleaner and ensures they comply with CRAN’s requirements.

Bonus: RStudio Integration

To make adoption even easier, the package includes an RStudio addin to insert the template for you. Just search for "Insert examplesTempdir" in the: Tools -> Addins -> Browse Addins menu. With one keyboard shortcut, you can add the tag and focus on writing your actual example code.

Combining @examples with @examplesTempdir

You might wonder - what if I want some examples to run in the current working directory and others in a temporary directory? You have options!

Since @examplesTempdir transforms into an @examples tag during processing, you can:

1. Use either @examples OR @examplesTempdir for different functions in your package
2. Split your examples within a single function:

#' My combined function
#'
#' @examples
#' # These examples run in the normal working directory
#' 1 + 1
#' plot(1:10)
#'
#' @examplesTempdir
#' # These examples run in tempdir()
#' write.csv(mtcars, "mtcars.csv")
#' file.exists("mtcars.csv")

Both sets of examples will appear correctly in your documentation, with the file operations safely contained in a temporary directory.

Technical Details

For those interested in the technical details, @examplesTempdir follows Extending roxygen2: Adding a new .Rd tag section of the roxygen2 documentation. The process involves:

1. Creating a custom {roxygen2} tag parser, e.g. roxy_tag_parse.*().
2. Transforming the raw contents into a @examples tag with added tempdir() and setwd() handling.
3. Processing the result through roxygen2’s standard examples handler, e.g. roxy_tag_rd.*().

The implementation is surprisingly small - just about 20 lines of code! The majority of the work was on documentation and testing to ensure it behaves as expected.

A Note on Default Behavior

Ideally, this tempdir() handling would be the default behavior for all examples that write files. However, given how long {roxygen2} has been around and its widespread usage, it’s likely safer not to modify the default behavior. Changing defaults in established packages can lead to unexpected issues for existing users.

By implementing this as an opt-in tag through {rocleteer}, we get the immediate benefits without disrupting existing workflows. Perhaps someday {roxygen2} might consider incorporating a similar feature directly, but for now, this extension approach strikes a good balance. At least, that’s my hope!

Future Extensions Tags

The @examplesTempdir tag is just the beginning. I’ve made this functionality available in the {rocleteer} package, which is designed to be a collection of roxygen2 extensions. Specifically, the package name hints at its purpose - a place for roxygen “roclets” and related tools that enhance the documentation experience.

In the future, I plan to add more custom tags and roclets to address other common documentation pain points. The package structure is set up to make it easy to extend with additional functionality.

Troubleshooting

• Q: Will this affect package checks?
  A: No, the roxygen processing happens before R CMD check runs.

• Q: Can I use this with @examplesIf?
  A: Yes! You can combine it with other roxygen tags.

Conclusion

Small quality-of-life improvements like @examplesTempdir make package development more pleasant. Sometimes the best tools are the ones that remove annoyances you’ve gotten so used to that you barely notice them anymore.

Happy documenting!