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.
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.
download,: logical. Whether to try downloading missing files. Defaults to TRUE. Existing files (with correct MD5 if available) will never be downloaded.
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);
#> Download file to '/home/runner/.local/share/R/mypackage/local_file1.txt' from 'https://raw.githubusercontent.com/dfsp-spirit/pkgfilecache/master/inst/extdata/file1.txt'
#> Download file to '/home/runner/.local/share/R/mypackage/local_file2.txt' from 'https://raw.githubusercontent.com/dfsp-spirit/pkgfilecache/master/inst/extdata/file2.txt'
   erase_file_cache(pkg_info); # clear full cache