new read_redcap_instrument in development

NEWS.md

@@ -6,10 +6,19 @@
 
 * NEW: `ds2dd_detailed()`: extension of the `ds2dd()`, which serves to preserve as much metadata as possible automatically. Depends on a group of helper functions also introduced. Of special note is the `guess_time_only_filter()`, which will try to guess which columns/variables should be formatted as time only formats. Supports hms time format. DETAILED INSTRUCTION AND VIGNETTE IS PENDING.
 
+* NEW: `read_redcap_instrument()` convenience function to retrieve complete instrument. Goes a little against the focused approach. DETAILED INSTRUCTION IS PENDING.
+
 ### Other
 
 I believe `renv` has now been added and runs correctly. After clone, do `renv::restore()` to install all necessary package to modify the package.
 
+### Whishes before CRAN release
+
+* Vignette for `ds2dd_detailed()`
+
+* Tests for `ds2dd_detailed()`
+
+
 # REDCapCAST 24.1.1
 
 ### Functions

R/read_redcap_instrument.R

@@ -0,0 +1,25 @@
+#' Convenience function to download complete instrument, using token storage in keyring.
+#'
+#' @param key key name in standard keyring for token retrieval.
+#' @param uri redcap api url
+#' @param instrument instrument name
+#' @param raw_or_label raw or label passed to `REDCapR::redcap_read()`
+#' @param id_name id variable name. Default is "record_id".
+#' @param records specify the records to download. Index numbers. Numeric vector.
+#'
+#' @return data.frame
+#' @export
+read_redcap_instrument <- function(key,
+                            uri,
+                            instrument = "rbans",
+                            raw_or_label = "raw",
+                            id_name = "record_id",
+                            records = NULL) {
+  REDCapCAST::read_redcap_tables(
+    records = records,
+    uri = uri, token = keyring::key_get(key),
+    fields = id_name,
+    forms = instrument,
+    raw_or_label = raw_or_label
+  )[[{{ instrument }}]]
+}

man/read_redcap_instrument.Rd

@@ -0,0 +1,34 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/read_redcap_instrument.R
+\name{read_redcap_instrument}
+\alias{read_redcap_instrument}
+\title{Convenience function to download complete instrument, using token storage in keyring.}
+\usage{
+read_redcap_instrument(
+  key,
+  uri,
+  instrument = "rbans",
+  raw_or_label = "raw",
+  id_name = "record_id",
+  records = NULL
+)
+}
+\arguments{
+\item{key}{key name in standard keyring for token retrieval.}
+
+\item{uri}{redcap api url}
+
+\item{instrument}{instrument name}
+
+\item{raw_or_label}{raw or label passed to `REDCapR::redcap_read()`}
+
+\item{id_name}{id variable name. Default is "record_id".}
+
+\item{records}{specify the records to download. Index numbers. Numeric vector.}
+}
+\value{
+data.frame
+}
+\description{
+Convenience function to download complete instrument, using token storage in keyring.
+}