forked from r-lib/styler
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
188 lines (131 loc) · 6.03 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
---
output:
github_document:
html_preview: false
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
# styler
[](https://travis-ci.org/r-lib/styler)
[](https://ci.appveyor.com/project/r-lib/styler)
[](https://www.tidyverse.org/lifecycle/#stable)
[](https://codecov.io/gh/r-lib/styler)
[](https://cran.r-project.org/package=styler)
The goal of styler is to provide non-invasive pretty-printing of R source code
while adhering to the [tidyverse](https://style.tidyverse.org) formatting rules.
styler can be customized to format code according to other style guides too.
The following online docs are available:
- [latest CRAN release](https://styler.r-lib.org).
- [GitHub development version](https://styler.r-lib.org/dev).
## Installation
You can install the package from CRAN.
```{r, eval = FALSE}
install.packages("styler")
```
If you don't use styler interactively (i.e. not from the R prompt or RStudio
Addin), make sure you authorize `{R.cache}` once to set up a permanent cache.
If you use it interactively, you will be asked to grant this permission once.
See `?caching` for details.
Or get the development version from GitHub:
```{r, eval = FALSE}
# install.packages("remotes")
remotes::install_github("r-lib/styler")
```
## API
You can style a simple character vector of code with `style_text()`:
```{r}
library("styler")
ugly_code <- "a=function( x){1+1} "
style_text(ugly_code)
```
There are a few variants of `style_text()`:
* `style_file()` styles .R, .Rmd .Rnw and .Rprofile, files.
* `style_dir()` styles all .R and/or .Rmd files in a directory.
* `style_pkg()` styles the source files of an R package.
* RStudio Addins for styling the active file, styling the current package and
styling the highlighted code region.
```{r, out.width = "650px", echo = FALSE}
knitr::include_graphics("https://raw.githubusercontent.com/lorenzwalthert/some_raw_data/master/styler_0.1.gif")
```
## Configuration
You can decide on the level of invasiveness with the scope argument. You can
style:
* just spaces.
* spaces and indention.
* spaces, indention and line breaks.
* spaces, indention, line breaks and tokens.
```{r}
ugly_code <- "a=function( x){1+1} "
style_text(ugly_code, scope = "spaces")
```
Note that compared to the default used above `scope = "tokens"`:
* no line breaks were added.
* `<-` was not replaced with `=`.
While spaces still got styled (around `=` in `(x)`).
This was just the tip of the iceberg. To learn more about customization options
with the tidyverse style guide, see the [help file for
`tidyverse_style](https://styler.r-lib.org/reference/tidyverse_style.html) for a
quick overview or the [introductory
vignette](https://styler.r-lib.org/articles/introducing_styler.html).
## Features
* style roxygen2 code examples.
* do not re-style [deliberate code
alignment](https://styler.r-lib.org/articles/detect-alignment.html).
* [ignore some lines](https://styler.r-lib.org/dev/reference/stylerignore.html)
for styling.
* [cache styled
expressions](https://styler.r-lib.org/dev/reference/caching.html) for speed.
## Adaption of styler
styler functionality is made available through other tools, most notably
* as a pre-commit hook `style-files` in
https://github.com/lorenzwalthert/precommit
* `usethis::use_tidy_style()` styles your project according to the tidyverse
style guide.
* via commenting a PR on GitHub with `\style` when the [GitHub
Action](https://github.com/features/actions) [*Tidyverse
CI*](https://github.com/r-lib/actions/tree/master/examples#tidyverse-ci-workflow)
is used. The most convenient way to set this up is via
[`usethis::use_tidy_github_actions()`](https://usethis.r-lib.org/reference/tidyverse.html).
* `reprex::reprex(style = TRUE)` to prettify reprex code before printing. To
permanently use `style = TRUE` without specifying it every time, you can add
the following line to your `.Rprofile` (via `usethis::edit_r_profile()`):
`options(reprex.styler = TRUE)`.
* you can pretty-print your R code in RMarkdown reports without having styler
modifying the source. This feature is implemented as a code chunk option in
knitr. use `tidy = "styler"` in the header of a code chunks (e.g. ` ```{r
name-of-the-chunk, tidy = "styler"}`), or `knitr::opts_chunk$set(tidy =
"styler")` at the top of your RMarkdown script.
* Adding styler as a fixer to the [ale
Plug-in](https://github.com/w0rp/ale/pull/2401#issuecomment-485942966) for
VIM.
* pretty-printing of [drake](https://github.com/ropensci/drake) workflow data
frames with `drake::drake_plan_source()`.
* Adding styler with
[emacs-format-all-the-code](https://github.com/lassik/emacs-format-all-the-code)
for Emacs.
## Further resources
* The official [web documentation](https://styler.r-lib.org/) of styler,
containing various vignettes function documentation as well as a change-log.
* The wiki of [Google Summer of Code
2017](https://github.com/rstats-gsoc/gsoc2017/wiki/Noninvasive-source-code-formatting)
or the [pkgdown](https://r-lib.github.io/styler/) page contain information
related to the initial development phase during Google Summer of Code 2017.
## Contributing
Please have a look at `CONTRIBUTING.md`, in particular, make sure to use the
pre-commit hooks and if you skip a hook, describe why in the PR.
See the `{precommit}` [README.md](https://github.com/lorenzwalthert/precommit)
on how to install the pre-commit framework and the R package on your system and
then run
```{r, eval = FALSE}
precommit::use_precommit()
```
to make sure the hooks are activated in your local styler clone.