caching: Remember the past to be quicker in the future

Description Setup Non-interactive use Invalidation Manage the cache Using a cache for styler in CI/CD

Description

Caching makes styler faster on repeated styling. It does not cache input but output code. That means if you style code that already complies to a style guide and you have previously styled that code, it will be quicker. Code is cached by expression and the cache is shared across all APIs (e.g. style_text() and Addin).

Setup

styler by default uses caching via the {R.cache} package. You will be asked to let it create a permanent cache on your file system that styler will use in case it is not set already up for another tool that uses {R.cache}. We encourage users to let {R.cache} create a permanent directory for caching because, otherwise, the cache is lost at restart of R.

Non-interactive use

Note that if you have never authorized {R.cache} to create the cache in a permanent directory, it will build the cache in a temporary directory. To create a permanent cache, just open an interactive R session and type cache_info(). You can see under Location: if a permanent directory is used and if not, {R.cache} will ask you to create one the first time you use {R.cache} in an R session.

Invalidation

The cache is specific to a version of styler by default, because different versions potentially format code differently. This means after upgrading styler or a style guide you use, the cache will be re-built.

Manage the cache

See cache_info(), cache_activate(), cache_clear() for utilities to manage the cache. Since we leverage {R.cache} to manage the cache, you can also use any {R.cache} functionality to manipulate it.

Using a cache for styler in CI/CD

If you want to set up caching in a CI/CD pipeline, we suggest to set the {R.cache} root path to a directory for which you have the cache enabled. The former can be done with R.cache::setCacheRootPath("/path/to/cache"), the latter can often be set in config files of CI/CD tools, e.g. see the the Travis documentation on caching.


krlmlr/styler documentation built on Oct. 25, 2020, 8:13 a.m.