ensure_files_available: Ensure all given files exist in the file cache, download them...

In pkgfilecache: Download and Manage Optional Package Data

Ensure all given files exist in the file cache, download them if they are not.

Description

Ensure all given files exist in the file cache, download them if they are not.

Usage

ensure_files_available(
  pkg_info,
  relative_filenames,
  urls,
  files_are_binary = NULL,
  md5sums = NULL,
  on_errors = "warn",
  download = TRUE,
  num_connections = getOption("pkgfilecache.num_connections", 2),
  num_retries = 2
)

Arguments

pkg_info	named list. Package identifier, see get_pkg_info() on how to get one.
relative_filenames	vector of strings. A vector of filenames, realtive to the package cache.
urls	vector of strings. For each file, a remote URL where to download the file. Will be passed to 'curl::curl_download', see that function for URL encoding details.
files_are_binary	logical vector. For each file, whether it is binary. Only required on Windows, when files need to be downloaded. See 'curl::curl_download' docs for details.
md5sums	vector of strings or NULL. A list of MD5 checksums, one for each file in param 'relative_filenames', if not NULL. If given, the files will only be reported as existing if the MD5 sums match. A file that is present in the cache but whose MD5 sum does not match the expected sum is considered invalid and is deleted from the cache, so that it is never mistaken for a valid file.
on_errors	string. What to do if getting the files failed. One of c("warn", "stop", "ignore"). At the end, files are checked using ‘files_available'(including MD5 if given). Depending on the check results, the behaviours triggered are: "warn": Print a warning for each file that failed the check. "stop": Stop the script, i.e., the whole application. "ignore": Do nothing. You can still react using the return value. This applies whether or not downloading was attempted, so missing files are never silently ignored, e.g., when ’download' is FALSE.
download	logical. Whether to try downloading missing files. Defaults to TRUE. Existing files (with correct MD5 if available) will never be downloaded. When set to FALSE, no files are downloaded, but missing files are still reported according to 'on_errors'.
num_connections	integer. The number of parallel connections to use when downloading files. Defaults to 2. With more connections, several files are downloaded at the same time, which can speed up downloading many small files considerably. Use 1 for strictly sequential downloads. A high number of connections may overload the server or trigger rate limits. The default can be changed globally for all calls that do not specify this argument by setting the R option pkgfilecache.num_connections.
num_retries	integer. How many times to retry downloading files that failed, in addition to the first attempt. Defaults to 2. Each attempt uses fresh connections, which makes downloads robust against transient connection failures (e.g., a server that closes or throttles connections). Set to 0 to disable retrying.

Value

Named list. The list has entries: "available": vector of strings. The names of the files that are available in the local file cache. You can access them using get_filepath(). "missing": vector of strings. The names of the files that this function was unable to retrieve. "file_status": Logical array indicating whether the files are available. Order is identical to the one in argument 'relative_filenames'.

Examples

   pkg_info = get_pkg_info("mypackage");
   local_relative_filenames = c("local_file1.txt", "local_file2.txt");
   bu = "https://raw.githubusercontent.com/dfsp-spirit/";
   url1 = paste(bu, "pkgfilecache/master/inst/extdata/file1.txt", sep="");
   url2 = paste(bu, "pkgfilecache/master/inst/extdata/file2.txt", sep="");
   urls = c(url1, url2);
   md5sums = c("35261471bcd198583c3805ee2a543b1f", "85ffec2e6efb476f1ee1e3e7fddd86de");
   res = ensure_files_available(pkg_info, local_relative_filenames, urls, md5sums=md5sums);
   erase_file_cache(pkg_info); # clear full cache

pkgfilecache documentation built on Sept. 1, 2026, 1:08 a.m.