Public helper to fetch an artifact into the user cache. This function delegates to the internal downloader used by the package at runtime, so it benefits from the same behavior:
Arguments
- file
Character scalar; relative filename to use in the cache (e.g., `"rb_mod1a.rda"`).
- url
Character scalar; source URL. May be a `file://` URL for local testing.
- sha256
Optional 64-hex SHA-256 checksum for verification. If provided, the cached file must match it (or a re-download is attempted). NULL, NA, and an empty string mean no checksum. Local mock artifacts bypass checksums.
- quiet
Logical; if `TRUE`, suppresses download progress messages.
Value
A character scalar: the absolute path to the cached file, or the local
artifact path when writeAlizer.mock_dir is set.
Details
- Respects options(writeAlizer.mock_dir) to load local mock copies
(useful for tests/examples and offline runs).
- Fails gracefully with a clear, informative message when Internet
resources are unavailable or have changed (per CRAN policy).
- Verifies an optional SHA-256 checksum and re-downloads or errors if it
does not match.
Local file URLs work offline. Internet URLs require a connection unless a valid cached copy exists. Downloads are verified before replacing a cached file, and failed transfers leave the previous copy intact. Nested relative filenames are accepted; absolute names and parent-directory traversal are not. The filename is the cache key: changing only the URL does not refresh an existing file. Supply the expected checksum or clear the cache to refresh it.
Examples
local({
cache <- tempfile("wa-cache-")
old <- options(writeAlizer.cache_dir = cache,
writeAlizer.mock_dir = NULL, writeAlizer.offline = TRUE)
on.exit(options(old))
on.exit(unlink(cache, recursive = TRUE), add = TRUE)
src <- tempfile(fileext = ".bin")
writeBin(as.raw(1:10), src)
on.exit(unlink(src), add = TRUE)
path <- normalizePath(src, winslash = "/")
url <- paste0(if (.Platform$OS.type == "windows") "file:///" else "file://",
utils::URLencode(path))
sha <- digest::digest(src, algo = "sha256", file = TRUE)
dest <- wa_download("example.bin", url, sha256 = sha)
file.exists(dest)
})
#> [1] TRUE