rename to qmd_to_r_script and mark as experimental

Author: cderv

NAMESPACE

@@ -2,9 +2,9 @@
 
 export(add_spin_preamble)
 export(check_newer_version)
-export(extract_r_code)
 export(is_using_quarto)
 export(new_blog_post)
+export(qmd_to_r_script)
 export(quarto_add_extension)
 export(quarto_available)
 export(quarto_binary_sitrep)

R/utils-extract.R

@@ -1,10 +1,16 @@
-#' Extract R code from Quarto document
+#' Convert Quarto document to R script
+#'
+#' @description
+#' `r lifecycle::badge("experimental")`
 #'
 #' Extracts R code cells from a Quarto document and writes them to an R script
 #' file that can be rendered with the same options. The Markdown text is not
 #' preserved, but R chunk options are kept as comment headers using Quarto's
 #' `#|` syntax.
 #'
+#' This function is still experimental and may slightly change in
+#' future releases, depending on feedback.
+#'
 #' @param qmd Character. Path to the input Quarto document (.qmd file).
 #' @param script Character. Path to the output R script file. If `NULL`
 #'   (default), the script file will have the same name as the input file
@@ -36,16 +42,16 @@
 #'
 #' @examples
 #' \dontrun{
-#' # Extract R code from a Quarto document
-#' extract_r_code("my-document.qmd")
+#' # Convert a Quarto document to R script
+#' qmd_to_r_script("my-document.qmd")
 #' # Creates "my-document.R"
 #'
 #' # Specify custom output file
-#' extract_r_code("my-document.qmd", script = "extracted-code.R")
+#' qmd_to_r_script("my-document.qmd", script = "extracted-code.R")
 #' }
 #'
 #' @export
-extract_r_code <- function(qmd, script = NULL) {
+qmd_to_r_script <- function(qmd, script = NULL) {
   if (!file.exists(qmd)) {
     cli::cli_abort(
       c(

man/extract_r_code.Rd renamed to man/qmd_to_r_script.Rd

@@ -1,25 +1,25 @@
-# extract_r_code() errors on wrong qmd
+# qmd_to_r_script() errors on wrong qmd
 
     Code
-      extract_r_code("nonexistent.qmd")
+      qmd_to_r_script("nonexistent.qmd")
     Condition
       Error:
       ! File 'nonexistent.qmd' does not exist.
       > Please provide a valid Quarto document.
 
-# extract_r_code() errors on existing script
+# qmd_to_r_script() errors on existing script
 
     Code
-      extract_r_code(resources_path("purl-r.qmd"), script = r_script)
+      qmd_to_r_script(resources_path("purl-r.qmd"), script = r_script)
     Condition
-      Error in `extract_r_code()`:
+      Error in `qmd_to_r_script()`:
       ! File <r script> already exists.
       > Please provide a new file name or remove the existing file.
 
-# extract_r_code() ignore other language code
+# qmd_to_r_script() ignore other language code
 
     Code
-      extract_r_code(resources_path("purl-r-ojs.qmd"), r_script)
+      qmd_to_r_script(resources_path("purl-r-ojs.qmd"), r_script)
     Message
       Extracting only R code cells from 'resources/purl-r-ojs.qmd'.
       > Other languages will be ignored (found ojs).

tests/testthat/_snaps/utils-extract.md

@@ -1,30 +1,30 @@
-test_that("extract_r_code() errors on wrong qmd", {
+test_that("qmd_to_r_script() errors on wrong qmd", {
   expect_snapshot(
     error = TRUE,
-    extract_r_code("nonexistent.qmd")
+    qmd_to_r_script("nonexistent.qmd")
   )
 })
 
-test_that("extract_r_code() errors on existing script", {
+test_that("qmd_to_r_script() errors on existing script", {
   r_script <- withr::local_tempfile(pattern = "purl", fileext = ".R")
   file.create(r_script)
   expect_snapshot(
     error = TRUE,
-    extract_r_code(resources_path("purl-r.qmd"), script = r_script),
+    qmd_to_r_script(resources_path("purl-r.qmd"), script = r_script),
     transform = function(x) {
       gsub("(! File ).*( already exists.)", "\\1<r script>\\2", x)
     }
   )
 })
 
-test_that("extract_r_code() writes R file that renders", {
+test_that("qmd_to_r_script() writes R file that renders", {
   skip_if_no_quarto()
   r_script <- withr::local_tempfile(pattern = "purl", fileext = ".R")
 
   announce_snapshot_file(name = "purl.R")
 
   expect_snapshot_file(
-    path = extract_r_code(
+    path = qmd_to_r_script(
       resources_path("purl-r.qmd"),
       script = r_script
     ),
@@ -46,29 +46,29 @@ test_that("extract_r_code() writes R file that renders", {
   )
 })
 
-test_that("extract_r_code() do nothing on file with no code", {
+test_that("qmd_to_r_script() do nothing on file with no code", {
   skip_if_no_quarto()
   expect_message(
-    expect_null(extract_r_code(resources_path("purl-no-cell.qmd"))),
+    expect_null(qmd_to_r_script(resources_path("purl-no-cell.qmd"))),
     "No code cells found"
   )
   expect_false(file.exists(resources_path("purl.R")))
 })
 
-test_that("extract_r_code() do nothing on file with only other language code", {
+test_that("qmd_to_r_script() do nothing on file with only other language code", {
   skip_if_no_quarto()
   expect_message(
-    expect_null(extract_r_code(resources_path("purl-py.qmd"))),
+    expect_null(qmd_to_r_script(resources_path("purl-py.qmd"))),
     "No R code cells found.*: python"
   )
   expect_false(file.exists(resources_path("purl.R")))
 })
 
-test_that("extract_r_code() ignore other language code", {
+test_that("qmd_to_r_script() ignore other language code", {
   skip_if_no_quarto()
   r_script <- withr::local_tempfile(pattern = "purl", fileext = ".R")
   expect_snapshot(
-    extract_r_code(resources_path("purl-r-ojs.qmd"), r_script),
+    qmd_to_r_script(resources_path("purl-r-ojs.qmd"), r_script),
   )
   expect_true(file.exists(r_script))
 })