Use check_exclusive() to enhance API

Signed-off-by: Liang Zhang <[email protected]>

Author: psychelzh

R/targets.R

@@ -5,17 +5,15 @@
 #' specific project and task/game combination. Further pre-processing on the
 #' fetched data can also be added if requested.
 #'
-#' @param params A [data.frame] or [list] contains the parameters to be bound to
-#'   the query. Default templates require specifying `organization_name` and
-#'   `project_name`, in that order. If `contents` template is specified without
-#'   any parameters, set it as empty vector or `NULL`. If `contents` argument is
-#'   specified, this argument is omitted.
+#' @param params,contents Used as the configuration of data fetching. These two
+#'   arguments are mutually exclusive. If `params` is specified, it will be used
+#'   as parameters to be bound to the query, see [DBI::dbBind()] for more
+#'   details. The default template requires specifying `organization_name` and
+#'   `project_name`, in that order. If `contents` is specified, it should be a
+#'   [data.frame] and will be used directly as the configuration of data
+#'   fetching. Note `contents` should at least contain `project_id` and
+#'   `game_id` names.
 #' @param ... For future usage. Should be empty.
-#' @param contents The contents structure used as the configuration of data
-#'   fetching. It is typically automatically fetched from database based on the
-#'   `contents` template in `templates`. If not `NULL`, it will be used directly
-#'   and ignore that specified in `templates`. Note `contents` should at least
-#'   contains `project_id` and `game_id` names.
 #' @param what What to fetch. There are basically two types of data, i.e., raw
 #'   data and scores. The former is the logged raw data for each trial of the
 #'   tasks/games, while the latter is the scores calculated by iQuizoo server.
@@ -29,23 +27,37 @@
 #'   done. If set as "none", neither will be done. If `what` is "scores", this
 #'   argument will be ignored.
 #' @param combine Specify which targets to be combined. Note you should only
-#'   specify names from `c("scores", "raw_data", "raw_data_parsed",
-#'   "indices")`. If `NULL`, none will be combined.
+#'   specify names from `c("scores", "raw_data", "raw_data_parsed", "indices")`.
+#'   If `NULL`, none will be combined.
 #' @param templates The SQL template files used to fetch data. See
 #'   [setup_templates()] for details.
 #' @param check_progress Whether to check the progress hash. Set it as `FALSE`
 #'   if the project is finalized.
 #' @return A list of target objects.
 #' @export
-tar_prep_iquizoo <- function(params, ...,
-                             contents = NULL,
+tar_prep_iquizoo <- function(params, contents, ...,
                              what = c("raw_data", "scores"),
                              action_raw_data = c("all", "parse", "none"),
                              combine = NULL,
                              templates = setup_templates(),
                              check_progress = TRUE) {
   check_dots_empty()
   check_templates(templates)
+  contents <- switch(check_exclusive(params, contents),
+    params = fetch_iquizoo_mem()(
+      read_file(templates$contents),
+      params = unname(
+        if (!is_empty(params)) as.list(params)
+      )
+    ),
+    contents = {
+      stopifnot(
+        "`content` must be a `data.frame`." =
+          is.data.frame(contents)
+      )
+      contents
+    }
+  )
   what <- match.arg(what, several.ok = TRUE)
   action_raw_data <- match.arg(action_raw_data)
   if (!is.null(combine) && !all(combine %in% objects())) {
@@ -54,14 +66,6 @@ tar_prep_iquizoo <- function(params, ...,
       class = "tarflow_bad_combine"
     )
   }
-  if (is.null(contents)) {
-    contents <- fetch_iquizoo_mem()(
-      read_file(templates$contents),
-      params = unname(
-        if (!is_empty(params)) as.list(params)
-      )
-    )
-  }
   if (nrow(contents) == 0) {
     cli::cli_abort(
       "No contents to fetch.",

man/tar_prep_iquizoo.Rd

@@ -42,7 +42,7 @@
         {
           "type": "character",
           "attributes": {},
-          "value": ["陈佳洋", "茹祎", "于胜蓝", "李荟镕", "张忱涵", "连宗鸿", "徐小琳"]
+          "value": ["徐小琳", "连宗鸿", "张忱涵", "李荟镕", "于胜蓝", "茹祎", "陈佳洋"]
         },
         {
           "type": "integer",
@@ -58,7 +58,7 @@
               "value": ["Date"]
             }
           },
-          "value": [-25202, -25201, -25200, -25199, -25198, -25197, -25196]
+          "value": [-25196, -25197, -25198, -25199, -25200, -25201, -25202]
         },
         {
           "type": "character",

tests/testthat/_snaps/targets.md

@@ -10,7 +10,7 @@ test_that("Default templates work", {
 
 test_that("Signal error if templates not created correctly", {
   templates <- list(contents = "myfile")
-  tar_prep_iquizoo(templates = templates) |>
+  tar_prep_iquizoo(NULL, templates = templates) |>
     expect_error(class = "tarflow_bad_templates")
 })