forked from r-lib/styler
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
146 lines (112 loc) · 4.66 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
---
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](http://style.tidyverse.org) formatting rules.
styler can be customized to format code according to other style guides too.
## Installation
You can install the package from CRAN:
```{r, eval = FALSE}
install.packages("styler")
```
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 and/or .Rmd 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")
```
## Functionality of styler
**scope**
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)`).
**strict**
If you wish to keep alignment as is, you can use `strict = FALSE`:
```{r}
style_text(
c(
"first <- 4",
"second <- 1+1"
),
strict = FALSE
)
```
This was just the tip of the iceberg. Learn more about customization with the
tidyverse style guide in in this
[vignette](http://styler.r-lib.org/articles/introducing_styler.html). If this is
not flexible enough for you, you can implement your own style guide, as
explained in the corresponding
[vignette](http://styler.r-lib.org/articles/customizing_styler.html).
## Adaption of styler
styler functionality is made available through other packages, most notably
* `usethis::use_tidy_style()` styles your project according to the tidyverse
style guide.
* `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.
* pretty-printing of [drake](https://github.com/ropensci/drake) workflow data
frames with `drake::drake_plan_source()`.
## Further resources
* The official [web documentation](http://styler.r-lib.org/) of styler,
containing various vignettes function documentation as well as a change-log.
* [Blog
post](https://lorenzwalthert.netlify.com/posts/customizing-styler-the-quick-way/)
about how you can customize styler without being an expert.
* A [tidyverse.org blog
post](https://www.tidyverse.org/articles/2017/12/styler-1.0.0/) introducing the
functionality of styler.
* 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.