From 1a648029168f98a795112869f7620f85673ffa8f Mon Sep 17 00:00:00 2001
From: Rob Ashton <r.ashton@imperial.ac.uk>
Date: Thu, 29 Feb 2024 15:47:31 +0000
Subject: [PATCH 1/8] Add function to parse orderly script details from AST

---
 DESCRIPTION                         |  4 ++--
 NAMESPACE                           |  1 +
 R/read.R                            | 16 ++++++++++++++++
 man/orderly_build_script_details.Rd | 22 ++++++++++++++++++++++
 4 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 man/orderly_build_script_details.Rd

diff --git a/DESCRIPTION b/DESCRIPTION
index f31a2101..131cf5a9 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: orderly2
 Title: Orderly Next Generation
-Version: 1.99.12
+Version: 1.99.13
 Authors@R: c(person("Rich", "FitzJohn", role = c("aut", "cre"),
                     email = "rich.fitzjohn@gmail.com"),
              person("Robert", "Ashton", role = "aut"),
@@ -11,7 +11,7 @@ Description: Reimplementation of orderly based on outpack.
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1
 URL: https://github.com/mrc-ide/orderly2
 BugReports: https://github.com/mrc-ide/orderly2/issues
 Imports:
diff --git a/NAMESPACE b/NAMESPACE
index 1b22cabf..a2c36248 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -4,6 +4,7 @@ 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)
diff --git a/R/read.R b/R/read.R
index 3faa6edf..d54c7a3d 100644
--- a/R/read.R
+++ b/R/read.R
@@ -6,6 +6,22 @@ orderly_read <- function(path, call = NULL) {
 
 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
+#'
+#' 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
+#' orderly_ in-script functions are well-formed.
+#'
+#' @param exprs Parsed AST from orderly script
+#' @param entrypoint_filename Name of entrypoint file to include in metadata
+#'
+#' @return Details of orderly script
+#' @export
+orderly_build_script_details <- function(exprs, entrypoint_filename) {
 
   inputs <- list()
   artefacts <- list()
diff --git a/man/orderly_build_script_details.Rd b/man/orderly_build_script_details.Rd
new file mode 100644
index 00000000..0653375f
--- /dev/null
+++ b/man/orderly_build_script_details.Rd
@@ -0,0 +1,22 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/read.R
+\name{orderly_build_script_details}
+\alias{orderly_build_script_details}
+\title{Build the details of an orderly source script}
+\usage{
+orderly_build_script_details(exprs, entrypoint_filename)
+}
+\arguments{
+\item{exprs}{Parsed AST from orderly script}
+
+\item{entrypoint_filename}{Name of entrypoint file to include in metadata}
+}
+\value{
+Details of orderly script
+}
+\description{
+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
+orderly_ in-script functions are well-formed.
+}

From 3569e877a3ae1e90abe3c35db727c486106dc236 Mon Sep 17 00:00:00 2001
From: Rob Ashton <r.ashton@imperial.ac.uk>
Date: Thu, 29 Feb 2024 16:38:46 +0000
Subject: [PATCH 2/8] Make build_script_details internal function to exclude
 from pkgdown site

---
 R/read.R                            | 1 +
 man/orderly_build_script_details.Rd | 1 +
 2 files changed, 2 insertions(+)

diff --git a/R/read.R b/R/read.R
index d54c7a3d..25cc9885 100644
--- a/R/read.R
+++ b/R/read.R
@@ -21,6 +21,7 @@ orderly_read_r <- function(path, entrypoint_filename) {
 #'
 #' @return Details of orderly script
 #' @export
+#' @keywords internal
 orderly_build_script_details <- function(exprs, entrypoint_filename) {
 
   inputs <- list()
diff --git a/man/orderly_build_script_details.Rd b/man/orderly_build_script_details.Rd
index 0653375f..05adf481 100644
--- a/man/orderly_build_script_details.Rd
+++ b/man/orderly_build_script_details.Rd
@@ -20,3 +20,4 @@ of any calls to orderly_ in-script functions into intermediate
 representation for downstream use. Also validates calls to
 orderly_ in-script functions are well-formed.
 }
+\keyword{internal}

From a2c43de505427e7a8cfc867078e5fe3ba1fd010a Mon Sep 17 00:00:00 2001
From: Rob Ashton <r.ashton@imperial.ac.uk>
Date: Fri, 1 Mar 2024 17:39:18 +0000
Subject: [PATCH 3/8] Rename function and improve docs

---
 NAMESPACE                           |  2 +-
 R/read.R                            | 30 +++++++++++++++--------------
 man/orderly_build_script_details.Rd | 23 ----------------------
 man/orderly_parse.Rd                | 26 +++++++++++++++++++++++++
 tests/testthat/test-read.R          | 17 +++++++++++-----
 5 files changed, 55 insertions(+), 43 deletions(-)
 delete mode 100644 man/orderly_build_script_details.Rd
 create mode 100644 man/orderly_parse.Rd

diff --git a/NAMESPACE b/NAMESPACE
index a2c36248..39681ffe 100644
--- a/NAMESPACE
+++ b/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)
diff --git a/R/read.R b/R/read.R
index 25cc9885..7465ffe2 100644
--- a/R/read.R
+++ b/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()
diff --git a/man/orderly_build_script_details.Rd b/man/orderly_build_script_details.Rd
deleted file mode 100644
index 05adf481..00000000
--- a/man/orderly_build_script_details.Rd
+++ /dev/null
@@ -1,23 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/read.R
-\name{orderly_build_script_details}
-\alias{orderly_build_script_details}
-\title{Build the details of an orderly source script}
-\usage{
-orderly_build_script_details(exprs, entrypoint_filename)
-}
-\arguments{
-\item{exprs}{Parsed AST from orderly script}
-
-\item{entrypoint_filename}{Name of entrypoint file to include in metadata}
-}
-\value{
-Details of orderly script
-}
-\description{
-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
-orderly_ in-script functions are well-formed.
-}
-\keyword{internal}
diff --git a/man/orderly_parse.Rd b/man/orderly_parse.Rd
new file mode 100644
index 00000000..00d8bee4
--- /dev/null
+++ b/man/orderly_parse.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/read.R
+\name{orderly_parse}
+\alias{orderly_parse}
+\title{Parse the orderly entrypoint script}
+\usage{
+orderly_parse(entrypoint_script, entrypoint_filename)
+}
+\arguments{
+\item{entrypoint_script}{Path to script or parsed AST from orderly script}
+
+\item{entrypoint_filename}{Name of entrypoint file to include in metadata}
+}
+\value{
+Parsed orderly entrypoint script
+}
+\description{
+For expert use only.
+}
+\details{
+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.
+}
diff --git a/tests/testthat/test-read.R b/tests/testthat/test-read.R
index 77f9c480..542b6c53 100644
--- a/tests/testthat/test-read.R
+++ b/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)
 })

From 0665401d4b5cb1377ba7179ed3ddcfcbef2de93b Mon Sep 17 00:00:00 2001
From: Rob Ashton <r.ashton@imperial.ac.uk>
Date: Mon, 4 Mar 2024 09:27:12 +0000
Subject: [PATCH 4/8] Add orderly_parse into pkgdown index

---
 _pkgdown.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/_pkgdown.yml b/_pkgdown.yml
index 4a9ead98..ba92bebc 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -86,3 +86,4 @@ reference:
       - orderly_validate_archive
       - orderly_hash_data
       - orderly_hash_file
+      - orderly_parse

From ee5d7e6e0abb77f2b49a4ecd964b061ef99c41d8 Mon Sep 17 00:00:00 2001
From: Rob Ashton <r.ashton@imperial.ac.uk>
Date: Mon, 4 Mar 2024 09:57:38 +0000
Subject: [PATCH 5/8] Tidy up orderly_parse interface, add some validation

---
 R/read.R                   | 40 ++++++++++++++++++++++++++++----------
 man/orderly_parse.Rd       | 11 +++++++----
 tests/testthat/test-read.R | 27 +++++++++++++++++++------
 3 files changed, 58 insertions(+), 20 deletions(-)

diff --git a/R/read.R b/R/read.R
index 7465ffe2..3a24c5f9 100644
--- a/R/read.R
+++ b/R/read.R
@@ -1,6 +1,6 @@
 orderly_read <- function(path, call = NULL) {
   entrypoint_filename <- find_entrypoint_filename(path)
-  orderly_parse(file.path(path, entrypoint_filename), entrypoint_filename)
+  orderly_parse(file.path(path, entrypoint_filename))
 }
 
 
@@ -12,18 +12,38 @@ orderly_read <- function(path, call = NULL) {
 #' 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.
+#' `orderly_*` in-script functions are well-formed.
 #'
-#' @param entrypoint_script Path to script or parsed AST from orderly script
-#' @param entrypoint_filename Name of entrypoint file to include in metadata
+#' @param path Path to `orderly_*` script
+#' @param exprs Parsed AST from `orderly_*` script
+#' @param filename Name of `orderly_*` file to include in metadata, required if
+#'   calling with `exprs`. If called with a `path` this can be NULL.
 #'
 #' @return Parsed orderly entrypoint script
 #' @export
-orderly_parse <- function(entrypoint_script, entrypoint_filename) {
-  if (!is.expression(entrypoint_script)) {
-    exprs <- parse(file = entrypoint_script)
+orderly_parse <- function(path, exprs = NULL, filename = NULL) {
+  path_missing <- missing(path)
+  exprs_missing <- missing(exprs)
+  if ((path_missing && exprs_missing) ||
+      (!path_missing && !exprs_missing)) {
+    cli::cli_abort(c("One and only one of 'path' and 'exprs' must be set.",
+                   i = "See {.fun orderly2::orderly_parse} for details."))
+  }
+  if (is.null(filename)) {
+    if (!path_missing) {
+      filename <- basename(path)
+    } else {
+      cli::cli_abort(c(paste(
+        "`filename` must be set if calling",
+        "{.fun orderly2::orderly_parse} with `exprs`"),
+        i = "See {.fun orderly2::orderly_parse} for details."))
+    }
+  }
+  if (!path_missing) {
+    assert_file_exists(path)
+    exprs <- parse(file = path)
   } else {
-    exprs <- entrypoint_script
+    assert_is(exprs, "expression")
   }
 
   inputs <- list()
@@ -69,7 +89,7 @@ orderly_parse <- function(entrypoint_script, entrypoint_filename) {
   ## Rename to make things easier below:
   names(dat) <- sub("^orderly_", "", names(dat))
 
-  ret <- list(entrypoint_filename = entrypoint_filename)
+  ret <- list(entrypoint_filename = filename)
   if (length(dat$strict_mode) > 0) {
     ret$strict <- dat$strict_mode[[1]]
   } else {
@@ -95,7 +115,7 @@ orderly_parse <- function(entrypoint_script, entrypoint_filename) {
 
   if (length(dat$resource) > 0) {
     ret$resources <- setdiff(unique(unlist(dat$resource, TRUE, FALSE)),
-                             entrypoint_filename)
+                             filename)
   }
   if (length(dat$artefact) > 0) {
     ret$artefacts <- dat$artefact
diff --git a/man/orderly_parse.Rd b/man/orderly_parse.Rd
index 00d8bee4..0aa99251 100644
--- a/man/orderly_parse.Rd
+++ b/man/orderly_parse.Rd
@@ -4,12 +4,15 @@
 \alias{orderly_parse}
 \title{Parse the orderly entrypoint script}
 \usage{
-orderly_parse(entrypoint_script, entrypoint_filename)
+orderly_parse(path, exprs = NULL, filename = NULL)
 }
 \arguments{
-\item{entrypoint_script}{Path to script or parsed AST from orderly script}
+\item{path}{Path to \verb{orderly_*} script}
 
-\item{entrypoint_filename}{Name of entrypoint file to include in metadata}
+\item{exprs}{Parsed AST from \verb{orderly_*} script}
+
+\item{filename}{Name of \verb{orderly_*} file to include in metadata, required if
+calling with \code{exprs}. If called with a \code{path} this can be NULL.}
 }
 \value{
 Parsed orderly entrypoint script
@@ -22,5 +25,5 @@ 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.
+\verb{orderly_*} in-script functions are well-formed.
 }
diff --git a/tests/testthat/test-read.R b/tests/testthat/test-read.R
index 542b6c53..c31e8c57 100644
--- a/tests/testthat/test-read.R
+++ b/tests/testthat/test-read.R
@@ -1,12 +1,12 @@
 test_that("can parse file with no helpers", {
-  expect_equal(orderly_parse("examples/implicit/implicit.R", "implicit.R"),
+  expect_equal(orderly_parse("examples/implicit/implicit.R"),
                list(entrypoint_filename = "implicit.R",
                     strict = list(enabled = FALSE)))
 })
 
 
 test_that("can parse file with helpers", {
-  dat <- orderly_parse("examples/explicit/explicit.R", "explicit.R")
+  dat <- orderly_parse("examples/explicit/explicit.R")
   expect_setequal(names(dat),
                   c("entrypoint_filename", "strict", "resources", "artefacts"))
   expect_equal(dat$strict, list(enabled = FALSE))
@@ -19,14 +19,29 @@ test_that("can parse 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"))
+  dat <- orderly_parse(exprs = exprs, filename = "explicit.R")
+  expect_equal(dat, orderly_parse("examples/explicit/explicit.R"))
+})
+
+
+
+test_that("useful error raised if trying to parse from path and exprs", {
+  expect_error(orderly_parse(path = "p", exprs = "e"),
+               "One and only one of 'path' and 'exprs' must be set.")
+  expect_error(orderly_parse(),
+               "One and only one of 'path' and 'exprs' must be set.")
+})
+
+
+test_that("useful error raised if trying to parse with exprs and no filename", {
+  exprs <- parse(file = "examples/explicit/explicit.R")
+  expect_error(orderly_parse(exprs = exprs),
+               "`filename` must be set if calling")
 })
 
 
 test_that("Skip over computed resources", {
-  dat <- orderly_parse("examples/computed-resource/computed-resource.R",
-                        "computed-resource.R")
+  dat <- orderly_parse("examples/computed-resource/computed-resource.R")
   expect_null(dat$resources)
 })
 

From ded36b38546dc6fc886c956f97cb2dd1451ed33f Mon Sep 17 00:00:00 2001
From: Robert Ashton <r.ashton@imperial.ac.uk>
Date: Tue, 5 Mar 2024 17:22:41 +0000
Subject: [PATCH 6/8] Split orderly parse into 2 functions to improve interface

---
 NAMESPACE                                     |  3 +-
 R/read.R                                      | 48 +++++++------------
 _pkgdown.yml                                  |  3 +-
 ...orderly_parse.Rd => orderly_parse_file.Rd} | 17 +++----
 tests/testthat/test-read.R                    | 26 ++--------
 5 files changed, 35 insertions(+), 62 deletions(-)
 rename man/{orderly_parse.Rd => orderly_parse_file.Rd} (56%)

diff --git a/NAMESPACE b/NAMESPACE
index 39681ffe..4c96b240 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -30,7 +30,8 @@ export(orderly_metadata_extract)
 export(orderly_metadata_read)
 export(orderly_new)
 export(orderly_parameters)
-export(orderly_parse)
+export(orderly_parse_expr)
+export(orderly_parse_file)
 export(orderly_plugin_add_metadata)
 export(orderly_plugin_context)
 export(orderly_plugin_register)
diff --git a/R/read.R b/R/read.R
index 3a24c5f9..09c3bca7 100644
--- a/R/read.R
+++ b/R/read.R
@@ -1,6 +1,6 @@
 orderly_read <- function(path, call = NULL) {
   entrypoint_filename <- find_entrypoint_filename(path)
-  orderly_parse(file.path(path, entrypoint_filename))
+  orderly_parse_file(file.path(path, entrypoint_filename))
 }
 
 
@@ -8,43 +8,29 @@ orderly_read <- function(path, call = NULL) {
 #'
 #' For expert use only.
 #'
-#' 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.
+#' 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 path Path to `orderly_*` script
+#'
+#' @return Parsed orderly entrypoint script
+#' @export
+orderly_parse_file <- function(path) {
+  assert_file_exists(path)
+  exprs <- parse(file = path)
+  orderly_parse_expr(exprs, basename(path))
+}
+
+
 #' @param exprs Parsed AST from `orderly_*` script
 #' @param filename Name of `orderly_*` file to include in metadata, required if
 #'   calling with `exprs`. If called with a `path` this can be NULL.
 #'
-#' @return Parsed orderly entrypoint script
+#' @rdname orderly_parse_file
 #' @export
-orderly_parse <- function(path, exprs = NULL, filename = NULL) {
-  path_missing <- missing(path)
-  exprs_missing <- missing(exprs)
-  if ((path_missing && exprs_missing) ||
-      (!path_missing && !exprs_missing)) {
-    cli::cli_abort(c("One and only one of 'path' and 'exprs' must be set.",
-                   i = "See {.fun orderly2::orderly_parse} for details."))
-  }
-  if (is.null(filename)) {
-    if (!path_missing) {
-      filename <- basename(path)
-    } else {
-      cli::cli_abort(c(paste(
-        "`filename` must be set if calling",
-        "{.fun orderly2::orderly_parse} with `exprs`"),
-        i = "See {.fun orderly2::orderly_parse} for details."))
-    }
-  }
-  if (!path_missing) {
-    assert_file_exists(path)
-    exprs <- parse(file = path)
-  } else {
-    assert_is(exprs, "expression")
-  }
+orderly_parse_expr <- function(exprs, filename) {
+  assert_is(exprs, "expression")
 
   inputs <- list()
   artefacts <- list()
diff --git a/_pkgdown.yml b/_pkgdown.yml
index ba92bebc..72bbe997 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -86,4 +86,5 @@ reference:
       - orderly_validate_archive
       - orderly_hash_data
       - orderly_hash_file
-      - orderly_parse
+      - orderly_parse_file
+      - orderly_parse_expr
diff --git a/man/orderly_parse.Rd b/man/orderly_parse_file.Rd
similarity index 56%
rename from man/orderly_parse.Rd
rename to man/orderly_parse_file.Rd
index 0aa99251..16a73d21 100644
--- a/man/orderly_parse.Rd
+++ b/man/orderly_parse_file.Rd
@@ -1,10 +1,13 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/read.R
-\name{orderly_parse}
-\alias{orderly_parse}
+\name{orderly_parse_file}
+\alias{orderly_parse_file}
+\alias{orderly_parse_expr}
 \title{Parse the orderly entrypoint script}
 \usage{
-orderly_parse(path, exprs = NULL, filename = NULL)
+orderly_parse_file(path)
+
+orderly_parse_expr(exprs, filename)
 }
 \arguments{
 \item{path}{Path to \verb{orderly_*} script}
@@ -21,9 +24,7 @@ Parsed orderly entrypoint script
 For expert use only.
 }
 \details{
-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
-\verb{orderly_*} in-script functions are well-formed.
+Parses details of any calls to the orderly_ in-script functions
+into intermediate representation for downstream use. Also validates
+that any calls to \verb{orderly_*} in-script functions are well-formed.
 }
diff --git a/tests/testthat/test-read.R b/tests/testthat/test-read.R
index c31e8c57..8f0ec350 100644
--- a/tests/testthat/test-read.R
+++ b/tests/testthat/test-read.R
@@ -1,12 +1,12 @@
 test_that("can parse file with no helpers", {
-  expect_equal(orderly_parse("examples/implicit/implicit.R"),
+  expect_equal(orderly_parse_file("examples/implicit/implicit.R"),
                list(entrypoint_filename = "implicit.R",
                     strict = list(enabled = FALSE)))
 })
 
 
 test_that("can parse file with helpers", {
-  dat <- orderly_parse("examples/explicit/explicit.R")
+  dat <- orderly_parse_file("examples/explicit/explicit.R")
   expect_setequal(names(dat),
                   c("entrypoint_filename", "strict", "resources", "artefacts"))
   expect_equal(dat$strict, list(enabled = FALSE))
@@ -19,29 +19,13 @@ test_that("can parse file with helpers", {
 
 test_that("can parse file from expression", {
   exprs <- parse(file = "examples/explicit/explicit.R")
-  dat <- orderly_parse(exprs = exprs, filename = "explicit.R")
-  expect_equal(dat, orderly_parse("examples/explicit/explicit.R"))
-})
-
-
-
-test_that("useful error raised if trying to parse from path and exprs", {
-  expect_error(orderly_parse(path = "p", exprs = "e"),
-               "One and only one of 'path' and 'exprs' must be set.")
-  expect_error(orderly_parse(),
-               "One and only one of 'path' and 'exprs' must be set.")
-})
-
-
-test_that("useful error raised if trying to parse with exprs and no filename", {
-  exprs <- parse(file = "examples/explicit/explicit.R")
-  expect_error(orderly_parse(exprs = exprs),
-               "`filename` must be set if calling")
+  dat <- orderly_parse_expr(exprs = exprs, filename = "explicit.R")
+  expect_equal(dat, orderly_parse_file("examples/explicit/explicit.R"))
 })
 
 
 test_that("Skip over computed resources", {
-  dat <- orderly_parse("examples/computed-resource/computed-resource.R")
+  dat <- orderly_parse_file("examples/computed-resource/computed-resource.R")
   expect_null(dat$resources)
 })
 

From 321b63e19be30a0d9f815a91b6582fcda3425bb4 Mon Sep 17 00:00:00 2001
From: Rob <39248272+r-ash@users.noreply.github.com>
Date: Tue, 5 Mar 2024 17:38:30 +0000
Subject: [PATCH 7/8] Update R/read.R

Co-authored-by: M-Kusumgar <98405247+M-Kusumgar@users.noreply.github.com>
---
 R/read.R | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/R/read.R b/R/read.R
index 09c3bca7..e16da060 100644
--- a/R/read.R
+++ b/R/read.R
@@ -24,8 +24,7 @@ orderly_parse_file <- function(path) {
 
 
 #' @param exprs Parsed AST from `orderly_*` script
-#' @param filename Name of `orderly_*` file to include in metadata, required if
-#'   calling with `exprs`. If called with a `path` this can be NULL.
+#' @param filename Name of `orderly_*` file to include in metadata
 #'
 #' @rdname orderly_parse_file
 #' @export

From e4354415ebfb7908100315bf685edc61b14146e5 Mon Sep 17 00:00:00 2001
From: Robert Ashton <r.ashton@imperial.ac.uk>
Date: Tue, 5 Mar 2024 17:38:58 +0000
Subject: [PATCH 8/8] Regen docs

---
 man/orderly_parse_file.Rd | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/man/orderly_parse_file.Rd b/man/orderly_parse_file.Rd
index 16a73d21..e15f05cb 100644
--- a/man/orderly_parse_file.Rd
+++ b/man/orderly_parse_file.Rd
@@ -14,8 +14,7 @@ orderly_parse_expr(exprs, filename)
 
 \item{exprs}{Parsed AST from \verb{orderly_*} script}
 
-\item{filename}{Name of \verb{orderly_*} file to include in metadata, required if
-calling with \code{exprs}. If called with a \code{path} this can be NULL.}
+\item{filename}{Name of \verb{orderly_*} file to include in metadata}
 }
 \value{
 Parsed orderly entrypoint script