Introduction

Welcome to the website of the Google Summer of Code 2017 project Non-invasive source code formatting, a source code formatter for the R language.

Over the course of three months, Lorenz Walthert mentored by Kirill Müller and Yihui Xie, worked on the R package styler, which evolved from a proof of concept to a ready-for-production source code formatter. Because it is so exciting and pictures say more than 1000 words, we just want to show you how it works.

You can install the package from GitHub:

# install.packages("remotes")
remotes::install_github("krlmlr/styler")

Functionality

The package can style text, single files, packages and entire R source trees with the following functions:

  • style_text() styles a character vector.
  • style_file() styles a single .R file.
  • style_dir() styles all .R files in a directory.
  • style_pkg() styles the source files of an R package.
  • An RStudio Addin that styles the active file .R file, the current package or the highlighted code.

Mechanics

In brief, styler works as follows:

  1. Create a abstract syntax tree (AST) from utils::getParseData() that contains positional information of every token. We call this a nested parse table.
  2. Apply transformer functions at each level of the nested parse table. In particular, modify information about the position of the token.
  3. Serialize the nested parse table, that is, extract the terminal tokens from the nested parse table and add spaces and line breaks between them as specified in the nested parse table.

A style guide applied to code is hence just a set of transformer functions applied to each level of nesting. The main goal of this GSOC project was to provide infrastructure that allows performing the above steps and implementing one particular style guide: The tidyverse style guide. However, since technically speaking, the style guide is just a set of transformer functions, everybody can implement a style guide. There is a vignette that describes how to do that with an example.

Further Resources

You can find out more about the package by checking out