Get and set openFDA package-level options — openFDA

User-configurable options used by openFDA, which provide a mechanism for setting default behaviours.

Usage

openFDA_options(
  paging = NULL,
  paging_verbosity = NULL,
  handle_http_errors = NULL
)

current_openFDA_options()

Arguments

paging

A single string used to set the openFDA.paging option. The default, NULL, indicates that you don't want to change its value. The openFDA.paging option controls how openFDA() behaves when there are enough results that paging is required, and has the default value "ask". New values must be one of:

"ask" - openFDA() will warn you that pagination is required and ask if you want this to be done. Depending on user input, either a single httr2 response object or a list of httr2 response objects will be returned. This will throw an error if your R session is not in interactive mode. When s etting this option, the value must be one of:
"always" - openFDA() will always perform pagination. A list of httr2 responses will be returned when pagination occurs.
"never" - openFDA() will never perform pagination. Only the first httr2 response will be returned.

paging_verbosity

A single string used to set the openFDA.paging_verbosity option. The default, NULL, indicates that you don't want to change its value. The openFDA.paging_verbosity option controls whether openFDA() prints messages when paging is required, and has the default value "warn". New values must be one of:

"verbose" - If paging can be performed, print a message to the console, stating how many requests are required with a minimum estimate for the time this will take.
"quiet" - Print no messages to the console regarding paging.

handle_http_errors

A single string used to set the openFDA.handle_http_errors option. The default, NULL, indicates that you don't want to change its value. The openFDA.handle_http_errors option controls how openFDA() reacts when responses from the openFDA API have HTTP codes other than 200 OK, and has the default value "warn". New values must be one of:

"warn": If the returned HTTP code is not 200, issue a warning to the console and return the underlying httr2 response object.
"error": If the returned HTTP code is not 200, throw an (informative) error.
"silent": If the returned HTTP code is not 200, return the underlying httr2 response object without printing a warning.

Value

For openFDA_options() returns a named character vector with current option values. This will include the updated option values, if any have been set.

For current_openFDA_options(), returns a named character vector with the current values for each openFDA package-level option.

Examples

# Print current options by leaving all input args as `NULL`:
openFDA_options()
#> Current openFDA options:
#> • `openFDA.paging` = "ask"
#> • `openFDA.paging_verbosity` = "verbose"
#> • `openFDA.handle_http_errors` = "warn"
#> ℹ See `?openFDA_options()` for more information.

# Or specify some options to set these:
openFDA_options(paging = "never", handle_http_errors = "silent")
#> ! New option values set:
#> • "openFDA.paging" option set to "never" (was previously "ask") .
#> • "openFDA.handle_http_errors" option set to "silent" (was previously "warn") .
#> ℹ See `?openFDA_options()` for more information.

# Make sure to give valid option values
try(openFDA_options(paging = "bad-value"))
#> Error in openFDA_options(paging = "bad-value") : 
#>   ! You attempted to set bad option values:
#> • Bad "openFDA.paging" value. You tried to set it to "bad-value", but it must
#>   be one of "always", "ask" or "never".
#> ℹ See `?openFDA_options()` for more information.

# If you set an option using `options()` and it is not valid, you will
# invoke errors
try(
  rlang::with_options(openFDA.paging = "no", current_openFDA_options())
)
#> Error in current_openFDA_options() : 
#>   ! Invalid openFDA package-level option value detected.
#> • `openFDA.paging`: is "no", but must be one of "always", "ask" or "never".
#> ℹ Set a valid value for this option using `openFDA_options()`.