README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# roam <img src="man/figures/logo.svg" align="right" height="139" />

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/roam)](https://CRAN.R-project.org/package=roam)
[![R-CMD-check](https://github.com/finyang/roam/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/finyang/roam/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

The goal of roam is to ...

1. Allow 'regular looking' R objects in packages to exceed the 5MB limit.
2. Support updating of datasets without updating packages by using functions that pull from remote resources.
3. Make it easy for packages to include these 'roaming' datasets.

## Installation

You can install the **stable** version from
[CRAN](https://cran.r-project.org/package=roam).

``` r
install.packages("roam")
```

You can install the **development** version from
[Github](https://github.com/FinYang/roam)

``` r
# install.packages("remotes")
remotes::install_github("FinYang/roam")
```

## Example

```{r example}
#| eval: false
library(roam)
bee <- new_roam(
  "roam", "bee", 
  function(version) 
    read.csv(
      "https://raw.githubusercontent.com/finyang/roam/master/demo/bee_colonies.csv"))


roam_activate(bee)

head(bee)
#> The roam data object "bee" in package roam does not exist locally
#> Would you like to download and cache it? (Yes/no/cancel) 
```

*The data is downloaded to a local cache using {rappdirs}, then returned as the data itself*

```{r}
#| include: false
#| echo: false
library(roam)
bee <- new_roam(
  "roam", "bee", 
  function(version) 
    read.csv(
      "https://raw.githubusercontent.com/finyang/roam/master/demo/bee_colonies.csv"))

roam_activate(bee)
roam_update(bee)
```


```{r}
#| echo: false
head(roam_update(bee))
```

### Accessing cached data

```{r}
head(bee)
```

### Updating cached data

```{r}
head(roam_update(bee))
```

### Deleting cached data

```{r}
roam_delete(bee)
```