Export and modify gm_default_email()

* Export it, because appears as a default in gm_auth().
* If GMAILR_EMAIL does not exist, fall back to gargle::gargle_oauth_email(). If nothing else, this makes lots of gargle documentation much more true and relevant to gmailr.
* Create a new help topic for env vars that affect gmailr. This is going to gain more before we're done.
* Test it.

NAMESPACE

@@ -66,6 +66,7 @@ export(gm_create_draft)
 export(gm_create_label)
 export(gm_date)
 export(gm_deauth)
+export(gm_default_email)
 export(gm_delete_draft)
 export(gm_delete_label)
 export(gm_delete_message)

R/gm_auth.R

@@ -88,14 +88,6 @@ gm_auth <- function(email = gm_default_email(),
   invisible()
 }
 
-gm_default_email <- function() {
-  user <- Sys.getenv("GMAILR_EMAIL")
-  if (nzchar(user)) {
-    return(user)
-  }
-  NULL
-}
-
 #' Clear current token
 #'
 #' @eval gargle:::PREFIX_deauth_description_no_api_key(gargle_lookup_table)

R/gmailr-package.R

@@ -11,3 +11,30 @@
 #' @importFrom lifecycle deprecated
 ## usethis namespace: end
 NULL
+
+#' Configuring gmailr
+#'
+#' gmailr can be configured with various environment variables. Since gmailr
+#' uses the gargle package to handle auth, gargle's configuration is also
+#' relevant, which is mostly accomplished through [options and associated
+#' accessor functions][gargle::gargle_options].
+#'
+#' @name gmailr_configuration
+NULL
+
+#' @rdname gmailr_configuration
+#' @export
+#' @section `gm_default_email()`:
+
+#' `gm_default_email()` returns the environment variable `GMAILR_EMAIL`, if it
+#' exists, and [gargle::gargle_oauth_email()], otherwise.
+#' @family auth functions
+gm_default_email <- function() {
+  user <- Sys.getenv("GMAILR_EMAIL")
+  if (nzchar(user)) {
+    user
+  } else {
+    gargle::gargle_oauth_email()
+  }
+}
+

tests/testthat/test-gmailr-package.R

@@ -0,0 +1,19 @@
+test_that("gm_default_email() transmits GMAILR_EMAIL", {
+  withr::local_envvar(GMAILR_EMAIL = "jenny@example.com")
+  expect_equal(gm_default_email(), "jenny@example.com")
+})
+
+test_that("gm_default_email() falls back to gargle::gargle_oauth_email()", {
+  # unset GMAILR_EMAIL
+  withr::local_envvar(GMAILR_EMAIL = NA)
+  expect_equal(Sys.getenv("GMAILR_EMAIL"), "")
+
+  withr::local_options(gargle_oauth_email = NULL)
+  expect_null(gm_default_email())
+
+  withr::local_options(gargle_oauth_email = "*@example.com")
+  expect_equal(gm_default_email(), "*@example.com")
+
+  withr::local_options(gargle_oauth_email = TRUE)
+  expect_true(gm_default_email())
+})