eia_data() refactor: dynamic error handling, forced input format requirements, and additional unit testing

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: eia
 Title: API Wrapper for 'US Energy Information Administration' Open Data
-Version: 0.4.0
+Version: 0.4.1
 Authors@R: 
     c(person(
         given = "Matthew",

NEWS.md

@@ -1,8 +1,14 @@
 # eia 0.4.1
 
-* Added dynamic error handling to `eia_data()` via metadata layer conditioned on
-new function argument `check_metadata`.
-
+* Re-factor of `eia_data()`:
+  * Added dynamic error handling via metadata layer conditioned on new function argument `check_metadata`.
+  * Forced `start` and `end` input values to character.
+  * Forced `length` and `offset` input values to numeric.
+  * Augmented `sort` functionality to now handle multiple, varying "asc"/"desc" inputs 
+  to `order` as a list, rather than just one value of "asc" or "desc" applied to all
+  specified columns.
+  * Improved error messaging with `check_metadata = TRUE` to more closely resemble
+  those provided by the API (i.e. with `check_metadata = FALSE`).
 
 # eia 0.4.0
 

R/data.R

@@ -6,6 +6,14 @@
 #' input values for each of these arguments, use the specific ID labels
 #' as provided by `eia_metadata()`.
 #'
+#' The use of `start` and `end` require some input to `freq`.
+#' By default (`check_metadata = FALSE`), the resulting data will match the
+#' temporal resolution provided to `freq`, however, `check_metadata = TRUE` applies
+#' further restrictions such that the format of values provided to `start`/`end` must match
+#' that of `freq`. Furthermore, regardless of the input format provided to `start`/`end`,
+#' the resulting data will always match the specification of `freq`. And lastly,
+#' regardless of chosen format, `end` must be strictly greater than `start` to return data.
+#'
 #' By default, additional processing is done to return a list containing tibble data frames.
 #' Set `tidy = FALSE` to return only the initial list result of `jsonlite::fromJSON`.
 #' Set `tidy = NA` to return the original JSON as a character string.
@@ -20,8 +28,7 @@
 #' @param data character or `NULL`, see details.
 #' @param facets character list or `NULL`, see details.
 #' @param freq character or `NULL`, see details.
-#' @param start,end character, integer or `NULL`, must match format of default or supplied
-#' `freq`; e.g. if `freq = "yearly"`, then format must be `YYYY`.
+#' @param start,end character or `NULL`, see details.
 #' @param sort named list of two.
 #'   * `cols`: list column names on which to sort.
 #'   * `order`: `"asc"` or `"desc"` for ascending or descending, respectively.
@@ -71,7 +78,7 @@ eia_data <- function(dir,
     warning(wrngs, "\nTotal available rows: ", r$response$total, call. = FALSE)
   } else {
     if (r$response$total == 0)
-      stop("No data available - check inputs.", call. = FALSE)
+      stop("No data available - check temporal inputs.", call. = FALSE)
     if (nrow(r$response$data) != r$response$total)
       warning("Rows returned: ", nrow(r$response$data), "\nRows available: ", r$response$total, call. = FALSE)
   }
@@ -153,6 +160,8 @@ eia_data <- function(dir,
 # Start input formatting and validation
 .start_specs <- function(start, freq){
   if(!is.null(start)){
+    if(!is.character(start))
+      stop("'start' must be a character string of length 1.", call. = FALSE)
     if(is.null(freq))
       stop("'start' requires 'freq' be non-NULL.", call. = FALSE)
     paste0("&start=", start)
@@ -161,11 +170,13 @@ eia_data <- function(dir,
 
 .start_check <- function(start, freq, md_frq_tbl, mds, mde){
   if(!is.null(start)){
+    if(!is.character(start))
+      stop("'start' must be a character string of length 1.", call. = FALSE)
     if (is.null(freq))
       stop("'start' requires 'freq' be non-NULL.", call. = FALSE)
     fmt <- md_frq_tbl[md_frq_tbl$id == freq, ]$format
     if (nchar(start) != nchar(fmt))
-      stop("'start' must be a string of format: ", fmt, call. = FALSE)
+      stop("'start' must be a character string of format: ", fmt, call. = FALSE)
     if (start > mde)
       stop("'start' is beyond the end of available data.", call. = FALSE)
     if (start < mds)
@@ -176,6 +187,8 @@ eia_data <- function(dir,
 # End input formatting and validation
 .end_specs <- function(end, freq){
   if (!is.null(end)){
+    if(!is.character(end))
+      stop("'end' must be a character string of length 1.", call. = FALSE)
     if(is.null(freq))
       stop("'end' requires 'freq' be non-NULL.", call. = FALSE)
     paste0("&end=", end)
@@ -184,11 +197,13 @@ eia_data <- function(dir,
 
 .end_check <- function(end, freq, md_frq_tbl, mde, mds){
   if (!is.null(end)){
+    if(!is.character(end))
+      stop("'end' must be a character string of length 1.", call. = FALSE)
     if (is.null(freq))
       stop("'end' requires 'freq' be non-NULL.", call. = FALSE)
     fmt <- md_frq_tbl[md_frq_tbl$id == freq, ]$format
     if (nchar(end) != nchar(fmt))
-      stop("'end' must be a string of format: ", fmt, call. = FALSE)
+      stop("'end' must be a character string of format: ", fmt, call. = FALSE)
     if (end < mds)
       stop("'end' is before the start of available data.", call. = FALSE)
     if (end > mde)
@@ -224,17 +239,17 @@ eia_data <- function(dir,
 # Length input formatting and validation
 .lng_specs <- function(length){
   if (!is.null(length)){
-    if (length > 5000 | length < 0)
-      stop("'length' must be a single value between 0 and 5000.", call. = FALSE)
+    if (!is.numeric(length) | length > 5000 | length < 0)
+      stop("'length' must be a numeric value between 0 and 5000.", call. = FALSE)
     paste0("&length=", length)
   }
 }
 
 # Offset input formatting and validation
 .ofs_specs <- function(offset){
   if (!is.null(offset)){
-    if (offset < 0)
-      stop("'offset' must be a single value greater than 0.", call. = FALSE)
+    if (!is.numeric(offset) | offset < 0)
+      stop("'offset' must be a numeric value greater than 0.", call. = FALSE)
     paste0("&offset=", offset)
   }
 }

codemeta.json

@@ -8,7 +8,7 @@
   "codeRepository": "https://github.com/ropensci/eia",
   "issueTracker": "https://github.com/ropensci/eia/issues",
   "license": "https://spdx.org/licenses/MIT",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",
@@ -229,5 +229,5 @@
     },
     "SystemRequirements": null
   },
-  "fileSize": "191.382KB"
+  "fileSize": "202.642KB"
 }

cran-comments.md

@@ -8,8 +8,7 @@
 
 ## Update release
 
-* This update includes a maintainer change/email address update.
-* Refactored package to work with newer version 2 of the US Energy Information Administration API.
+* Code updates and additional unit testing.
 
 ## R CMD check results
 

revdep/README.md

@@ -10,31 +10,30 @@
 |collate  |English_United States.utf8                                                           |
 |ctype    |English_United States.utf8                                                           |
 |tz       |America/Denver                                                                       |
-|date     |2023-10-31                                                                           |
+|date     |2023-11-17                                                                           |
 |rstudio  |2023.06.1+524 Mountain Hydrangea (desktop)                                           |
 |pandoc   |3.1.1 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown) |
 
 # Dependencies
 
 |package     |old   |new   |Δ  |
 |:-----------|:-----|:-----|:--|
-|eia         |0.3.7 |0.4.0 |*  |
+|eia         |0.4.0 |0.4.1 |*  |
 |askpass     |1.2.0 |1.2.0 |   |
 |cachem      |1.0.8 |1.0.8 |   |
 |cellranger  |1.1.0 |1.1.0 |   |
 |cli         |3.6.1 |3.6.1 |   |
 |cpp11       |0.4.6 |0.4.6 |   |
 |crayon      |1.5.2 |1.5.2 |   |
 |curl        |5.1.0 |5.1.0 |   |
-|dplyr       |1.1.3 |NA    |*  |
 |fansi       |1.0.5 |1.0.5 |   |
 |fastmap     |1.1.1 |1.1.1 |   |
 |generics    |0.1.3 |0.1.3 |   |
 |glue        |1.6.2 |1.6.2 |   |
 |hms         |1.1.3 |1.1.3 |   |
 |httr        |1.4.7 |1.4.7 |   |
 |jsonlite    |1.8.7 |1.8.7 |   |
-|lifecycle   |1.0.3 |1.0.3 |   |
+|lifecycle   |1.0.4 |1.0.4 |   |
 |lubridate   |1.9.3 |1.9.3 |   |
 |magrittr    |2.0.3 |2.0.3 |   |
 |memoise     |2.0.1 |2.0.1 |   |
@@ -48,14 +47,12 @@
 |R6          |2.5.1 |2.5.1 |   |
 |readxl      |1.4.3 |1.4.3 |   |
 |rematch     |2.0.0 |2.0.0 |   |
-|rlang       |1.1.1 |1.1.1 |   |
+|rlang       |1.1.2 |1.1.2 |   |
 |sys         |3.4.2 |3.4.2 |   |
 |tibble      |3.2.1 |3.2.1 |   |
-|tidyselect  |1.2.0 |NA    |*  |
 |timechange  |0.2.0 |0.2.0 |   |
 |utf8        |1.2.4 |1.2.4 |   |
 |vctrs       |0.6.4 |0.6.4 |   |
-|withr       |2.5.2 |NA    |*  |
 
 # Revdeps