README.Rmd

---
output: pal::gitlab_document
---

```{r}
#| label: init
#| include: false

knitr::opts_knit$set(root.dir = getwd())
```

# `r pal::desc_value("Package")`

`r paste0('[![CRAN Status](https://r-pkg.org/badges/version/', pal::desc_value(key = "Package"), ')](https://cran.r-project.org/package=', pal::desc_value(key = "Package"), '){.pkgdown-release}')`

`r pal::desc_value("Description") %>% stringr::str_replace(" (pins)( package) ", " [\\1](https://pins.rstudio.com/)\\2 ")`

```{r}
#| label: documentation
#| eval: !expr '!isTRUE(getOption("pal.build_readme.is_pkgdown"))'
#| results: asis
#| echo: false
pkgsnip::md_snip(id = "pkgdown_notice") %>%
  paste0("## Documentation\n\n",
         "[![Netlify Status](https://api.netlify.com/api/v1/badges/db173373-dd17-47ef-959b-695d01482a1d/deploy-status)]",
         "(https://app.netlify.com/sites/pkgpins-rpkg-dev/deploys)\n\n",
         .) %>%
  pal::cat_lines()
```

## How it works

TODO: describe design (separate [user-cache pins board](https://pins.rstudio.com/articles/boards-understanding.html) per pkg and pkg version etc.)

## Predefined parameter labels

There are two predefined parameter labels available in [pkgsnip](https://gitlab.com/rpkg.dev/pkgsnip) which fit typical use cases of this package. They are
intended to be used in `@param` [roxygen2 tags](https://roxygen2.r-lib.org/articles/rd.html#functions)[^1] as follows:

``` r
#' @param max_cache_age `r '\x60r pkgsnip::param_lbl("max_cache_age")\x60'`
#' @param use_cache `r '\x60r pkgsnip::param_lbl("use_cache")\x60'`
```

The above inline R code will eventually result in this:

``` r
#' @param max_cache_age `r pkgsnip::param_lbl("max_cache_age")`
#' @param use_cache `r pkgsnip::param_lbl("use_cache")`
```

[^1]: Support for dynamic inline R code was introduced in [roxygen2 7.1.0](https://www.tidyverse.org/blog/2020/03/roxygen2-7-1-0/).

## Installation

```{r}
#| label: install-snippet-dev
#| child: !expr pkgsnip::snip_path("installation-notice_dev-version_gitlab.Rmd")
```

```{r}
#| label: usage
#| eval: !expr isTRUE(getOption("pal.build_readme.is_pkgdown"))
#| results: asis
#| echo: false
pkgsnip::md_snip(id = "usage_notice") %>%
  paste0("## Usage\n\n", .) %>%
  pal::cat_lines()
```

## Development

### R Markdown format

```{r}
#| label: rmd-format
#| child: !expr pkgsnip::snip_path("rmd-package-notice.Rmd")
```

### Coding style

```{r}
#| label: coding-style
#| child: !expr pkgsnip::snip_path("coding-style-notice.Rmd")
```

## See also

-   R packages that provide a [memoization](http://en.wikipedia.org/wiki/Memoization) infrastructure. Memoization is suited best for caching [purely functional
    programming](https://en.wikipedia.org/wiki/Purely_functional_programming) results, i.e. caching functions that *always* return the same result for the same
    arguments (complete statelessness) -- something that's often not the case for functions accessing external APIs.

    There are at least two actively developed memoization packages:

    -   The Tidyverse-style [**memoise**](https://github.com/r-lib/memoise) package.
    -   The [**R.cache**](https://github.com/HenrikBengtsson/R.cache) package.

-   The R package [**storr**](https://richfitz.github.io/storr/) that acts as a simple object cacher supporting various [storage back
    ends](https://richfitz.github.io/storr/articles/storr.html#supported-backends). Notable is the [**thor**](https://richfitz.github.io/thor/index.html) back
    end that combines in-memory-mapping via [LMDB](https://symas.com/lmdb/) with on-disk caching.