Skip to contents

Peek at the contents of a remote ZIP file without downloading it

Source: R/zip-peek.R
zip_peek.Rd

Uses an HTTP range request to fetch only the tail of a ZIP archive and read its central directory, returning the name and uncompressed size of every entry inside. This lets a downloader decide whether a zip is worth fetching (does it contain data, or only stimuli/assets?) before spending the bandwidth.

Usage

zip_peek(
  url,
  tail_bytes = 131072,
  cache = FALSE,
  skip_on_api_limit = FALSE,
  size = NULL
)

Arguments

url

the download URL of a ZIP file, or the path of a ZIP file already on disk (e.g. one inside a downloaded ResearchBox), which is then read directly without any request

tail_bytes

how many bytes of the tail to fetch (default 128 KB; raised automatically on retry when the central directory is larger)

cache

if TRUE, persist this URL's result to disk (see zip_peek_cache_clear()) so a later R process reuses it instead of re-peeking the archive over HTTP. Off by default, like the repository-listing cache (see repo_info_cache_clear()); a caller that never asks for caching sees no behavior change. repo_check()/data_check() forward their own cache argument here.

skip_on_api_limit

if TRUE, a confirmed exhausted rate-limit bucket during a peek is treated as a failure (returns NULL) instead of waiting out the host's reset – see download_repo_files()'s parameter of the same name. Falls back to getOption("metacheck.skip_on_api_limit") when not given directly.

size

the archive's size in bytes, when the caller already knows it (e.g. from a repository's file listing). Skips the HEAD request otherwise made to learn it – on the OSF's file server every request costs several seconds, however small the file. NULL or NA (the default) asks the host as before.

Value

a data.frame with columns name (entry path inside the zip) and size (uncompressed bytes), excluding directory entries; or NULL when the host does not support range requests or the listing cannot be read (the caller should then download-and-inspect). Also returns method, csize, offset, crc and name_bytes, which describe where each member's bytes sit in the archive so a single member can be fetched without the rest. Names without the zip's UTF-8 flag are read as CP437 (old Windows zip tools) and returned in UTF-8; name_bytes is the name's stored length. Zip64 archives (over 4 GB or over 65,535 entries) are read in full, including the sizes and offsets stored only in their Zip64 extra fields; csize and offset are NA only for an entry whose listing is malformed.

Examples

if (requireNamespace("zip", quietly = TRUE)) {
  # a zip of the demo repository; a URL of a zip on a server works the same
  z <- file.path(tempdir(), "stroop_effect_paper.zip")
  zip::zipr(z, file.path(demofile("repo"), c("data", "code", "README.md")))
  zip_peek(z)
}
#>                      name size method csize offset        crc name_bytes
#> 3 data/raw/stroop_raw.csv 2853      8  1131     74 2686692863         23
#> 4    data/stroop_data.csv 2871      8  1144   1258 2324951144         20
#> 6       code/analysis.qmd 9733      8  3689   2487  130992771         17
#> 7       code/clean_data.R  736      8   385   6223 1502631959         17
#> 8     code/references.bib  832      8   479   6655 3924336129         19
#> 9               README.md 2466      8  1169   7183   15368429          9