Improve quarto_use_template (#261)

* Improve quarto_use_template

- Support using in another empty directory
- Fails on non-empty directory as interactive prompting is required done by Quarto CLI directly (only for 1.5.15+)

* Add NEWS

* Bump version

Author: cderv

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: quarto
 Title: R Interface to 'Quarto' Markdown Publishing System
-Version: 1.4.4.9020
+Version: 1.4.4.9021
 Authors@R: c(
     person("JJ", "Allaire", , "[email protected]", role = "aut",
            comment = c(ORCID = "0000-0003-0174-9868")),

NEWS.md

@@ -2,6 +2,8 @@
 
 - `quarto_create_project()` gains a `title` argument to set the project title independently from the directory name. This allows creating projects with custom titles, including when using `name = "."` to create a project in the current directory (thanks, @davidkane9, #148). This matches with `--title` addition for `quarto create project` in Quarto CLI v1.5.15.
 
+- `quarto_use_template()` now supports using templates in another empty directory via the `dir` argument. However, the function will fail with a clear error message when used in non-empty directories, as interactive prompting is required and handled by Quarto CLI directly (requires Quarto 1.5.15+). Follow for [quarto-dev/quarto-cli#11127](https://github.com/quarto-dev/quarto-cli/issues/11127) for change with `--no-prompt` behavior in future Quarto versions.
+
 - `quarto_render(output_file = )` now sets the `output-file` Quarto metadata instead of the `--output` CLI flag. This allows the output file information to correctly be processed by Quarto, as if passed in a YAML header. e.g. it allows to support multiple output formats in the same render call. `quarto_render(quarto_args = c('--output', 'dummy.html'))` can still be used to set the `--output` CLI flag to enforce using the CLI flag and not the metadata processed by Quarto (#251, #43).
 
 - Added `check_newer_version()` function to check if a newer version of Quarto is available. The function compares the current Quarto version against the latest stable and prerelease versions. It is aimed for verbosity by default (`verbose = TRUE`), but `verbose = FALSE` can also be set for just checking update availability with TRUE or FALSE return values. Version information is cached per session for up to 24 hours to minimize network requests.

R/use.R

@@ -8,28 +8,42 @@
 #' @param template The template to install, either an archive or a GitHub
 #'   repository as described in the documentation
 #'   <https://quarto.org/docs/extensions/formats.html>.
-#'
+#' @param dir The directory in which to install the template. This must be an empty directory.
+#'   To use directly in a non-empty directory, use `quarto use template` interactively in the terminal for safe installation
+#'   without overwrite.
 #' @param quiet Suppress warnings and messages.
 #'
 #'
 #' @examples
 #' \dontrun{
-#' # Install a template and set up a draft document from a GitHub repository
+#' # Use a template and set up a draft document from a GitHub repository
 #' quarto_use_template("quarto-journals/jss")
 #'
-#' # Install a template and set up a draft document from a ZIP archive
+#' # Use a template in current directory by installing it in an empty directory
+#' quarto_use_template("quarto-journals/jss", dir = "new-empty-dir")
+#'
+#' # Use a template and set up a draft document from a ZIP archive
 #' quarto_use_template("https://github.com/quarto-journals/jss/archive/refs/heads/main.zip")
 #' }
 #'
 #' @export
 quarto_use_template <- function(
   template,
+  dir = ".",
   no_prompt = FALSE,
   quiet = FALSE,
   quarto_args = NULL
 ) {
   rlang::check_required(template)
 
+  if (!is_empty_dir(dir) && quarto_available("1.5.15")) {
+    cli::cli_abort(c(
+      "{.arg dir} must be an empty directory.",
+      "x" = "The directory {.path {dir}} is not empty.",
+      " " = "Please provide an empty directory or use {.code quarto use template {template} } interactively in terminal."
+    ))
+  }
+
   quarto_bin <- find_quarto()
 
   # This will ask for approval or stop installation
@@ -47,8 +61,10 @@ quarto_use_template <- function(
     if (quarto_version() > "1.5.4" && is_quiet(quiet)) {
       args <- cli_arg_quiet(args)
     }
-
-    quarto_use(args, quarto_bin = quarto_bin, echo = !quiet)
+    xfun::in_dir(
+      dir,
+      quarto_use(args, quarto_bin = quarto_bin, echo = !quiet)
+    )
   }
 
   invisible()

R/utils.R

@@ -65,3 +65,11 @@ has_internet <- function(host = "https://www.google.com") {
     }
   )
 }
+
+is_empty_dir <- function(dir) {
+  if (!dir.exists(dir)) {
+    return(FALSE)
+  }
+  files <- list.files(dir, all.files = TRUE, no.. = TRUE)
+  length(files) == 0
+}

man/quarto_use_template.Rd

@@ -0,0 +1,10 @@
+# Installing an extension in non empty dir errors
+
+    Code
+      quarto_use_template("quarto-journals/jss", no_prompt = TRUE, quiet = TRUE)
+    Condition
+      Error in `quarto_use_template()`:
+      ! `dir` must be an empty directory.
+      x The directory '.' is not empty.
+        Please provide an empty directory or use `quarto use template quarto-journals/jss ` interactively in terminal.
+

tests/testthat/_snaps/use.md

@@ -2,7 +2,7 @@
 skip_if_no_quarto <- function(ver = NULL) {
   skip_if(is.null(quarto_path()), message = "Quarto is not available")
   skip_if(
-    quarto_version() < ver,
+    quarto_available(min = ver, error = FALSE),
     message = sprintf(
       "Version of quarto is lower than %s: %s.",
       ver,

tests/testthat/helper.R

@@ -1,4 +1,4 @@
-test_that("Installing an extension", {
+test_that("Installing an extension in empty dir", {
   skip_if_no_quarto()
   skip_if_offline("github.com")
   dir <- withr::local_tempdir()
@@ -8,3 +8,31 @@ test_that("Installing an extension", {
   expect_true(dir.exists("_extensions/quarto-journals/jss"))
   expect_length(list.files(pattern = "[.]qmd$"), 1)
 })
+
+test_that("Installing an extension in a new empty dir", {
+  skip_if_no_quarto()
+  skip_if_offline("github.com")
+  dir <- withr::local_tempdir()
+  withr::local_dir(dir)
+  quarto_use_template(
+    "quarto-journals/jss",
+    dir = "empty-dir",
+    no_prompt = TRUE,
+    quiet = TRUE
+  )
+  expect_true(dir.exists("empty-dir/_extensions/quarto-journals/jss"))
+  expect_length(list.files(path = "empty-dir", pattern = "[.]qmd$"), 1)
+  expect_equal(list.files(no.. = TRUE, all.files = TRUE), "empty-dir")
+})
+
+test_that("Installing an extension in non empty dir errors", {
+  skip_if_no_quarto("1.5.15")
+  skip_if_offline("github.com")
+  dir <- withr::local_tempdir()
+  withr::local_dir(dir)
+  file.create("README.md")
+  expect_snapshot(
+    error = TRUE,
+    quarto_use_template("quarto-journals/jss", no_prompt = TRUE, quiet = TRUE),
+  )
+})