#346 added single docs page for all hoardr caching objects, mention t…

…hose in their associated fxn man files

NAMESPACE

@@ -16,17 +16,20 @@ S3method(type_summ,logical)
 S3method(type_summ,matrix)
 S3method(type_summ,numeric)
 export(arc2)
+export(arc2_cache)
 export(argo)
 export(argo_buoy_files)
 export(argo_files)
 export(argo_plan)
 export(argo_qwmo)
 export(argo_search)
 export(bsw)
+export(bsw_cache)
 export(buoy)
 export(buoy_stations)
 export(buoys)
 export(coops_search)
+export(cpc_cache)
 export(cpc_prcp)
 export(erddap_clear_cache)
 export(erddap_data)
@@ -63,6 +66,7 @@ export(is.ncdc_locs)
 export(is.ncdc_locs_cats)
 export(is.ncdc_stations)
 export(isd)
+export(isd_cache)
 export(isd_read)
 export(isd_stations)
 export(isd_stations_search)

R/arc2.R

@@ -5,6 +5,7 @@
 #' @param ... curl options passed on to [crul::verb-GET]
 #' @references docs:
 #' <ftp://ftp.cpc.ncep.noaa.gov/fews/fewsdata/africa/arc2/ARC2_readme.txt>
+#' @note See [arc2_cache] for managing cached files
 #' @return a tibble/data.frame with columns:
 #'
 #' - lon - longitude

R/bsw.R

@@ -22,7 +22,7 @@
 #' 
 #' Uses `ncdf4` under the hood to read NetCDF files
 #' 
-#' Use `bsw_cache` object to manage cached files.
+#' @note See [bsw_cache] for managing cached files
 #' 
 #' @section Citing NOAA and BSW data:
 #' Message from NOAA: "We also ask you to acknowledge us in your use of the 

R/cpc.R

@@ -7,6 +7,7 @@
 #' values (values in the `precip` column in the output data.frame). 
 #' default: `FALSE`
 #' @param ... curl options passed on to [crul::verb-GET]
+#' @note See [cpc_cache] for managing cached files
 #' @return a data.frame, with columns:
 #'
 #' - lon - longitude (0 to 360)

R/isd.R

@@ -65,20 +65,7 @@
 #' file does not exist on NOAA's ftp servers. If your internet is down,
 #' you'll get a different error.
 #'
-#' @section File storage:
-#' We use \pkg{rappdirs} to store files, see
-#' [rappdirs::user_cache_dir()] for how we determine the directory on
-#' your machine to save files to, and run
-#' `rappdirs::user_cache_dir("rnoaa/isd")` to get that directory.
-#' 
-#' Note that cached files will continue to be used until they are deleted.
-#' It's possible to run into problems when changes happen in your R 
-#' setup. For example, at least one user reported changing versions
-#' of this package and running into problems because a cached data
-#' file from a previous version of rnoaa did not work with the newer
-#' version of rnoaa. You may want to occassionally delete all cached
-#' files.
-#'
+#' @note See [isd_cache] for managing cached files
 #' @examples \dontrun{
 #' # Get station table
 #' (stations <- isd_stations())

R/lcd.R

@@ -8,7 +8,7 @@
 #' @param ... curl options passed on to [crul::verb-GET]
 #' @return a data.frame, with many columns, and variable rows
 #' depending on how frequently data was collected in the given year
-#' @seealso lcd_cache
+#' @note See [lcd_cache] for managing cached files
 #' @references
 #' Docs: 
 #' <https://www.ncei.noaa.gov/data/local-climatological-data/doc/LCD_documentation.pdf>
@@ -98,45 +98,3 @@ lcd_base <- function() {
 lcd_key <- function(station, year) {
   file.path(lcd_base(), year, paste0(station, ".csv"))
 }
-
-#' @title lcd_cache
-#' @description Manage the `lcd()` cache
-#' @export
-#' @details The cache directory for `lcd()` is
-#' `paste0(rappdirs::user_cache_dir(), "/R/noaa_lcd")`, but you can set
-#' your own path using `cache_path_set()`
-#'
-#' `cache_delete` only accepts 1 file name, while
-#' `cache_delete_all` doesn't accept any names, but deletes all files.
-#' For deleting many specific files, use `cache_delete` in a [lapply()]
-#' type call
-#'
-#' @section Useful user functions:
-#'
-#' - `lcd_cache$cache_path_get()` get cache path
-#' - `lcd_cache$cache_path_set()` set cache path
-#' - `lcd_cache$list()` returns a character vector of full path file names
-#' - `lcd_cache$files()` returns file objects with metadata
-#' - `lcd_cache$details()` returns files with details
-#' - `lcd_cache$delete()` delete specific files
-#' - `lcd_cache$delete_all()` delete all files, returns nothing
-#'
-#' @examples \dontrun{
-#' lcd_cache
-#'
-#' # list files in cache
-#' lcd_cache$list()
-#'
-#' # delete certain database files
-#' # lcd_cache$delete("file path")
-#' # lcd_cache$list()
-#'
-#' # delete all files in cache
-#' # lcd_cache$delete_all()
-#' # lcd_cache$list()
-#'
-#' # set a different cache path from the default
-#' # lcd_cache$cache_path_set(full_path = file.path(tempdir(), "foo_bar"))
-#' # lcd_cache
-#' }
-"lcd_cache"

R/onload.R

@@ -2,6 +2,7 @@ cpc_cache <- NULL
 arc2_cache <- NULL
 lcd_cache <- NULL
 bsw_cache <- NULL
+isd_cache <- NULL
 
 .onLoad <- function(libname, pkgname){
   x <- hoardr::hoard()
@@ -19,4 +20,8 @@ bsw_cache <- NULL
   m <- hoardr::hoard()
   m$cache_path_set("noaa_bsw")
   bsw_cache <<- m
+
+  g <- hoardr::hoard()
+  g$cache_path_set("noaa_isd")
+  isd_cache <<- g
 }

R/rnoaa_caching.R

@@ -0,0 +1,72 @@
+#' @title rnoaa caching
+#' @description Manage data caches
+#' @name rnoaa_caching
+#' @details To get the cache directory for a data source, see the method
+#' `x$cache_path_get()`
+#'
+#' `cache_delete` only accepts 1 file name, while
+#' `cache_delete_all` doesn't accept any names, but deletes all files.
+#' For deleting many specific files, use `cache_delete` in a [lapply()]
+#' type call
+#' 
+#' Note that cached files will continue to be used until they are deleted.
+#' It's possible to run into problems when changes happen in your R 
+#' setup. For example, at least one user reported changing versions
+#' of this package and running into problems because a cached data
+#' file from a previous version of rnoaa did not work with the newer
+#' version of rnoaa. You should occassionally delete all cached files.
+#' 
+#' @seealso [rnoaa_options()] for managing whether you see messages
+#' about cached files when you request data
+#' 
+#' @section Useful user functions:
+#' 
+#' Assuming x is a `HoardClient` class object, e.g., `lcd_cache`
+#'
+#' - `x$cache_path_get()` get cache path
+#' - `x$cache_path_set()` set cache path
+#' - `x$list()` returns a character vector of full path file names
+#' - `x$files()` returns file objects with metadata
+#' - `x$details()` returns files with details
+#' - `x$delete()` delete specific files
+#' - `x$delete_all()` delete all files, returns nothing
+#' 
+#' @section Caching objects for each data source:
+#'
+#' - `isd()`: `isd_cache`
+#' - `cpc_prcp()`: `cpc_cache`
+#' - `arc2()`: `arc2_cache`
+#' - `lcd()`: `lcd_cache`
+#' - `bsw()`: `bsw_cache`
+#' 
+NULL
+
+#' @rdname rnoaa_caching
+#' @format NULL
+#' @usage NULL
+#' @export
+"isd_cache"
+
+#' @rdname rnoaa_caching
+#' @format NULL
+#' @usage NULL
+#' @export
+"cpc_cache"
+
+#' @rdname rnoaa_caching
+#' @format NULL
+#' @usage NULL
+#' @export
+"arc2_cache"
+
+#' @rdname rnoaa_caching
+#' @format NULL
+#' @usage NULL
+#' @export
+"lcd_cache"
+
+#' @rdname rnoaa_caching
+#' @format NULL
+#' @usage NULL
+#' @export
+"bsw_cache"

R/rnoaa_options.R

@@ -7,6 +7,7 @@ roenv$cache_messages <- TRUE
 #' on caching status for function calls that can cache data. default: `TRUE`
 #' @details rnoaa package level options; stored in an internal
 #' package environment `roenv`
+#' @seealso [rnoaa_caching] for managing cached files
 #' @examples \dontrun{
 #' rnoaa_options(cache_messages = FALSE)
 #' }