return tibble instead of data.frame

ref #415

R/redcap-users-export.R

@@ -16,7 +16,20 @@
 #' @param config_options  A list of options to pass to `POST` method in the
 #' `httr` package.  See the details below.  Optional.
 #'
-#' @return a [utils::packageDescription].
+#' @return Currently, a list is returned with the following elements:
+#' * `data_user`: A [tibble::tibble()] of all users associated with the project.
+#' One row represents one user.
+#' * `data_user_form`: A [tibble::tibble()] of permissions for users and forms.
+#' One row represents a unqiue user-by-form combination.
+#' * `success`: A boolean value indicating if the operation was apparently
+#' successful.
+#' * `status_codes`: A collection of
+#' [http status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes),
+#' separated by semicolons.  There is one code for each batch attempted.
+#' * `outcome_messages`: A collection of human readable strings indicating the
+#' operations' semicolons.  There is one code for each batch attempted.  In an
+#' unsuccessful operation, it should contain diagnostic information.
+#' * `elapsed_seconds`: The duration of the function.
 #'
 #' @note
 #' **Documentation in REDCap 8.4.0**
@@ -159,8 +172,8 @@ redcap_users_export <- function(
     } else {
       # nocov start
       kernel$success   <- FALSE # Override the 'success' http status code.
-      ds_user          <- data.frame() # Return an empty data.frame
-      ds_user_form     <- data.frame() # Return an empty data.frame
+      ds_user          <- tibble::tibble() # Return an empty data.frame
+      ds_user_form     <- tibble::tibble() # Return an empty data.frame
       outcome_message  <- sprintf(
         "The REDCap user export failed.  The http status code was %i.  The 'raw_text' returned was '%s'.",
         kernel$status_code,
@@ -169,8 +182,8 @@ redcap_users_export <- function(
       # nocov end
     }
   } else {
-    ds_user          <- data.frame() # Return an empty data.frame
-    ds_user_form     <- data.frame() # Return an empty data.frame
+    ds_user          <- tibble::tibble() # Return an empty data.frame
+    ds_user_form     <- tibble::tibble() # Return an empty data.frame
     outcome_message  <- sprintf(
       "The REDCap user export failed.  The error message was:\n%s",
       kernel$raw_text

R/redcap-variables.R

@@ -18,7 +18,7 @@
 #' `httr` package.  See the details below. Optional.
 #'
 #' @return Currently, a list is returned with the following elements,
-#' * `data`: An R [base::data.frame()] where each row represents one column
+#' * `data`: A [tibble::tibble()] where each row represents one column
 #' in the REDCap dataset.
 #' * `success`: A boolean value indicating if the operation was apparently
 #' successful.
@@ -109,7 +109,7 @@ redcap_variables <- function(
     } else {
       # nocov start
       kernel$success  <- FALSE # Override the 'success' http status code.
-      ds              <- data.frame() #Return an empty data.frame
+      ds              <- tibble::tibble() # Return an empty data.frame
 
       outcome_message <- sprintf(
         "The REDCap variable retrieval failed.  The http status code was %i.  The 'raw_text' returned was '%s'.",
@@ -119,7 +119,7 @@ redcap_variables <- function(
       # nocov end
     }
   } else {
-    ds              <- data.frame() #Return an empty data.frame
+    ds              <- tibble::tibble() # Return an empty data.frame
     outcome_message <- if (any(grepl(kernel$regex_empty, kernel$raw_text))) {
       "The REDCapR read/export operation was not successful.  The returned dataset (of variables) was empty."
     } else {

tests/testthat/test-users-export.R

@@ -36,6 +36,9 @@ test_that("with-dags", {
   expect_equal(returned_object$raw_text, expected="", ignore_attr = TRUE) # dput(returned_object$raw_text)
   expect_match(returned_object$outcome_message, regexp=expected_outcome_message, perl=TRUE)
   expect_true(returned_object$success)
+
+  expect_s3_class(returned_object$data_user       , "tbl")
+  expect_s3_class(returned_object$data_user_form  , "tbl")
 })
 test_that("without DAGs", {
   testthat::skip_on_cran()
@@ -61,6 +64,9 @@ test_that("without DAGs", {
   expect_equal(returned_object$raw_text, expected="", ignore_attr = TRUE) # dput(returned_object$raw_text)
   expect_match(returned_object$outcome_message, regexp=expected_outcome_message, perl=TRUE)
   expect_true(returned_object$success)
+
+  expect_s3_class(returned_object$data_user       , "tbl")
+  expect_s3_class(returned_object$data_user_form  , "tbl")
 })
 test_that("bad token -Error", {
   testthat::skip_on_cran()

tests/testthat/test-variables.R

@@ -27,6 +27,7 @@ test_that("default", {
   expect_equal(returned_object$raw_text, expected="", ignore_attr = TRUE) # dput(returned_object$raw_text)
   expect_match(returned_object$outcome_message, regexp=expected_outcome_message, perl=TRUE)
   expect_true(returned_object$success)
+  expect_s3_class(returned_object$data, "tbl")
 })