This function generates example code that runs in a temporary directory
by automatically wrapping the code with the appropriate setup and teardown calls.
When roxygen2 processes your documentation, the @examplesTempdir tag is transformed into
an @examples tag with temporary directory handling, eliminating the need to manually
include these calls in your documentation.
Details
The tag addresses a common need when writing package examples that create files or modify the filesystem. Running such examples in a temporary directory prevents cluttering the user's working directory with test files and ensures clean package checks.
Implementation
When the @examplesTempdir tag is processed, it is transformed into an @examples tag with
the following wrapper code automatically added:
\dontshow{.old_wd <- setwd(tempdir())}
# Your example code here
\dontshow{setwd(.old_wd)}
The temporary directory setup saves the current working directory, switches to tempdir(),
and then restores the original working directory when the example code has finished executing.
This is all hidden from the user in the final documentation using \dontshow{}.
Use Cases
The @examplesTempdir tag is particularly useful for:
Examples that create or write to files
Examples that need to test file operations
Examples that should not modify the user's working directory
Any code that should run in an isolated directory environment
Package Configuration
To use the @examplesTempdir tag in your package, add rocleteer to your
package dependencies and configure roxygen2 to use the rocleteer:
In your DESCRIPTION file:
where ... could be roclets = c("collate", "namespace", "rd").
Examples
# A function that writes a file and needs to run in a temporary directory
#
#' @title Write CSV to a File
#' @description
#' This function writes a data frame to a CSV file
#'
#' @param data A data frame to write
#' @param filename Name of the file to write
#'
#' @return
#' Invisibly returns the input data frame
#'
#' @examplesTempdir
#' # Create a data frame
#' df <- data.frame(x = 1:5, y = letters[1:5])
#'
#' # Write to a file
#' write.csv(df, "test.csv", row.names = FALSE)
#'
#' # Check that the file exists
#' file.exists("test.csv")
#'
#' # Read it back
#' read.csv("test.csv")