Add query to odata_entitylist_data_get

* Allow a combination of any query parameter (filter, top, skip, count, etc.) at the cost of input sanitisation and query format validation
* Bump version to 1.5.1
* Bump dependency versions
* Spurious warning about DESC author format

DESCRIPTION

@@ -1,11 +1,16 @@
 Type: Package
 Package: ruODK
 Title: An R Client for the ODK Central API
-Version: 1.5.0.9000
-Authors@R:c(
-    person(c("Florian", "W."), "Mayer", , "[email protected]", role = c("aut", "cre"),
-           comment = c(ORCID = "0000-0003-4269-4242")),
-    person("Maëlle", "Salmon", , "[email protected]", role = "rev",
+Version: 1.5.1
+Authors@R: c(
+    person(
+      given = c("Florian", "W."),
+      family = "Mayer",
+      email = "[email protected]",
+      role = c("aut", "cre"),
+      comment = c(ORCID = "0000-0003-4269-4242")
+    ),
+    person("Maëlle", "Salmon", "[email protected]", role = "rev",
            comment = c(ORCID = "0000-0002-2815-0399")),
     person("Karissa", "Whiting", role = "rev",
            comment = c(ORCID = "0000-0002-4683-1868")),
@@ -30,44 +35,46 @@ BugReports: https://github.com/ropensci/ruODK/issues
 Depends:
     R (>= 4.1)
 Imports:
+    cli (>= 3.6.3),
     clisymbols (>= 1.2.0),
-    crayon (>= 1.5.2),
-    dplyr (>= 1.0.10),
-    fs (>= 1.6.0),
-    glue (>= 1.6.2),
-    httr (>= 1.4.4),
-    janitor (>= 2.1.0),
-    lifecycle (>= 1.0.3),
-    lubridate (>= 1.9.1),
+    crayon (>= 1.5.3),
+    dplyr (>= 1.1.4),
+    fs (>= 1.6.5),
+    glue (>= 1.8.0),
+    httr (>= 1.4.7),
+    janitor (>= 2.2.0),
+    lifecycle (>= 1.0.4),
+    lubridate (>= 1.9.3),
     magrittr (>= 2.0.3),
-    purrr (>= 1.0.1),
-    readr (>= 2.1.3),
-    rlang (>= 1.0.6),
+    purrr (>= 1.0.2),
+    readr (>= 2.1.5),
+    rlang (>= 1.1.4),
     semver (>= 0.2.0),
-    stringr (>= 1.5.0),
-    tibble (>= 3.1.8),
-    tidyr (>= 1.3.0),
-    xml2 (>= 1.3.3)
+    stringr (>= 1.5.1),
+    tibble (>= 3.2.1),
+    tidyr (>= 1.3.1),
+    withr (>= 3.0.2),
+    xml2 (>= 1.3.6)
 Suggests:
-    covr (>= 3.6.1),
-    DT (>= 0.27),
-    ggplot2 (>= 3.4.0),
+    covr (>= 3.6.4),
+    DT (>= 0.33),
+    ggplot2 (>= 3.5.1),
     here (>= 1.0.1),
-    knitr (>= 1.42),
-    lattice (>= 0.20-45),
-    leafem (>= 0.2.0.9012),
-    leaflet (>= 2.1.1),
+    knitr (>= 1.48),
+    lattice (>= 0.22-6),
+    leafem (>= 0.2.3.9007),
+    leaflet (>= 2.2.2),
     leafpop (>= 0.1.0),
-    listviewer (>= 3.0.0),
-    mapview (>= 2.11.0.9005),
-    rmarkdown (>= 2.20),
-    roxygen2 (>= 7.2.3),
-    sf (>= 1.0-9),
+    listviewer (>= 4.0.0),
+    mapview (>= 2.11.2.9000),
+    rmarkdown (>= 2.29),
+    roxygen2 (>= 7.3.2),
+    sf (>= 1.0-19),
     skimr (>= 2.1.5),
-    terra (>= 1.7-3),
-    testthat (>= 3.1.6),
-    tmap (>= 3.3-3),
-    usethis (>= 2.1.6)
+    terra (>= 1.7-83),
+    testthat (>= 3.2.1.1),
+    tmap (>= 3.3-4),
+    usethis (>= 3.0.0)
 VignetteBuilder:
     knitr
 RdMacros:
@@ -81,5 +88,4 @@ LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
 X-schema.org-applicationCategory: Data Access
-X-schema.org-keywords: database, open-data, opendatakit, odk, api, data,
-    dataset
+X-schema.org-keywords: database, open-data, odk, api, data, dataset

NAMESPACE

@@ -100,6 +100,7 @@ export(submission_list)
 export(sym)
 export(syms)
 export(user_list)
+import(rlang)
 import(semver)
 importFrom(dplyr,all_of)
 importFrom(dplyr,any_of)
@@ -108,11 +109,13 @@ importFrom(dplyr,ends_with)
 importFrom(dplyr,everything)
 importFrom(dplyr,one_of)
 importFrom(dplyr,starts_with)
+importFrom(glue,glue)
 importFrom(httr,GET)
 importFrom(httr,add_headers)
 importFrom(httr,authenticate)
 importFrom(httr,content)
 importFrom(lifecycle,deprecate_soft)
+importFrom(lifecycle,deprecated)
 importFrom(magrittr,"%>%")
 importFrom(rlang,"%||%")
 importFrom(rlang,":=")

R/odata_entitylist_data_get.R

@@ -2,8 +2,7 @@
 #'
 #' `r lifecycle::badge("experimental")`
 #'
-#' A data document is the straightforward JSON representation of all the
-#' Entities in a Dataset.
+#' All the Entities in a Dataset.
 #'
 #' The `$top` and `$skip` querystring parameters, specified by OData, apply limit
 #' and offset operations to the data, respectively.
@@ -16,43 +15,47 @@
 #' As of ODK Central v2023.4, `@odata.nextLink` contains a `$skiptoken`
 #' (an opaque cursor) to better paginate around deleted Entities.
 #'
-#' The $filter querystring parameter can be used to filter certain data fields
+#' The `$filter` querystring parameter can be used to filter certain data fields
 #' in the system-level schema, but not the Dataset properties.
-#' The operators lt, le, eq, ne, ge, gt, not, and, and or are supported.
-#' The built-in functions now, year, month, day, hour, minute, second are
-#' supported.
+#' The operators `lt`, `le`, `eq`, `ne`, `ge`, `gt`, `not`, `and`, and `or`
+#' and the built-in functions `now`, `year`, `month`, `day`, `hour`,
+#' `minute`, `second` are supported.
 #'
 #' The fields you can query against are as follows:
 #'
-#' Entity Metadata	OData Field Name
-#' Entity Creator Actor ID	__system/creatorId
-#' Entity Timestamp	__system/createdAt
-#' Entity Update Timestamp	__system/updatedAt
-#' Entity Conflict	__system/conflict
+#' Entity Metadata:	`OData Field Name`
+#' Entity Creator Actor ID:	`__system/creatorId`
+#' Entity Timestamp:	`__system/createdAt`
+#' Entity Update Timestamp:	`__system/updatedAt`
+#' Entity Conflict:	`__system/conflict`
 #'
-#' Note that createdAt and updatedAt are time components.
+#' Note that `createdAt` and `updatedAt` are time components.
 #' This means that any comparisons you make need to account for the full time
-#' of the entity. It might seem like $filter=__system/createdAt le 2020-01-31
+#' of the entity. It might seem like `$filter=__system/createdAt le 2020-01-31`
 #' would return all results on or before 31 Jan 2020, but in fact only entities
 #' made before midnight of that day would be accepted.
 #' To include all of the month of January, you need to filter by either
-#' $filter=__system/createdAt le 2020-01-31T23:59:59.999Z or
-#' $filter=__system/createdAt lt 2020-02-01.
+#' `$filter=__system/createdAt le 2020-01-31T23:59:59.999Z` or
+#' `$filter=__system/createdAt lt 2020-02-01`.
 #' Remember also that you can query by a specific timezone.
 #'
-#' Please see the OData documentation on $filter operations and functions for
-#' more information.
+#' Please see the OData documentation on `$filter`
+#  nolint start
+#' [operations](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinFilterOperations)
+#' and [functions](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinQueryFunctions)
+#  nolint end
+#' for more information.
 #'
-#' The $select query parameter will return just the fields you specify and is
-#' supported on __id, __system, __system/creatorId, __system/createdAt and
-#' __system/updatedAt, as well as on user defined properties.
+#' The `$select` query parameter will return just the fields you specify and is
+#' supported on `__id`, `__system`, `__system/creatorId`, `__system/createdAt`
+#' and `__system/updatedAt`, as well as on user defined properties.
 #'
-#' The $orderby query parameter will return Entities sorted by different fields,
-#' which come from the same list used by $filter, as noted above.
+#' The `$orderby` query parameter will return Entities sorted by different
+#' fields, which come from the same list used by `$filter`, as noted above.
 #' The order can be specified as ASC (ascending) or DESC (descending),
 #' which are case-insensitive. Multiple sort expressions can be used together,
-#' separated by commas, e.g. $orderby=__system/creatorId ASC,
-#'  __system/conflict DESC.
+#' separated by commas,
+#' e.g. `$orderby=__system/creatorId ASC, __system/conflict DESC`.
 #'
 #' As the vast majority of clients only support the JSON OData format,
 #' that is the only format ODK Central offers.
@@ -65,6 +68,24 @@
 #' @template tpl-compat-2022-3
 #' @template param-pid
 #' @template param-did
+#' @param query An optional named list of query parameters, e.g.
+#'   ```
+#'   list(
+#'     "$filter" = "__system/createdAt le 2024-11-05",
+#'     "$orderby" = "__system/creatorId ASC, __system/conflict DESC",
+#'     "$top" = "100",
+#'     "$skip" = "3",
+#'     "$count" = "true"
+#'  )
+#'  ```
+#'  No validation is conducted by `ruODK` on the query list prior to
+#'  passing it to ODK Central.
+#'  If omitted, no filter query is sent.
+#'  Note that the behaviour of this parameter differs from the implementation
+#'  of `odata_submission_get()` in that `query` here accepts a list of all
+#'  possible OData query parameters and `odata_submission_get()` offers
+#'  individual function parameters matching supported OData query parameters.
+#'  Default: `NULL`
 #' @template param-url
 #' @template param-auth
 #' @template param-retries
@@ -73,9 +94,11 @@
 #' @template param-tz
 #' @return An S3 class `odata_entitylist_data_get` with two list items:
 #'  * `context` The URL for the OData metadata document
-#'  * `value` A tibble of EntitySets available in this EntityList
-# nolint start
+#'  * `value` A tibble of EntitySets available in this EntityList, with names
+#'    cleaned by `janitor::clean_names()` and unnested list columns
+#'    (`__system`).
 #' @seealso \url{https://docs.getodk.org/central-api-odata-endpoints/#id3}
+# nolint start
 #' @seealso \url{http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948}
 # nolint end
 #' @family entity-management
@@ -92,9 +115,25 @@
 #' ds1
 #' ds1$context
 #' ds1$value
+#'
+#' qry <- list(
+#'   "$filter" = "__system/createdAt le 2024-11-05",
+#'   "$orderby" = "__system/creatorId ASC, __system/conflict DESC",
+#'   "$top" = "100",
+#'   "$skip" = "3",
+#'   "$count" = "true"
+#' )
+#' ds2 <- odata_entitylist_data_get(
+#'   pid = get_default_pid(),
+#'   did = ds$name[1],
+#'   query = qry
+#' )
+#'
+#' ds2
 #' }
 odata_entitylist_data_get <- function(pid = get_default_pid(),
                                       did = "",
+                                      query = NULL,
                                       url = get_default_url(),
                                       un = get_default_un(),
                                       pw = get_default_pw(),
@@ -114,7 +153,8 @@ odata_entitylist_data_get <- function(pid = get_default_pid(),
       path = glue::glue(
         "v1/projects/{pid}/datasets/",
         "{URLencode(did, reserved = TRUE)}.svc/Entities"
-      )
+      ),
+      query = query
     ),
     httr::add_headers(
       "Accept" = "application/json"

R/ruODK.R → R/ruODK-package.R

@@ -21,3 +21,10 @@ utils::globalVariables(c(
   "xx",
   "xml_form_id"
 ))
+
+## usethis namespace: start
+#' @import rlang
+#' @importFrom glue glue
+#' @importFrom lifecycle deprecated
+## usethis namespace: end
+NULL