This project follows the contributing recommendations outlined by saamwerk. In particular, issues labelled with Status: Postponed are closed even if they are not resolved.
precommit::use_precommit() to make sure the hooks are activated in your local styler clone. If you skip a hook, describe why in the PR.Read the vignettes. If you are done, come back here.
devtools::load_all()
debug(style_text)
style_text("call(1, 2 + 1)")Go broad before you go deep. Before going into the very deep layers of function calls of style_text(), try to understand that style_text() consists of a few function calls only. Go into each of them and try to understand one layer deep. That is, try to understand what make_transformer() does by reading the names of the functions that get called, the name of the objects that are created by assigning the output of these function calls. Before looking into a functions source code, look at the documentation for that function. All internal important functions are documented and documentation is available also for unexported objects via ? (if you did devtools::load_all()). Then, go into parse_transform_serialize(), and so on.
To understand the most fundamental operation in styler, the manipulation of the columns related to spacing and line break information, pick a rule from R/rules-*.R (e.g. R/rules-spacing), add a break point to a rule, and style a string where you think this rule will be active. Then, see what happens and how this rule is applied on each level of nesting.
There are multiple packages that can be used to analyze a code base:
Check out the links above to see how the tools listed could help you understanding styler.
The source code is organized as follows:
| File | Description |
|---|---|
| addins.R | ui and helpers for the Addins of styler. |
| communicate.R | function to communicate to the user via the console. |
| compat-dplyr.R | compatibility functions. Since styler does not depend on dplyr, we define the dplyr functions ourself. |
| compat-tidyr.R | compatibility functions. Since styler does not depend on tidy, we define the tidyr functions ourself. |
| expr-is.R | Functions to check whether an expression matches a predicate (e.g. whether it is a function call, a curly brace expression etc.). |
| indent.R | Computation of whether indention is needed (needs_indention()), if so which indices are indented and how indention is it is triggered. |
| initialize.R | initializer called with the visitor at each nest. |
| nest.R | converting from a text representation into a flat and then into a nested parse table representation. |
| nested-to-tree.R | utilities to create a tree representation from text (after text was converted into a nested parse table). |
| parse.R | parse text into parse table, minor token manipulation, verification of parsed objects. |
| reindent.R | Deals with token-dependent indention and re-indention, opposed to indent.R where all indention is token independent (i.e. a brace just adds one level of indention, whereas in function declaration headers (if mutli-line), indention depends on token position of “function”). |
| relevel.R | Reorganizing the nested parse table, namely relocates expressions on both sides of “%>%” to the same nest. |
| rules-line-break.R, rules-other.R, rules-replacement.R, rules-spacing.R | transformer rules |
| serialize.R | converts flattened parse table into text representation. Complement operation to the functions in nest.R |
| set-assert-args.R | Assertion and setting of arguments. |
| style-guides.R | How to create style guide objects from transformers. |
| styler.R | General package information. |
| testing.R | function used for testing. |
| token-create.R | Utilities for creating tokens, mostly to insert braces around mutli-line if statements. |
| token-define.R | Defines which tokens belong to which group. |
| transform-code.R, transform-files.R | Transformation of code for APIs that manipulate files (e.g. style_file()). |
| ui.R | User interaces. Top-level functions for styling. |
| unindent.R | Certain tokens cause unindention, e.g. closing braces. |
| utils.R | low-level general purpose utilities. |
| vertical.R | S3 class for pretty printing of styled code. |
| visit.R | Functions that apply functions to each level of nesting, either inside out or outside in. |
| zzz.R | backport imports. |
You may have problems understanding some code because documentation is minimal, some code / functions seem to solve problems you don’t understand or handle cases that seem unreasonable or otherwise incomprehensible. You can resort to the following strategies:
$ git blame to see where changes were introduced. Look at the commit message, check changes that were made to the code in the same commit. If you are using the GUI of GitHub, you can easily obtain more contextual information such as the pull request with which a change was introduced. Often, functionality was introduced with testing. So, you can easily see which new tests are related to the new functionality. You can remove the changes in the source code and re-run the tests and see what fails and why.test_collection() should be used.FIXME.$ git blame to track when changes were introduced and find the corresponding pull request and associated issues to understand the thought process that lead to a change in the source code. This also implies that issues and / or pull request contain verbose explanation of problems and solutions provided.This project follows the tidyverse style guide. If we refer to specific variables / values etc. in the following sections, you can use RStudio’s full text search to find where remove_line_break_before_round_closing_after_curly() is declared or called.
remove_line_break_before_round_closing_after_curly().utils.R.TRUE or FALSE, i.e. we don’t encourage if (length(x)), but rather if (length(x) > 0L).purrr::map() and friends when possible and prefer them over R base counterparts like base::lapply().Functions that return Boolean values or variables that hold Boolean values are to be prefixed with is or has. For example, is_rmd_file(path) is a function that returns TRUE if path is the path to a .Rmd file and FALSE otherwise.
Vectors that hold indices are often suffixed with idx. For example, else_idx indicates for every row in a parse table whether it contains an else token.
The use of closures is discouraged. We prefer to prefill a template function with purrr::partial().
We have a testing framework powered by test_collection(). Essentially, there is an *-in.R file and a *-out.R file. The *-in.R file is the input that is transformed and - if it matches the *-out.R file, the test will pass. You can create an *-in.R file, run devtools::test(f = "[your file]") and an *-out.R file is generated. If the file matches your expectation, you can commit it. Note that files are overwritten and version control should be used to track failed tests. The files are placed in tests/testthat under the category they fit. Please have a look at the documentation for test_collection() and see other unit tests.