Conceptual

When we created styler, it was a design principle to make it non-invasive, flexible and maintainable. The downside of this is that it is slow. The natural solution to this problem is caching. styler does not store any formatted code anywhere, it simply hashes the input and checks if this was the output of formatting before. If so, it returns the code. the package implements caching on two layers. Whole input and by top-level expression. Let’s say you want to style the below text:

1 + 1
a <- 3

If it was previously styled, the second time you style it, it will just return the input immediately. If you change the code to

1 + 1
a = 3

the first layer of the cache (the whole input) won’t be used, because the text input is not the same. However, the first expression 1 + 1 is the same, so it will use the cache for this expression and only run a=3 through the full processing engine. The bigger the cached expressions, the more this matters. And typically, you have

# in package code
f <- function() {
  # long function declaration here
}

# in analysis code
data %>%
  long() %>%
  pipe(expressions) %>%
  here(all = chained) 

These are two top-level expressions (if you ignore the two top-level comments). If you style your code regularly and you do only modify a subset of all top-level expressions without touching the majority of them, you will benefit a lot from caching. In particular when you run functions like style_pkg(), because all unmodified files will pass through very quickly.

Usage

Caching is enabled by default and you will be asked once to let the caching backend of styler (R.cache) create a cache permanent directory. This will enable caching across R sessions, not just within a session. The cache is shared across all APIs (style_text(), style_file(), style_dir(), style_pkg(), Addin). You can easily check details of the cache as follows:

cache_info()
## Size:        0 bytes (0 cached expressions)
## Last modified:   NA
## Created: 2020-03-14 14:53:23
## Location:    /tmp/RtmpyGP7aD/.Rcache/styler/1.3.2
## Activated:   TRUE

There are utilities to deactivate the cache with cache_deactivate() or clear it with cache_clear(). You can also use use multiple caches, see ?cache_activate(). Caches are version and style guide dependent, so when you update the styler package in the future, the cache will be rebuilt as you go. We wanted to make sure the cache does not grow large on your disk, which is the case with the above described approach that does not store any code. We simply hash the styled code and create an empty file with the hash as a name. This literally takes zero bytes on disk, plus the size of the inode (which is negligible).

If you want use styler in a CI/CD workflow or non-interactively, please see ?caching for details.