Rename function and improve docs

NAMESPACE

@@ -4,7 +4,6 @@ S3method(format,orderly_query)
 S3method(print,orderly_cleanup_status)
 S3method(print,orderly_query_explain)
 export(orderly_artefact)
-export(orderly_build_script_details)
 export(orderly_cleanup)
 export(orderly_cleanup_status)
 export(orderly_config)
@@ -31,6 +30,7 @@ export(orderly_metadata_extract)
 export(orderly_metadata_read)
 export(orderly_new)
 export(orderly_parameters)
+export(orderly_parse)
 export(orderly_plugin_add_metadata)
 export(orderly_plugin_context)
 export(orderly_plugin_register)

R/read.R

@@ -1,28 +1,30 @@
 orderly_read <- function(path, call = NULL) {
   entrypoint_filename <- find_entrypoint_filename(path)
-  orderly_read_r(file.path(path, entrypoint_filename), entrypoint_filename)
+  orderly_parse(file.path(path, entrypoint_filename), entrypoint_filename)
 }
 
 
-orderly_read_r <- function(path, entrypoint_filename) {
-  exprs <- parse(file = path)
-  orderly_build_script_details(exprs, entrypoint_filename)
-}
-
-#' Build the details of an orderly source script
+#' Parse the orderly entrypoint script
+#'
+#' For expert use only.
 #'
-#' Takes the parsed AST from an orderly script, parses details
-#' of any calls to orderly_ in-script functions into intermediate
-#' representation for downstream use. Also validates calls to
+#' Takes either a path to the orderly entrypoint script or
+#' the parsed AST from an orderly script, parses details
+#' of any calls to the orderly_ in-script functions into intermediate
+#' representation for downstream use. Also validates that any calls to
 #' orderly_ in-script functions are well-formed.
 #'
-#' @param exprs Parsed AST from orderly script
+#' @param entrypoint_script Path to script or parsed AST from orderly script
 #' @param entrypoint_filename Name of entrypoint file to include in metadata
 #'
-#' @return Details of orderly script
+#' @return Parsed orderly entrypoint script
 #' @export
-#' @keywords internal
-orderly_build_script_details <- function(exprs, entrypoint_filename) {
+orderly_parse <- function(entrypoint_script, entrypoint_filename) {
+  if (!is.expression(entrypoint_script)) {
+    exprs <- parse(file = entrypoint_script)
+  } else {
+    exprs <- entrypoint_script
+  }
 
   inputs <- list()
   artefacts <- list()

tests/testthat/test-read.R

@@ -1,12 +1,12 @@
-test_that("can read file with no helpers", {
-  expect_equal(orderly_read_r("examples/implicit/implicit.R", "implicit.R"),
+test_that("can parse file with no helpers", {
+  expect_equal(orderly_parse("examples/implicit/implicit.R", "implicit.R"),
                list(entrypoint_filename = "implicit.R",
                     strict = list(enabled = FALSE)))
 })
 
 
-test_that("can read file with helpers", {
-  dat <- orderly_read_r("examples/explicit/explicit.R", "explicit.R")
+test_that("can parse file with helpers", {
+  dat <- orderly_parse("examples/explicit/explicit.R", "explicit.R")
   expect_setequal(names(dat),
                   c("entrypoint_filename", "strict", "resources", "artefacts"))
   expect_equal(dat$strict, list(enabled = FALSE))
@@ -17,8 +17,15 @@ test_that("can read file with helpers", {
 })
 
 
+test_that("can parse file from expression", {
+  exprs <- parse(file = "examples/explicit/explicit.R")
+  dat <- orderly_parse(exprs, "explicit.R")
+  expect_equal(dat, orderly_parse("examples/explicit/explicit.R", "explicit.R"))
+})
+
+
 test_that("Skip over computed resources", {
-  dat <- orderly_read_r("examples/computed-resource/computed-resource.R",
+  dat <- orderly_parse("examples/computed-resource/computed-resource.R",
                         "computed-resource.R")
   expect_null(dat$resources)
 })