Skip to content

Commit 046ec09

Browse files
Florian MayerFlorian Mayer
Florian Mayer
authored and
Florian Mayer
committed
#16 ru_settings
Add getters and setter for settings, tests, docs. Convert project_* and related tests to use settings getters as defaults. TODO convert remaining functions.
1 parent a27917d commit 046ec09

10 files changed

+1492
-0
lines changed

‎R/ru_setup.R

+256
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
#' Get or set \code{ruODK} settings.
2+
#'
3+
#' @export
4+
#' @return \code{ru_settings} prints your default ODK Central url, username,
5+
#' and password, and corresponding optional test server settings.
6+
#' \code{ru_setup} sets your production and test settings, while
7+
#' \code{get_(test_)*} get each of those respective settings.
8+
#' @seealso \code{\link{ru_setup}},
9+
#' \code{\link{get_default_url}},
10+
#' \code{\link{get_default_un}},
11+
#' \code{\link{get_default_pw}},
12+
#' \code{\link{get_test_url}},
13+
#' \code{\link{get_test_un}},
14+
#' \code{\link{get_test_pw}},
15+
#' \code{\link{get_test_pid}},
16+
#' \code{\link{get_test_fid}}.
17+
#' @family ru_settings
18+
#' @examples
19+
#' ru_settings()
20+
ru_settings <- function() {
21+
ops <- list(
22+
url = Sys.getenv("ODKC_URL", ""),
23+
un = Sys.getenv("ODKC_UN", ""),
24+
pw = Sys.getenv("ODKC_PW", ""),
25+
test_url = Sys.getenv("ODKC_TEST_URL", ""),
26+
test_un = Sys.getenv("ODKC_TEST_UN", ""),
27+
test_pw = Sys.getenv("ODKC_TEST_PW", ""),
28+
test_pid = Sys.getenv("ODKC_TEST_PID", ""),
29+
test_fid = Sys.getenv("ODKC_TEST_FID", "")
30+
)
31+
structure(ops, class = "ru_settings")
32+
}
33+
34+
#' @export
35+
print.ru_settings <- function(x, ...) {
36+
cat("<ruODK settings>", sep = "\n")
37+
cat(" Default ODK Central URL: ", x$url, "\n")
38+
cat(" Default ODK Central Username: ", x$un, "\n")
39+
cat(" Default ODK Central Password: ", x$pw, "\n")
40+
cat(" Test ODK Central URL:", x$test_url, "\n")
41+
cat(" Test ODK Central Username:", x$test_un, "\n")
42+
cat(" Test ODK Central Password:", x$test_pw, "\n")
43+
cat(" Test ODK Central Project ID:", x$test_pid, "\n")
44+
cat(" Test ODK Central Form ID:", x$test_fid, "\n")
45+
}
46+
47+
#------------------------------------------------------------------------------#
48+
# Setters
49+
#
50+
#' Configure default \code{ruODK} settings.
51+
#'
52+
#' @export
53+
#' @param url An ODK Central URL, e.g. "https://sandbox.central.opendatakit.org".
54+
#' @param un An ODK Central username which is the email of a "web user" in the
55+
#' specified ODK Central instance \code{url} (optional, character).
56+
#' @param pw The password for user \code{un} (optional, character).
57+
#' @param test_url (optional, character) A valid ODK Central URL for testing.
58+
#' @param test_un (optional, character) A valid ODK Central username (email)
59+
#' privileged to view the test project(s) at \code{test_url}.
60+
#' @param test_pw (optional, character) The valid ODK Central password for
61+
#' \code{test_un}.
62+
#' @param test_pid (optional, integer) The numeric ID of an existing project on
63+
#' \code{test_url}.
64+
#' @param test_fid (optional, character) The alphanumeric ID of an existing form
65+
#' in \code{test_pid}.
66+
#' @family ru_settings
67+
#' @details
68+
#' \code{ru_setup} sets ODK Central connection details. \code{ruODK}'s functions
69+
#' default to use the default URL, username, and password unless specified
70+
#' explicitly.
71+
#'
72+
#' \code{ruODK}'s automated tests require a valid ODK Central URL, and a
73+
#' privileged username and password of a "web user" on that ODK Central
74+
#' instance, as well as an existing project and form.
75+
#'
76+
#' @examples
77+
#' # \code{ruODK} users only need default settings to their ODK Central instance:
78+
#' ru_setup(url = "https://my-odkc.com", un = "[email protected]", pw = "...")
79+
#'
80+
#' # \code{ruODK} contributors and maintainers need specific ODK Central instances
81+
#' # to run tests and build vignettes, see contributing guide:
82+
#' ru_setup(
83+
#' url = "https://odkcentral.dbca.wa.gov.au",
84+
#' un = "[email protected]",
85+
#' pw = "...",
86+
#' test_url = "https://sandbox.central.opendatakit.org",
87+
#' test_un = "[email protected]",
88+
#' test_pw = "...",
89+
#' test_pid = 14,
90+
#' test_fid = "build_Flora-Quadrat-0-2_1558575936"
91+
#' )
92+
ru_setup <- function(url = NULL,
93+
un = NULL,
94+
pw = NULL,
95+
test_url = NULL,
96+
test_un = NULL,
97+
test_pw = NULL,
98+
test_pid = NULL,
99+
test_fid = NULL) {
100+
if (!is.null(url)) Sys.setenv("ODKC_URL" = url)
101+
if (!is.null(un)) Sys.setenv("ODKC_UN" = un)
102+
if (!is.null(pw)) Sys.setenv("ODKC_PW" = pw)
103+
if (!is.null(test_url)) Sys.setenv("ODKC_TEST_URL" = test_url)
104+
if (!is.null(test_un)) Sys.setenv("ODKC_TEST_UN" = test_un)
105+
if (!is.null(test_pw)) Sys.setenv("ODKC_TEST_PW" = test_pw)
106+
if (!is.null(test_pid)) Sys.setenv("ODKC_TEST_PID" = test_pid)
107+
if (!is.null(test_fid)) Sys.setenv("ODKC_TEST_FID" = test_fid)
108+
}
109+
110+
#------------------------------------------------------------------------------#
111+
# Getters
112+
#
113+
#' @export
114+
#' @rdname ru_settings
115+
get_default_url <- function() {
116+
x <- Sys.getenv("ODKC_URL")
117+
if (identical(x, "")) {
118+
rlang::warn("No default ODK Central URL set. ru_setup()?")
119+
}
120+
x
121+
}
122+
123+
#' @export
124+
#' @rdname ru_settings
125+
get_default_un <- function() {
126+
x <- Sys.getenv("ODKC_UN")
127+
if (identical(x, "")) {
128+
rlang::warn("No default ODK Central username set. ru_setup()?")
129+
}
130+
x
131+
}
132+
133+
#' @export
134+
#' @rdname ru_settings
135+
get_default_pw <- function() {
136+
x <- Sys.getenv("ODKC_PW")
137+
if (identical(x, "")) {
138+
rlang::warn("No default ODK Central password set. ru_setup()?")
139+
}
140+
x
141+
}
142+
143+
#' @export
144+
#' @rdname ru_settings
145+
get_test_url <- function() {
146+
x <- Sys.getenv("ODKC_TEST_URL")
147+
if (identical(x, "")) {
148+
rlang::warn("No test ODK Central URL set. ru_setup()?")
149+
}
150+
x
151+
}
152+
153+
#' @export
154+
#' @rdname ru_settings
155+
get_test_un <- function() {
156+
x <- Sys.getenv("ODKC_TEST_UN")
157+
if (identical(x, "")) {
158+
rlang::warn("No test ODK Central username set. ru_setup()?")
159+
}
160+
x
161+
}
162+
163+
#' @export
164+
#' @rdname ru_settings
165+
get_test_pw <- function() {
166+
x <- Sys.getenv("ODKC_TEST_PW")
167+
if (identical(x, "")) {
168+
rlang::warn("No test ODK Central password set. ru_setup()?")
169+
}
170+
x
171+
}
172+
173+
#' @export
174+
#' @rdname ru_settings
175+
get_test_pid <- function() {
176+
x <- Sys.getenv("ODKC_TEST_PID")
177+
if (identical(x, "")) {
178+
rlang::warn("No test ODK Central project ID set. ru_setup()?")
179+
}
180+
x
181+
}
182+
183+
#' @export
184+
#' @rdname ru_settings
185+
get_test_fid <- function() {
186+
x <- Sys.getenv("ODKC_TEST_FID")
187+
if (identical(x, "")) {
188+
rlang::warn("No test ODK Central form ID set. ru_setup()?")
189+
}
190+
x
191+
}
192+
193+
#' Abort on missing ODK Central credentials (url, username, password).
194+
#'
195+
#' @param url A URL (character)
196+
#' @param un A username (character)
197+
#' @param pw A password (character)
198+
#' @param pid A project ID (numeric, optional)
199+
#' @param fid A form ID (character, optional)
200+
#' @details This is a helper function to pat down \code{ruODK} functions for
201+
#' missing credentials and stop with a loud but informative yell.
202+
#' @family ru_settings
203+
#' @export
204+
#' @examples
205+
#' testthat::expect_error(yell_if_missing("", "username", "password"))
206+
#' testthat::expect_error(yell_if_missing("url", "", "password"))
207+
#' testthat::expect_error(yell_if_missing("url", "username", ""))
208+
#' testthat::expect_error(yell_if_missing(NULL, "", ""))
209+
#' testthat::expect_error(yell_if_missing("", "", ""))
210+
#' testthat::expect_error(yell_if_missing("", "", "", ""))
211+
#' testthat::expect_error(yell_if_missing("", "", "", "", ""))
212+
yell_if_missing <- function(url, un, pw, pid = NULL, fid = NULL) {
213+
if (is.null(url) | identical(url, "")) {
214+
rlang::abort("Missing ODK Central URL. ru_setup()?")
215+
}
216+
if (is.null(un) | identical(un, "")) {
217+
rlang::abort("Missing ODK Central username. ru_setup()?")
218+
}
219+
if (is.null(pw) | identical(pw, "")) {
220+
rlang::abort("Missing ODK Central password. ru_setup()?")
221+
}
222+
if (!is.null(pid) && identical(pid, "")) {
223+
rlang::abort("Missing ODK Central project ID. ru_setup()?")
224+
}
225+
if (!is.null(fid) && identical(fid, "")) {
226+
rlang::abort("Missing ODK Central form ID. ru_setup()?")
227+
}
228+
}
229+
230+
#' Warn about failed web requests and give helpful troubleshooting tips.
231+
#'
232+
#' A wrapper around \code{httr::stop_for_status()} with a helpful error message.
233+
#' Examples: see tests for \code{ruODK::project_list()}.
234+
#' This function is used internally but may be useful for debugging and
235+
#' \code{ruODK} development.
236+
#' @param response A httr response object
237+
#' @param url A URL (character)
238+
#' @param un A username (character)
239+
#' @param pw A password (character)
240+
#' @param pid A project ID (numeric, optional)
241+
#' @param fid A form ID (character, optional)
242+
#' @return The response object
243+
#' @family ru_settings
244+
yell_if_error <- function(response, url, un, pw, pid = NULL, fid = NULL){
245+
response %>%
246+
httr::stop_for_status(
247+
task = glue::glue(
248+
"connect to {url} as user {un} with password {pw}.\n",
249+
"This request failed likely on incorrect credentials (url, un, pw).\n",
250+
"Troubleshooting tips:\n",
251+
"If you have used this function with default settings, ",
252+
"check ru_settings() and run ru_setup() with working credentials.\n",
253+
'Read the vignette("Setup", package = "ruODK") for details of setting ',
254+
"up ruODK")
255+
)
256+
}

0 commit comments

Comments
 (0)