R: Download and unpack a ZIP file

use_course_details {usethis} | R Documentation

## Download and unpack a ZIP file

### Description

Details on the two functions that power `use_course()`. These internal functions are currently unexported but a course instructor may want more details.

### Arguments

`url` | Download link for the ZIP file, possibly behind a shortlink or other redirect. See Details.
`destdir` | Path to existing local directory where the ZIP file will be stored. Defaults to current working directory, but note that `use_course()` has different default behavior.
`pedantic` | Logical. When `TRUE` and in an interactive session, the user is told where the ZIP file will be stored. If happy, user can elect to proceed. Otherwise, user can abort and try again with the desired `destdir`. Intentional friction for a pedagogical setting.
`zipfile` | Path to local ZIP file.

### download_zip()

    ## function signature
    download_zip(url, destdir = getwd(), pedantic = FALSE)

    ## as called inside use_course()
    download_zip(
      url, ## after post-processing with normalize_url()
      ## conspicuous_place() = Desktop or home directory or working directory
      destdir = destdir %||% conspicuous_place(),
      pedantic = is.null(destdir) && interactive()
    )

Special-purpose function to download a ZIP file and automatically determine the file name, which often determines the folder name after unpacking. Developed with DropBox and GitHub as primary targets, possibly via shortlinks. Both platforms offer a way to download an entire folder or repo as a ZIP file, with information about the original folder or repo transmitted in the `Content-Disposition` header. In the absence of this header, a filename is generated from the input URL. In either case, the filename is sanitized. Returns the path to downloaded ZIP file, invisibly.

DropBox:

To make a folder available for ZIP download, create a shared link for it:

- https://www.dropbox.com/help/files-folders/view-only-access

A shared link will have this form:

    https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=0

Replace the `dl=0` at the end with `dl=1` to create a download link. The ZIP download link will have this form:

    https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=1

This download link (or a shortlink that points to it) is suitable as input for `download_zip()`. After one or more redirections, this link will eventually lead to a download URL. For more details, see https://www.dropbox.com/help/desktop-web/force-download and https://www.dropbox.com/en/help/desktop-web/download-entire-folders.

GitHub:

Click on the repo's "Clone or download" button, to reveal a "Download ZIP" button. Capture this URL, which will have this form:

    https://github.com/r-lib/usethis/archive/master.zip

This download link (or a shortlink that points to it) is suitable as input for `download_zip()`. After one or more redirections, this link will eventually lead to a download URL. Here's an alternative link that also leads to ZIP download, albeit with a different filenaming scheme:

    https://api.github.com/repos/r-lib/usethis/zipball/master

### tidy_unzip()

Special-purpose function to unpack a ZIP file and (attempt to) create the directory structure most people want. When unpacking an archive, it is easy to get one more or one less level of nesting than you expected.

It's especially important to finesse the directory structure here: we want the same local result when unzipping the same content from either GitHub or DropBox ZIP files, which pack things differently. Here is the intent:

- If the ZIP archive `foo.zip` does not contain a single top-level directory, i.e. it is packed as "loose parts", unzip into a directory named `foo`. Typical of DropBox ZIP files.

- If the ZIP archive `foo.zip` has a single top-level directory (which, by the way, is not necessarily called "foo"), unpack into said directory. Typical of GitHub ZIP files.

Returns path to the directory holding the unpacked files, invisibly.

DropBox: The ZIP files produced by DropBox are special. The file list tends to contain a spurious directory `"/"`, which we ignore during unzip. Also, if the directory is a Git repo and/or RStudio Project, we unzip-ignore various hidden files, such as `.RData`, `.Rhistory`, and those below `.git/` and `.Rproj.user`.

### See Also

Other download functions: `use_course`

### Examples

    ## Not run:
    download_zip("https://github.com/r-lib/rematch2/archive/master.zip")

    ## End(Not run)

    ## Not run:
    download_zip("https://github.com/r-lib/rematch2/archive/master.zip")
    tidy_unzip("rematch2-master.zip")

    ## End(Not run)

[Package usethis version 1.4.0 Index]