1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/course.R
\name{use_course_details}
\alias{use_course_details}
\alias{tidy_download}
\alias{tidy_unzip}
\alias{create_download_url}
\title{Helpers to download and unpack a ZIP file}
\usage{
tidy_download(url, destdir = getwd())
tidy_unzip(zipfile, cleanup = FALSE)
create_download_url(url)
}
\arguments{
\item{url}{A GitHub, DropBox, or Google Drive URL.
\itemize{
\item For \code{create_download_url()}: A URL copied from a web browser.
\item For \code{tidy_download()}: A download link for a ZIP file, possibly behind a
shortlink or other redirect. \code{create_download_url()} can be helpful for
creating this URL from typical browser URLs.
}}
\item{destdir}{Path to existing local directory where the ZIP file will be
stored. Defaults to current working directory, but note that \code{\link[=use_course]{use_course()}}
has different default behavior.}
\item{zipfile}{Path to local ZIP file.}
\item{cleanup}{Whether to delete the ZIP file after unpacking. In an
interactive session, \code{cleanup = NA} leads to asking the user if they
want to delete or keep the ZIP file.}
}
\description{
Details on the internal and helper functions that power \code{\link[=use_course]{use_course()}} and
\code{\link[=use_zip]{use_zip()}}. Only \code{create_download_url()} is exported.
}
\section{tidy_download()}{
\if{html}{\out{<div class="sourceCode">}}\preformatted{# how it's used inside use_course()
tidy_download(
# url has been processed with internal helper normalize_url()
url,
# conspicuous_place() = `getOption('usethis.destdir')` or desktop or home
# directory or working directory
destdir = destdir \%||\% conspicuous_place()
)
}\if{html}{\out{</div>}}
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 \code{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.
\code{tidy_download()} is setup to retry after a download failure. In an
interactive session, it asks for user's consent. All retries use a longer
connect timeout.
\subsection{DropBox}{
To make a folder available for ZIP download, create a shared link for it:
\itemize{
\item \url{https://help.dropbox.com/share/create-and-share-link}
}
A shared link will have this form:
\if{html}{\out{<div class="sourceCode">}}\preformatted{https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=0
}\if{html}{\out{</div>}}
Replace the \code{dl=0} at the end with \code{dl=1} to create a download link:
\if{html}{\out{<div class="sourceCode">}}\preformatted{https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=1
}\if{html}{\out{</div>}}
You can use \code{create_download_url()} to do this conversion.
This download link (or a shortlink that points to it) is suitable as input
for \code{tidy_download()}. After one or more redirections, this link will
eventually lead to a download URL. For more details, see
\url{https://help.dropbox.com/share/force-download} and
\url{https://help.dropbox.com/sync/download-entire-folders}.
}
\subsection{GitHub}{
Click on the repo's "Clone or download" button, to reveal a "Download ZIP"
button. Capture this URL, which will have this form:
\if{html}{\out{<div class="sourceCode">}}\preformatted{https://github.com/r-lib/usethis/archive/main.zip
}\if{html}{\out{</div>}}
This download link (or a shortlink that points to it) is suitable as input
for \code{tidy_download()}. After one or more redirections, this link will
eventually lead to a download URL. Here are other links that also lead to
ZIP download, albeit with a different filenaming scheme (REF could be a
branch name, a tag, or a SHA):
\if{html}{\out{<div class="sourceCode">}}\preformatted{https://github.com/github.com/r-lib/usethis/zipball/HEAD
https://api.github.com/repos/r-lib/rematch2/zipball/REF
https://api.github.com/repos/r-lib/rematch2/zipball/HEAD
https://api.github.com/repos/r-lib/usethis/zipball/REF
}\if{html}{\out{</div>}}
You can use \code{create_download_url()} to create the "Download ZIP" URL from
a typical GitHub browser URL.
}
\subsection{Google Drive}{
To our knowledge, it is not possible to download a Google Drive folder as a
ZIP archive. It is however possible to share a ZIP file stored on Google
Drive. To get its URL, click on "Get the shareable link" (within the "Share"
menu). This URL doesn't allow for direct download, as it's designed to be
processed in a web browser first. Such a sharing link looks like:
\if{html}{\out{<div class="sourceCode">}}\preformatted{https://drive.google.com/open?id=123456789xxyyyzzz
}\if{html}{\out{</div>}}
To be able to get the URL suitable for direct download, you need to extract
the "id" element from the URL and include it in this URL format:
\if{html}{\out{<div class="sourceCode">}}\preformatted{https://drive.google.com/uc?export=download&id=123456789xxyyyzzz
}\if{html}{\out{</div>}}
Use \code{create_download_url()} to perform this transformation automatically.
}
}
\section{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:
\itemize{
\item If the ZIP archive \code{foo.zip} does not contain a single top-level directory,
i.e. it is packed as "loose parts", unzip into a directory named \code{foo}.
Typical of DropBox ZIP files.
\item If the ZIP archive \code{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.
\strong{DropBox:}
The ZIP files produced by DropBox are special. The file list tends to contain
a spurious directory \code{"/"}, 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 \code{.RData}, \code{.Rhistory}, and those below \verb{.git/} and
\code{.Rproj.user}.
}
\examples{
\dontrun{
tidy_download("https://github.com/r-lib/rematch2/archive/main.zip")
tidy_unzip("rematch2-main.zip")
}
# GitHub
create_download_url("https://github.com/r-lib/usethis")
create_download_url("https://github.com/r-lib/usethis/issues")
# DropBox
create_download_url("https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=0")
# Google Drive
create_download_url("https://drive.google.com/open?id=123456789xxyyyzzz")
create_download_url("https://drive.google.com/open?id=123456789xxyyyzzz/view")
}
\keyword{internal}
|
