Add a function to add a knit spin preamble to a script

Author: cderv

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(add_spin_preamble)
 export(check_newer_version)
 export(is_using_quarto)
 export(new_blog_post)

R/spin.R

@@ -0,0 +1,56 @@
+#' Add spin preamble to R script
+#'
+#' Adds a minimal spin preamble to an R script file if one doesn't already exist.
+#' The preamble includes a title derived from the filename and is formatted as
+#' a YAML block suitable preprended with `#'` for [knitr::spin()].
+#'
+#' This is useful to prepare R scripts for use with
+#' Quarto Script rendering support.
+#' See <https://quarto.org/docs/computations/render-scripts.html#knitr>
+#'
+#' @section Preamble format:
+#' For a script named `analysis.R`, the function adds this preamble:
+#' ```
+#' #' ---
+#' #' title: analysis
+#' #' ---
+#' #'
+#'
+#' # Original script content starts here
+#' ```
+#'
+#' This is the minimal preamble required for Quarto Script rendering, so that
+#' [Engine Bindings](https://quarto.org/docs/computations/execution-options.html#engine-binding) works.
+#'
+#' @param script Path to the R script file
+#' @return Invisibly returns the script path if modified, otherwise invisible NULL
+#' @export
+add_spin_preamble <- function(script) {
+  if (!fs::file_exists(script)) {
+    cli::cli_abort(c(
+      "File {.file {script}} does not exist.",
+      "Please provide a valid file path."
+    ))
+  }
+  content <- xfun::read_utf8(script)
+
+  # if files starts with a spin preamble, do nothing
+  if (grepl("^\\s*#'", content[1])) {
+    cli::cli_inform(c(
+      "File {.file {script}} already has a spin preamble.",
+      "No changes made. Edit manually if needed."
+    ))
+    return(invisible())
+  }
+  # prepend the spin preamble
+  filename <- fs::path_file(fs::path_ext_remove(script))
+  preamble <- paste(
+    "#'",
+    xfun::split_lines(as_yaml_block(list(title = filename)))
+  )
+  new_content <- c(preamble, "", content) # Changed "\n" to ""
+  xfun::write_utf8(new_content, con = script)
+
+  cli::cli_inform("Added spin preamble to {.file {script}}")
+  return(invisible(script))
+}

man/add_spin_preamble.Rd

@@ -0,0 +1,9 @@
+# add_spin_preamble checks for file existence
+
+    Code
+      add_spin_preamble("non_existent_file.R")
+    Condition
+      Error in `add_spin_preamble()`:
+      ! File 'non_existent_file.R' does not exist.
+      Please provide a valid file path.
+

tests/testthat/_snaps/spin.md

@@ -0,0 +1,6 @@
+#' ---
+#' title: report
+#' ---
+#' 
+
+

tests/testthat/_snaps/spin/spin_preamble-empty.R

@@ -0,0 +1,7 @@
+#' ---
+#' title: report
+#' ---
+#' 
+
+x <- 1
+y <- 2

tests/testthat/_snaps/spin/spin_preamble.R

@@ -0,0 +1,97 @@
+test_that("add_spin_preamble checks for file existence", {
+  expect_snapshot(
+    error = TRUE,
+    add_spin_preamble("non_existent_file.R")
+  )
+})
+
+test_that("add_spin_preamble adds preamble to file without one", {
+  # Create temporary file
+  tmp_dir <- withr::local_tempdir()
+  withr::local_dir(tmp_dir)
+  script <- "report.R"
+  writeLines(c("x <- 1", "y <- 2"), script)
+
+  # Add preamble
+  expect_message(
+    result <- add_spin_preamble(script),
+    "Added spin preamble"
+  )
+
+  # Check return value
+  expect_equal(result, script)
+
+  announce_snapshot_file(name = "spin_preamble.R")
+  expect_snapshot_file(script, "spin_preamble.R")
+
+  skip_on_cran()
+  skip_if_no_quarto("1.4.511")
+  expect_no_error(
+    quarto_render(script, quiet = TRUE)
+  )
+  expect_true(file.exists(xfun::with_ext(script, "html")))
+})
+
+test_that("add_spin_preamble doesn't modify file with existing preamble", {
+  # Create file with existing preamble
+  tmp_file <- withr::local_tempfile(fileext = ".R")
+  original_content <- c(
+    "#' ---",
+    "#' title: \"Existing Title\"",
+    "#' ---",
+    "#' ",
+    "x <- 1"
+  )
+  xfun::write_utf8(original_content, tmp_file)
+
+  # Try to add preamble
+  expect_message(
+    result <- add_spin_preamble(tmp_file),
+    "already has a spin preamble"
+  )
+
+  # Check return value is invisible
+  expect_invisible(expect_null(result))
+
+  # Check content unchanged
+  new_content <- xfun::read_utf8(tmp_file)
+  expect_equal(new_content, original_content)
+})
+
+test_that("add_spin_preamble detects preamble with leading whitespace", {
+  # Create file with preamble that has leading whitespace
+  tmp_file <- withr::local_tempfile(fileext = ".R")
+  original_content <- c(
+    "  #' This is a comment",
+    "x <- 1"
+  )
+  xfun::write_utf8(original_content, tmp_file)
+
+  expect_message(
+    add_spin_preamble(tmp_file),
+    "already has a spin preamble"
+  )
+
+  # Content should be unchanged
+  new_content <- xfun::read_utf8(tmp_file)
+  expect_equal(new_content, original_content)
+})
+
+test_that("add_spin_preamble works with empty file", {
+  tmp_dir <- withr::local_tempdir()
+  withr::local_dir(tmp_dir)
+  script <- "report.R"
+  writeLines("", script) # Empty file
+
+  # Add preamble
+  expect_message(
+    result <- add_spin_preamble(script),
+    "Added spin preamble"
+  )
+
+  # Check return value
+  expect_equal(result, script)
+
+  announce_snapshot_file(name = "spin_preamble-empty.R")
+  expect_snapshot_file(script, "spin_preamble-empty.R")
+})