Skip to contents

pkgpins builds upon the pins package and strives to provide R package authors a simple and standardized way to cache results on the filesystem in a suitable user directory.

How it works

TODO: describe design (separate user-cache pins board per pkg and pkg version etc.)

Predefined parameter labels

There are two predefined parameter labels available in pkgsnip which fit typical use cases of this package. They are intended to be used in @param roxygen2 tags1 as follows:

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

The above inline R code will eventually result in this:

#' @param max_cache_age Duration after which cached results are refreshed (i.e. newly fetched). A valid [lubridate duration][lubridate::as.duration]. Use `Inf` to disable cache expiry. Only relevant if `use_cache = TRUE`.
#' @param use_cache Whether or not to return cached results if possible. If `FALSE`, results are always newly fetched regardless of `max_cache_age`.


To install the latest development version of pkgpins, run the following in R:

if (!("remotes" %in% rownames(installed.packages()))) {
  install.packages(pkgs = "remotes",
                   repos = "")

remotes::install_gitlab(repo = "")


The (function) reference is found here.


R Markdown format

This package’s source code is written in the R Markdown file format to facilitate practices commonly referred to as literate programming. It allows the actual code to be freely mixed with explanatory and supplementary information in expressive Markdown format instead of having to rely on # comments only.

All the .gen.R suffixed R source code found under R/ is generated from the respective R Markdown counterparts under Rmd/ using pkgpurl::purl_rmd()2. Always make changes only to the .Rmd files – never the .R files – and then run pkgpurl::purl_rmd() to regenerate the R source files.

Coding style

This package borrows a lot of the Tidyverse design philosophies. The R code adheres to the principles specified in the Tidyverse Design Guide wherever possible and is formatted according to the Tidyverse Style Guide (TSG) with the following exceptions:

  • Line width is limited to 160 characters, double the limit proposed by the TSG (80 characters is ridiculously little given today’s high-resolution wide screen monitors).

    Furthermore, the preferred style for breaking long lines differs. Instead of wrapping directly after an expression’s opening bracket as suggested by the TSG, we prefer two fewer line breaks and indent subsequent lines within the expression by its opening bracket:

    # TSG proposes this
      something = "that",
      requires = many,
      arguments = "some of which may be long"
    # we prefer this
    do_something_very_complicated(something = "that",
                                  requires = many,
                                  arguments = "some of which may be long")

    This results in less vertical and more horizontal spread of the code and better readability in pipes.

  • Usage of magrittr’s compound assignment pipe-operator %<>% is desirable3.

  • Usage of R’s right-hand assignment operator -> is not allowed4.

  • R source code is not split over several files as suggested by the TSG but instead is (as far as possible) kept in the single file Rmd/pkgpins.Rmd which is well-structured thanks to its Markdown support.

As far as possible, these deviations from the TSG plus some additional restrictions are formally specified in the lintr configuration file .lintr, so lintr can be used right away to check for formatting issues:


See also

  • R packages that provide a memoization infrastructure. Memoization is suited best for caching 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 R package storr that acts as a simple object cacher supporting various storage back ends. Notable is the thor back end that combines in-memory-mapping via LMDB with on-disk caching.