Fix whitespace/precedence inconsistencies; add print/fast parity

- Trim whitespace consistently with Python/Stata; blank tokens dropped and an
  empty/all-blank value becomes NULL ("no filter") instead of erroring (#4)
- Validate an invalid version before honoring cite (#7)
- Add print_option (APA citation) for parity with Python/Stata
- Add fast (local dataset cache under R_user_dir) for parity with Python/Stata

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Yicheng-Zhao1999

R/gmd.R

@@ -30,6 +30,13 @@
 #'   with \code{variables} to load only specific variables from that source.
 #' @param cite A string. \code{"load"} to load the full citation list as a dataframe,
 #'   or a specific source key (e.g., \code{"GMD"}) to display its BibTeX citation.
+#' @param print_option A string, \code{"GMD"} or \code{"Stata"} (case-insensitive),
+#'   to print the corresponding APA citation and return invisibly. Parity with the
+#'   Python/Stata \code{print} option.
+#' @param fast Logical (or the string \code{"yes"}). If \code{TRUE}, save the
+#'   downloaded dataset to a local cache so subsequent calls load it from disk
+#'   instead of re-downloading. Once cached, the file is reused automatically.
+#'   Parity with the Python/Stata \code{fast} option.
 #' @return A dataframe containing the requested macroeconomic data.
 #'
 #' @examples
@@ -94,12 +101,30 @@
 #' @export
 gmd <- function(variables = NULL, country = NULL, version = NULL,
                 raw = FALSE, iso = FALSE, vars = FALSE,
-                sources = NULL, cite = NULL,
-                start_year = NULL, end_year = NULL) {
+                sources = NULL, cite = NULL, print_option = NULL,
+                fast = FALSE, start_year = NULL, end_year = NULL) {
 
   base_url <- "https://gmd-releases.s3.ap-southeast-2.amazonaws.com/data"
   ID_COLS <- c("ISO3", "year", "countryname", "id")
 
+  # [print] Print the APA citation and return early \u2014 parity with Python/Stata
+  # (Python: print_option / Stata: print()). Case-insensitive; invalid -> error.
+  if (!is.null(print_option)) {
+    if (length(print_option) != 1 || is.na(print_option)) {
+      stop("`print_option` must be a single non-NA value ('GMD' or 'Stata').")
+    }
+    opt <- tolower(trimws(print_option))
+    if (opt == "gmd") {
+      message("M\u00fcller, K., Xu, C., Lehbib, M., & Chen, Z. (2025). The Global Macro Database: A New International Macroeconomic Dataset (NBER Working Paper No. 33714).")
+      return(invisible(NULL))
+    }
+    if (opt == "stata") {
+      message("Lehbib, M. & M\u00fcller, K. (2025). gmd: The Easy Way to Access the World's Most Comprehensive Macroeconomic Database. Working Paper.")
+      return(invisible(NULL))
+    }
+    stop("Invalid option for print(). valid arguments are 'GMD' or 'Stata'.")
+  }
+
   message("Global Macro Database by M\u00fcller, Xu, Lehbib, and Chen (2025)")
   message("Website: https://www.globalmacrodata.com")
   message("")
@@ -110,11 +135,23 @@ gmd <- function(variables = NULL, country = NULL, version = NULL,
       (!is.character(version) || length(version) != 1 || is.na(version))) {
     stop("`version` must be a single non-NA character string, or NULL.")
   }
-  if (!is.null(country) && length(country) == 0) {
-    stop("`country` must contain at least one ISO3 code, or be NULL.")
+
+  # [#4] Trim surrounding whitespace consistently with Python/Stata. Blank tokens
+  # are dropped; an empty/all-blank value becomes NULL ("no filter") instead of
+  # raising an error, matching Python's lenient handling.
+  if (!is.null(version)) {
+    version <- trimws(version)
+    if (version == "") version <- NULL
+  }
+  if (!is.null(country)) {
+    country <- trimws(country)
+    country <- country[country != ""]
+    if (length(country) == 0) country <- NULL
   }
-  if (!is.null(variables) && length(variables) == 0) {
-    stop("`variables` must contain at least one variable name, or be NULL.")
+  if (!is.null(variables)) {
+    variables <- trimws(variables)
+    variables <- variables[variables != ""]
+    if (length(variables) == 0) variables <- NULL
   }
 
   validate_year <- function(value, name) {
@@ -278,6 +315,15 @@ gmd <- function(variables = NULL, country = NULL, version = NULL,
     if (length(cite) != 1 || is.na(cite)) {
       stop("`cite` must be a single non-NA source key (or 'load').")
     }
+    # [#7] Validate an explicit version before honoring cite, so an invalid
+    # version errors regardless of cite (matches Python/Stata precedence).
+    if (!is.null(version) && !tolower(version) %in% c("list", "current")) {
+      .v_avail <- sort(unique(.gmd_load_versions_df()$versions), decreasing = TRUE)
+      if (!version %in% .v_avail) {
+        stop(sprintf("Error: %s is not valid\nAvailable versions are: %s\nThe current version is: %s",
+                    version, paste(sort(.v_avail), collapse = ", "), .v_avail[1]))
+      }
+    }
     cite_resp <- .gmd_safe_get(paste0(base_url, "/helpers/bib_dataframe.csv"))
     if (is.null(cite_resp)) {
       stop("Unable to import the list of sources to cite. Check internet connection.")
@@ -472,11 +518,28 @@ gmd <- function(variables = NULL, country = NULL, version = NULL,
   # Main dataset
   # ============================================================================
   require_haven()
-  main_resp <- .gmd_safe_get(data_url)
-  if (is.null(main_resp)) {
-    stop(sprintf("Error: Data file not found at %s\nCheck internet connection.", data_url))
+  # [fast] Optional local cache of the dataset for faster reloads / offline use
+  # (parity with Python/Stata `fast`). Once cached, the file is reused automatically.
+  use_fast <- isTRUE(fast) || (is.character(fast) && tolower(trimws(fast)) == "yes")
+  cache_dir <- tools::R_user_dir("globalmacrodata", "cache")
+  cache_file <- file.path(cache_dir, sprintf("GMD_%s.dta", current_version))
+  if (file.exists(cache_file)) {
+    df <- haven::read_dta(cache_file)
+  } else {
+    main_resp <- .gmd_safe_get(data_url)
+    if (is.null(main_resp)) {
+      stop(sprintf("Error: Data file not found at %s\nCheck internet connection.", data_url))
+    }
+    raw_bytes <- httr2::resp_body_raw(main_resp)
+    df <- haven::read_dta(raw_bytes)
+    if (use_fast) {
+      if (!dir.exists(cache_dir)) dir.create(cache_dir, recursive = TRUE, showWarnings = FALSE)
+      # Save the original .dta bytes verbatim so a cached read is byte-identical to a
+      # fresh download (haven::write_dta would drop dataset-level notes attributes).
+      writeBin(raw_bytes, cache_file)
+      message(sprintf("GMD dataset loaded and saved locally in %s.", cache_dir))
+    }
   }
-  df <- haven::read_dta(httr2::resp_body_raw(main_resp))
 
   if (!is.null(country)) {
     country <- validate_country(country, get_country_mapping())