---
title: "Integrating into Your Package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Integrating into Your Package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The primary purpose of this package is for use within other packages. 
To use {dlr}, you most likely want to wrap some of the exported functions from this package.

## read_or_cache

The primary use for {dlr} is to download data to an app cache if that data does not already exist.
Wrap `read_or_cache` for any files you wish to cache. 

Tip: If you will allow users to download multiple files with different URLs, define the URLs as internal data.
That way you can edit all URLs in one location without having to search through multiple functions.
For example, in the example below, `.my_url` is an internal named list with the URLs of the files of interest.

```{r read_or_cache, eval = FALSE}
my_big_dataset <- function(variant = c("small", "medium", "big")) {
  # Returns the result of downloading and then reading with read.csv.
  return(
    dlr::read_or_cache(
      source_path = .my_urls[[variant]],
      appname = "myPackage",
      process_f = read.csv
  )
}
```

## maybe_cache

An alternative pattern would be to allow users to download (or otherwise process) files which other functions in your package will load.
For example, perhaps you want to allow the user to download a large lookup table, which will then be used by default by the rest of the package.
The code to do so would look something like this:

```{r maybe_cache, eval = FALSE}
download_lookup <- function(variant = c("small", "medium", "big")) {
  # Returns the path to the processed file, rather than the contents of that
  # file.
  return(
    dlr::maybe_cache(
      source_path = .my_urls[[variant]],
      appname = "myPackage",
      process_f = read.csv
    )
  )
}
```

## app_cache_dir

If you want the user to be able to easily determine the location of the cache for your package (often useful even if you don't think it will be), provide a wrapper around `app_cache_dir`

```{r app_cache_dir, eval = FALSE}
myPackage_cache_dir <- function() {
  return(dlr::app_cache_dir(appname = "myPackage"))
}
```

## set_app_cache_dir

Users will have use cases you aren't prepared for, such as a strange file system or a shared cache directory specifically for your package. 
Allow them to set up such options with `set_app_cache_dir`.

```{r set_app_cache_dir, eval = FALSE}
set_myPackage_cache_dir <- function(cache_dir) {
  return(dlr::set_app_cache_dir(appname = "myPackage", cache_dir = cache_dir))
}
```