add shortcut for parse_file_matches and update doc

R/utils-paths-source.R

@@ -134,7 +134,8 @@ get_resource_list <- function(path, trim = FALSE, subfolder = NULL, warn = FALSE
   # These are the only four items that we need to consider order for.
   for (i in subfolder) {
     # If the configuration is not missing, then we have to rearrange the order.
-    res[[i]] <- parse_file_matches(res[[i]], cfg[[i]], warn = warn, i)
+    res[[i]] <- parse_file_matches(reality = res[[i]], hopes = cfg[[i]],
+      warn = warn, subfolder = i)
   }
   if (use_subfolder) res[[subfolder]] else res[names(res) != "site"]
 }
@@ -153,8 +154,46 @@ get_source_artifacts <- function(path, subfolder = "episodes") {
   )
 }
 
+#' Subset file matches to the order they appear in the config file
+#'
+#' @param reality a list of paths that exist in the lesson
+#' @param hopes a list of files in the order they should appear in the lesson
+#' @param warn a boolean. If `TRUE` and the `sandpaper.show_draft` option is
+#'   set to TRUE, then the files that are not in `hopes` are shown to the
+#'   screen as drafts
+#' @param subfolder a character. The folder where we should find the files in
+#'   `hopes`. This is only used for creating an error message.
+#' @return a character vector of `reality` subset in the order of `hopes`
+#' @keywords internal
+#' @examples
+#' # setup ----------------------------------------------------
+#' #
+#' # NOTE: we need to define our namespace here because using `:::`
+#' # in example calls is illegal.
+#' snd <- asNamespace("sandpaper")
+#' print(need <- c("a", "bunch", "of", "silly", "files"))
+#' print(exists <- fs::path("path", "to", sample(need)))
+#'
+#' # Rearrange files ------------------------------------------
+#' snd$parse_file_matches(reality = exists, hopes = need,
+#'   subfolder = "episodes")
+#'
+#' # a subset of files ----------------------------------------
+#' snd$parse_file_matches(reality = exists,
+#'   hopes = need[4:5], subfolder = "episodes")
+#'
+#' # a subset of files with a warning -------------------------
+#' op <- getOption("sandpaper.show_draft")
+#' options(sandpaper.show_draft = TRUE)
+#' on.exit(options(sandpaper.show_draft = op))
+#' snd$parse_file_matches(reality = exists,
+#'   hopes = need[-(4:5)], warn = TRUE, subfolder = "episodes")
+#'
+#' # files that do not exist give an error --------------------
+#' try(snd$parse_file_matches(reality = exists,
+#'   hopes = c("these", need[4:5]), subfolder = "episodes"))
 parse_file_matches <- function(reality, hopes = NULL, warn = FALSE, subfolder) {
-  if (is.null(hopes)) {
+  if (is.null(hopes) || is.null(reality)) {
     return(reality)
   }
   real_files <- fs::path_file(reality)

_pkgdown.yml

@@ -117,6 +117,7 @@ reference:
    - get_built_db
    - get_hash
    - get_resource_list
+   - parse_file_matches
    - template_episode
    - yaml_list
  - title: "[Developer] Lesson Test Fixture"

tests/testthat/test-overview.R

@@ -12,6 +12,10 @@ test_that("We can switch between overview and regular lesson metadata", {
   fs::dir_copy(lsn, tmp)
   this_metadata$clear()
   clear_this_lesson()
+  withr::defer({
+    this_metadata$clear()
+    clear_this_lesson()
+  })
 
   # check lesson defaults and norms ---------------------------
   lcfg <- get_config(lsn)