tidy after refactoring to kernel

closes #213

NEWS

@@ -7,7 +7,7 @@ In the future:
 Version 0.10 (to be released)
 ------------------------------------------------------------------------------
 Minor New Features:
-* export survey time-stamps optionally (#159)
+* export survey time-stamps optionally (Issue #159)
 * `redcap_read()` and `redcap_read_oneshot()` allow the user to specify if all variables
   should be returned with the `character` data type.  The default is to allow `readr::read_csv()` to guess the data type. (#194)
 * `redcap_read_oneshot()` allows use to specify how many rows should be considered when `readr::read_csv()` guesses the data type. (#194)
@@ -22,10 +22,11 @@ Minor New Features:
 * parameters in `redcap_read()` and `redcap_read_oneshot()` are more consistent with the order in raw REDCap API. (#204)
 
 Modified Internals:
+* All interaction with the REDCap server goes through the new `kernal_api()` function, which uses the 'httr' and 'curl' packages underneath.  Until now, each function called those packages directly. (#213)
 * When converting REDCap's CSV to R's data.frame, `readr::read_csv()` is used instead of `utils::read.csv()` (Issue #127).
+* updated to readr 1.2.0 (#200).  This changed how some data variables were assigned a data types
 * uses `odbc` package to retrieve credentials from the token server.  Remove RODBC and RODBCext (#188)
 * `data.table::rbindlist()` replaced by `dplyr::bind_rows()`
-* updated to readr 1.2.0 (#200)
 * the checkmate package inspects most function parameters now (instead of `testit::assert()` and `base:stop()` ) (#190 & #208).
 * `collapse_vector()` is refactored and tested (#209)
 

R/metadata-utilities.R

@@ -8,7 +8,7 @@
 #' @param pattern The regular expression pattern.  Required.
 #' @param text The text to apply the regex against.  Required.
 #' @param select_choices The text containing the choices that should be parsed to determine the `id` and `label` values.  Required.
-#' @param perl Indicates if perl-compatible regexps should be used.  Optional.
+#' @param perl Indicates if perl-compatible regexps should be used.  Default is `TRUE`. Optional.
 #'
 #' @return Currently, a [base::data.frame()] is returned a row for each match, and a column for each *named* group within a match.  For the `retrieve_checkbox_choices()` function, the columns will be.
 #' * `id`: The numeric value assigned to each choice (in the data dictionary).

R/project-simple.R

@@ -29,10 +29,10 @@ populate_project_simple <- function( batch = FALSE ) {
 
   #Import the data into the REDCap project
   testthat::expect_message(
-    if( batch ) {
-      returned_object <- REDCapR::redcap_write(ds=dsToWrite, redcap_uri=uri, token=token, verbose=TRUE)
+    returned_object <- if( batch ) {
+      REDCapR::redcap_write(ds=dsToWrite, redcap_uri=uri, token=token, verbose=TRUE)
     } else {
-      returned_object <- REDCapR::redcap_write_oneshot(ds=dsToWrite, redcap_uri=uri, token=token, verbose=TRUE)
+      REDCapR::redcap_write_oneshot(ds=dsToWrite, redcap_uri=uri, token=token, verbose=TRUE)
     }
   )
   # For internal inspection: REDCapR::redcap_read_oneshot(redcap_uri=uri, token=token, verbose=TRUE)
@@ -90,7 +90,7 @@ upload_file_simple <- function( redcap_uri, token=token ) {
   token <- sanitize_token(token)
 
   for( i in seq_along(records) ) {
-    record <- records[i]
+    record    <- records[i]
     file_path <- file_paths[i]
     redcap_upload_file_oneshot(file_name=file_path, record=record, field=field, redcap_uri=redcap_uri, token=token)
   }

R/redcap-download-file-oneshot.R

@@ -112,7 +112,7 @@ redcap_download_file_oneshot <- function(
     if( missing(file_name) | is.null(file_name) ) {
       #process the content-type to get the file name
       regex_matches <- regmatches(kernel$result_headers, regexpr("name=.*", kernel$result_headers))
-      file_name <- gsub(pattern='(name=.)|(")', replacement="", x=regex_matches)
+      file_name     <- gsub(pattern='(name=.)|(")', replacement="", x=regex_matches)
     }
 
     file_path <- if( missing(directory) & is.null(directory) ) {
@@ -133,14 +133,14 @@ redcap_download_file_oneshot <- function(
 
     outcome_message <- paste0(
       result_header, " successfully downloaded in " ,
-      round(kernel$elapsed_seconds, 1), " seconds, and saved as ", file_path
+      round(kernel$elapsed_seconds, 1), " seconds, and saved as ", file_path, "."
     )
-    recordsAffectedCount   <- length(record)
-    record_id              <- as.character(record)
-    kernel$raw_text        <- ""  # If an operation is successful, the `raw_text` is no longer returned to save RAM.  The content is not really necessary with httr's status message exposed.
+    records_affected_count  <- length(record)
+    record_id               <- as.character(record)
+    kernel$raw_text         <- ""  # If an operation is successful, the `raw_text` is no longer returned to save RAM.  The content is not really necessary with httr's status message exposed.
   } else { #If the operation was unsuccessful, then...
-    outcome_message         <- paste0("file NOT downloaded ")
-    recordsAffectedCount    <- 0L
+    outcome_message         <- "file NOT downloaded."
+    records_affected_count  <- 0L
     record_id               <- character(0) # Return an empty vector.
     raw_text                <- httr::content(kernel$result, type="text")
     file_path               <- character(0)
@@ -153,7 +153,7 @@ redcap_download_file_oneshot <- function(
     success                  = kernel$success,
     status_code              = kernel$status_code,
     outcome_message          = outcome_message,
-    records_affected_count   = recordsAffectedCount,
+    records_affected_count   = records_affected_count,
     affected_ids             = record_id,
     elapsed_seconds          = kernel$elapsed_seconds,
     raw_text                 = kernel$raw_text,

R/redcap-read.R

@@ -97,7 +97,7 @@ redcap_read <- function(
 
   checkmate::assert_character(redcap_uri                , any.missing=F, len=1, pattern="^.{1,}$")
   checkmate::assert_character(token                     , any.missing=F, len=1, pattern="^.{1,}$")
-  checkmate::assert_atomic(records                      , any.missing=T, min.len=0)
+  checkmate::assert_atomic(  records                    , any.missing=T, min.len=0)
   checkmate::assert_character(records_collapsed         , any.missing=T, len=1, pattern="^.{0,}$", null.ok=T)
   checkmate::assert_character(fields                    , any.missing=T, min.len=1, pattern="^.{1,}$", null.ok=T)
   checkmate::assert_character(fields_collapsed          , any.missing=T, len=1, pattern="^.{0,}$", null.ok=T)

R/redcap-upload-file-oneshot.R

@@ -65,9 +65,17 @@
 #' }
 #' }
 
-redcap_upload_file_oneshot <- function( file_name, record, redcap_uri, token, field, event="", verbose=TRUE, config_options=NULL ) {
+redcap_upload_file_oneshot <- function(
+  file_name,
+  record,
+  redcap_uri,
+  token,
+  field,
+  event             = "",
+  verbose           = TRUE,
+  config_options    = NULL
+) {
 
-  # start_time <- Sys.time()
   checkmate::assert_character(file_name                 , any.missing=F, len=1, pattern="^.{1,}$")
   checkmate::assert_file_exists(file_name                                                        )
   checkmate::assert_character(redcap_uri                , any.missing=F, len=1, pattern="^.{1,}$")
@@ -93,39 +101,28 @@ redcap_upload_file_oneshot <- function( file_name, record, redcap_uri, token, fi
 
   # This is the important line that communicates with the REDCap server.
   kernel <- kernel_api(redcap_uri, post_body, config_options)
-  #
-  # result <- httr::POST(
-  #   url    = redcap_uri,
-  #   body   = post_body,
-  #   config = config_options
-  # )
-  #
-  # status_code       <- result$status_code
-  # elapsed_seconds   <- as.numeric(difftime(Sys.time(), start_time, units="secs"))
-  # success           <- (status_code == 200L)
 
   if( kernel$success ) {
-    outcome_message <- paste0("file uploaded to REDCap in ",  round(kernel$elapsed_seconds, 1), " seconds.")
-    recordsAffectedCount <- 1
-    record_id <- as.character(record)
-    kernel$raw_text <- ""
-  }
-  else { #If the returned content wasn't recognized as valid IDs, then
-    raw_text               <- httr::content(kernel$result, type="text") # TODO: would this be stored as kernal$raw_text?
-    outcome_message        <- paste0("file NOT uploaded ")
-    recordsAffectedCount   <- 0L
-    record_id              <- character(0) # Return an empty vector.
+    outcome_message         <- paste0("file uploaded to REDCap in ",  round(kernel$elapsed_seconds, 1), " seconds.")
+    records_affected_count  <- 1
+    record_id               <- as.character(record)
+    kernel$raw_text         <- ""
+  } else { #If the returned content wasn't recognized as valid IDs, then
+    raw_text                <- httr::content(kernel$result, type="text") # TODO: would this be stored as kernal$raw_text?
+    outcome_message         <- paste0("file NOT uploaded ")
+    records_affected_count  <- 0L
+    record_id               <- character(0) # Return an empty vector.
   }
   if( verbose )
     message(outcome_message)
 
   return( list(
-    success                  = kernel$success,
-    status_code              = kernel$status_code,
-    outcome_message          = outcome_message,
-    records_affected_count   = recordsAffectedCount,
-    affected_ids             = record_id,
-    elapsed_seconds          = kernel$elapsed_seconds,
-    raw_text                 = kernel$raw_text
+    success                 = kernel$success,
+    status_code             = kernel$status_code,
+    outcome_message         = outcome_message,
+    records_affected_count  = records_affected_count,
+    affected_ids            = record_id,
+    elapsed_seconds         = kernel$elapsed_seconds,
+    raw_text                = kernel$raw_text
   ))
 }

R/redcap-version.R

@@ -21,8 +21,7 @@
 #' redcap_version(redcap_uri=uri, token=token)
 
 redcap_version <- function( redcap_uri, token, verbose=TRUE, config_options=NULL ) {
-  version_error=base::package_version("0.0.0")
-  # start_time <- Sys.time()
+  version_error <- base::package_version("0.0.0")
 
   checkmate::assert_character(redcap_uri                , any.missing=F, len=1, pattern="^.{1,}$")
   checkmate::assert_character(token                     , any.missing=F, len=1, pattern="^.{1,}$")
@@ -37,27 +36,6 @@ redcap_version <- function( redcap_uri, token, verbose=TRUE, config_options=NULL
   # This is the important line that communicates with the REDCap server.
   kernel <- kernel_api(redcap_uri, post_body, config_options)
 
-  # result <- httr::POST(
-  #   url     = redcap_uri,
-  #   body    = post_body
-  # )
-  # status_code <- result$status
-  # success <- (status_code==200L)
-  #
-  # raw_text <- httr::content(result, "text")
-  # elapsed_seconds <- as.numeric(difftime(Sys.time(), start_time, units="secs"))
-  #
-  # # raw_text <- "The hostname (redcap-db.hsc.net.ou.edu) / username (redcapsql) / password (XXXXXX) combination could not connect to the MySQL server. \r\n\t\tPlease check their values."
-  # regex_cannot_connect <- "^The hostname \\((.+)\\) / username \\((.+)\\) / password \\((.+)\\) combination could not connect.+"
-  # regex_empty <- "^\\s+$"
-  #
-  # if(
-  #   any(grepl(regex_cannot_connect, raw_text)) |
-  #   any(grepl(regex_empty, raw_text))
-  # ) {
-  #   success <- FALSE
-  # }
-
   if( kernel$success ) {
     try (
       {
@@ -78,8 +56,7 @@ redcap_version <- function( redcap_uri, token, verbose=TRUE, config_options=NULL
       version          <- version_error
       outcome_message  <- paste0("The REDCap version determination failed.  The http status code was ", kernel$status_code, ".  The 'raw_text' returned was '", kernel$raw_text, "'.")
     }
-  }
-  else {
+  } else {
     version          <- version_error
     outcome_message  <- paste0("The REDCap version determination failed.  The error message was:\n",  kernel$raw_text)
   }

R/redcap-write-oneshot.R

@@ -65,20 +65,19 @@
 
 redcap_write_oneshot <- function( ds, redcap_uri, token, verbose=TRUE, config_options=NULL ) {
   #TODO: automatically convert boolean/logical class to integer/bit class
-  csvElements <- NULL #This prevents the R CHECK NOTE: 'No visible binding for global variable Note in R CMD check';  Also see  if( getRversion() >= "2.15.1" )    utils::globalVariables(names=c("csvElements")) #http://stackoverflow.com/questions/8096313/no-visible-binding-for-global-variable-note-in-r-cmd-check; http://stackoverflow.com/questions/9439256/how-can-i-handle-r-cmd-check-no-visible-binding-for-global-variable-notes-when
+  csv_elements <- NULL #This prevents the R CHECK NOTE: 'No visible binding for global variable Note in R CMD check';  Also see  if( getRversion() >= "2.15.1" )    utils::globalVariables(names=c("csv_elements")) #http://stackoverflow.com/questions/8096313/no-visible-binding-for-global-variable-note-in-r-cmd-check; http://stackoverflow.com/questions/9439256/how-can-i-handle-r-cmd-check-no-visible-binding-for-global-variable-notes-when
 
-  start_time <- Sys.time()
   checkmate::assert_character(redcap_uri                , any.missing=F, len=1, pattern="^.{1,}$")
   checkmate::assert_character(token                     , any.missing=F, len=1, pattern="^.{1,}$")
 
   token <- sanitize_token(token)
 
-  con   <-  base::textConnection(object='csvElements', open='w', local=TRUE)
+  con   <-  base::textConnection(object='csv_elements', open='w', local=TRUE)
   utils::write.csv(ds, con, row.names = FALSE, na="")
   close(con)
 
-  csv <- paste(csvElements, collapse="\n")
-  rm(csvElements, con)
+  csv <- paste(csv_elements, collapse="\n")
+  rm(csv_elements, con)
 
   post_body <- list(
     token     = token,
@@ -96,17 +95,6 @@ redcap_write_oneshot <- function( ds, redcap_uri, token, verbose=TRUE, config_op
   # This is the important line that communicates with the REDCap server.
   kernel <- kernel_api(redcap_uri, post_body, config_options)
 
-  # result <- httr::POST(
-  #   url    = redcap_uri,
-  #   body   = post_body,
-  #   config = config_options
-  # )
-  #
-  # status_code       <- result$status_code
-  # raw_text          <- httr::content(result, type="text")
-  # elapsed_seconds   <- as.numeric(difftime(Sys.time(), start_time, units="secs"))
-  # success           <- (status_code == 200L)
-
   if( kernel$success ) {
     elements               <- unlist(strsplit(kernel$raw_text, split="\\n"))
     affected_ids           <- as.character(elements[-1])

R/redcap-write.R

@@ -74,12 +74,13 @@
 #' }
 redcap_write <- function(
   ds_to_write,
-  batch_size = 100L,
-  interbatch_delay = 0.5,
-  continue_on_error = FALSE,
+  batch_size          = 100L,
+  interbatch_delay    = 0.5,
+  continue_on_error   = FALSE,
   redcap_uri,
   token,
-  verbose = TRUE, config_options = NULL
+  verbose             = TRUE,
+  config_options      = NULL
 ) {
 
   start_time <- base::Sys.time()