build_status: Identify what files need to be rebuilt and what need to be...

In zkamvar/sandpaper: Create and Curate Carpentries Lessons

Identify what files need to be rebuilt and what need to be removed

Description

build_status() takes in a vector of files and compares them against a text database of files with checksums. It's been heavily adapted from blogdown to provide utilities for removal and updating of the old database.

Usage

get_hash(path, db = fs::path(path_built(path), "md5sum.txt"))

get_built_db(db = "site/built/md5sum.txt", filter = "*R?md")

build_status(
  sources,
  db = "site/built/md5sum.txt",
  rebuild = FALSE,
  write = FALSE
)

Arguments

path	path to at least one generated markdown file
db	the path to the database
filter	regex describing files to include.
sources	a character vector of ALL source files OR a single file to be rebuilt. These must be absolute paths
rebuild	if the files should be rebuilt, set this to TRUE (defaults to FALSE)
write	if TRUE, the database will be updated, Defaults to FALSE, meaning that the database will remain the same.

Details

get_built_db() returns the text database, which you can filter on

get_hash() should probably be named get_expected_hash() because it will return the expected hash of a given file from the database

If you supply a single file into this function, we assume that you want that one file to be rebuilt, so we will always return that file in the ⁠$build⁠ element and update the md5 sum in the database (if it has changed at all).

If you supply multiple files, you are indicating that these are the only files you care about and the database will be updated accordingly, removing entries missing from the sources.

Value

a list of the following elements

• build absolute paths of files to build

• new a new data frame with three columns:

  • file the relative path to the source file

  • checksum the md5 sum of the source file

  • built the relative path to the built file

  • date the date a file was last updated/built

• remove absolute paths of files to remove. This will be missing if there is nothing to remove

• old old database (for debugging). This will be missing if there is no old database or if a single file was rebuilt.

See Also

get_resource_list(), reserved_db(), hash_children()

Examples

# This demonstration will show how a temporary database can be set up. It
# will only work with a sandpaper lesson
# setup -----------------------------------------------------------------
tmp <- tempfile()
on.exit(fs::dir_delete(tmp), add = TRUE)
create_lesson(tmp, rmd = FALSE, open = FALSE)

# show build status -----------------------------------------------------
# get namespace to use internal functions
sp <- asNamespace("sandpaper")
db <- fs::path(tmp, "site/built/md5sum.txt")
resources <- fs::path(tmp, c("episodes/introduction.md", "index.md"))
# first run, everything needs to be built and no build file exists
sp$build_status(resources, db, write = TRUE)
# second run, everything is identical and nothing to be rebuilt
sp$build_status(resources, db, write = TRUE)
# this is because the db exists on disk and you can query it
sp$get_built_db(db, filter = "*")
sp$get_built_db(db, filter = "*R?md")
# if you get the hash of the file, it's equal to the expected:
print(actual <- tools::md5sum(resources[[1]]))
print(expected <- sp$get_hash(resources[[1]], db))
unname(actual == expected)

# replaced files need to be rebuilt -------------------------------------
# if we change the introduction to an R Markdown file, the build will
# see this as a deleted file and re-added file.
cat("This is now an R Markdown document and the time is `r Sys.time()`\n",
  file = resources[[1]], append = TRUE)
fs::file_move(resources[[1]], fs::path_ext_set(resources[[1]], "Rmd"))
resources[[1]] <- fs::path_ext_set(resources[[1]], "Rmd")
set_episodes(tmp, fs::path_file(resources[[1]]), write = TRUE)
sp$build_status(resources, db, write = TRUE)

# modified files need to be rebuilt -------------------------------------
cat("We are using `r R.version.string`\n",
  file = resources[[1]], append = TRUE)
sp$build_status(resources, db, write = TRUE)

# child files require rebuilding ----------------------------------------
writeLines("Hello from another file!\n",
  fs::path(tmp, "episodes", "files", "hi.md"))
cat("\n\n```{r child='files/hi.md'}\n```\n",
  file = resources[[1]], append = TRUE)
sp$build_status(resources, db, write = TRUE)
# NOTE: for child files, the checksums are the checksum of the checksums
# of the parent and children, so the file checksum may not make sense

# changing a child file rebuilds the parent ----------------------------
cat("Goodbye!\n", append = TRUE,
  file = fs::path(tmp, "episodes", "files", "hi.md"))
sp$build_status(resources, db, write = TRUE)

zkamvar/sandpaper documentation built on April 21, 2024, 1:17 a.m.