From 63c3749e2b846c0fdaa9b7f27edd0d6ec223e83f Mon Sep 17 00:00:00 2001 From: Lorenz Date: Tue, 13 Apr 2021 21:53:49 +0200 Subject: [PATCH] improve docs --- NEWS.md | 20 +++- vignettes/detect-alignment.Rmd | 209 +++++++++++---------------------- 2 files changed, 87 insertions(+), 142 deletions(-) diff --git a/NEWS.md b/NEWS.md index 43cd9ff3e..0ac70503e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,8 +1,24 @@ # styler 1.4.1.9000 (Development version) * `#>` is recognized as an output marker and no space is added after `#` (#771). -* speeding up alignment detection (#774). - +* code with left alignment after `=` in function calls is now recognized as + aligned and won't be reformatted (#774). + ``` + # newly detected + call( + x = 12345, + y2 = 17 + ) + + # already detected previously + call( + x = 12345, + y2 = 17 + ) + ``` + Also see `vignette("detect-alignment")`: + + # styler 1.4.1 * Fix interaction between cache and `base_indention`. This also fixes diff --git a/vignettes/detect-alignment.Rmd b/vignettes/detect-alignment.Rmd index 08e7d2a83..4863b1122 100644 --- a/vignettes/detect-alignment.Rmd +++ b/vignettes/detect-alignment.Rmd @@ -11,14 +11,15 @@ vignette: > knitr::opts_chunk$set(eval = FALSE) ``` +# Overview + Sometimes, you deliberately align code to make it more readable. ```{r} call( - a = 3, - b = 3213232 + a = 3, + bre = 3213232 ) - ``` Until styler 1.1.1.9002 (with `strict = TRUE`, e.g. as in @@ -27,9 +28,8 @@ Until styler 1.1.1.9002 (with `strict = TRUE`, e.g. as in ```{r} call( a = 3, - b = 3213232 + bre = 3213232 ) - ``` because no alignment detection was built in.^[With `strict = FALSE`, the spacing @@ -42,6 +42,31 @@ vignette describes how aligned code is defined in styler and gives some examples so users can format their aligned code to match the definition styler uses to ensure their code is not unintentionally reformatted. +## Examples + +These typical examples match *styler*'s definition of alignment. Note the +spacing around operators and commas. + +```{r} +tibble::tribble( + ~key_here, ~value_here, + "left", "right", # comments are allowed + "long string", "shrt" # columns can overlap ('~' above ',') +) + +purrr::map(x, fun, # arguments on same line as opening brace are not considered + arg2 = 2, + ar = f(k, x) +) + +purrr::map(x, fun, # arguments on same line as opening brace are not considered + arg2 = 2, + ar = f(k, x) +) +``` + +# Details + An important definition used in the remainder is the one of a **column**. All arguments of a function call that have the same position but are placed on different lines form a column. The below call shows a call with two columns and @@ -52,173 +77,79 @@ unnamed: ```{r} call( # column 1 | column 2 | - abkj = f(2), 7, + abkj = f(2), 7, more_ = "a", 2 # more ) ``` ## Function calls -### Non-technical definition - Below, we try to explain in an intuitive way how your code should look like to be recognized as aligned. -**If all arguments in the first column are named**: Make commas match position -vertically and right align everything between commas: +**If all arguments in the first column are named**: + +Make commas match position vertically and align everything right before commas: ```{r} -# all arguments of first column named -> must right align -# aligned if the (imaginary) comma on the last line is in line with the commas -# from the two top lines. +# all arguments of first column named -> must right align values after `=`, +# one or more spaces around `=`, none before and at least one after the comma. +# aligned if the (imaginary) comma on the last line is in line with the commas fell( - x = 1, + x = 1, y = 23, zz = NULL ) # this works also with more than one column fell( - x = 1, annoying = 3, + x = 1, annoying = 3, y = 23, # nothing in column 2 for row 2 - zz = NULL, finally = "" + zz = NULL, finally = "stuff" ) ``` -**If not all arguments of the first column are named:**^[In the below example, -the first argument of the first column is named (`p = 2`). The second argument -of the first column is not (`31`).] Make **all except the first column's -commas** match position - -- vertically - -- right align everything between the commas - -- except before the first comma on a line - -- give priority to correctly indent (i.e. left align): - -```{r} -# not all arguments of first column named, hence, only -# commas of all but the first column must agree. -gell( - p = 2, g = gg(x), n = 3 * 3, # - 31, fds = -1, gz = f / 3, -) - -``` - -By *align everything in between the commas*, we mean put zero space before a -comma and at least one after. Note that the arguments on the first line are -ignored when detecting alignment, which is best shown when code is formatted -such that no line breaks will be modified by _styler_. This applies if all names -on the first line are unnamed and all subsequent are named: +... or match position of `=` vertically and align everything after this operator +left ```{r} -map(x, f, - arg1 = 121, - arg2 = 1 -) -``` - -**Examples** - -These typical examples match _styler_'s definition of alignment. - -```{r} -tibble::tribble( - ~key_here, ~value_here, - "left", "right", # comments are allowed - "long string", "shrt" # columns can overlap ('~' above ',') -) - -purrr::map(x, fun, # arguments on same line as opening brace are not considered - arg2 = 2, - ar = f(x) -) -``` - -### Technical definition - -This section closely follows the implementation of the alignment detection and -is mostly aimed at developers for understanding _styler_ internals. - -Function calls are aligned if **all** of the following conditions hold (for all -but the very first line (i.e. `call(` below): - -* all rows in first column have the same number of lag spaces. This basically - means that the indention is identical for all columns (except for the closing - brace if it is on its own line). The below example has one column, because the - maximal number of commas on one line is one. - -```{r} -# holds -call( - a = 3, - b = 32 +# all arguments of first column named -> must left align values after `=`, +# at least one space before `=`, exactly one after, none before and at least one +# after the comma. +# aligned if the first values after `=` are aligned (and exactly one space after +# `=`) +fell( + x = 1, + y = 23, + zz = NULL ) -# doesn't hold -call( - a = 3, - b = 32 +# this works also with more than one column +fell( + x = 1, annoying = 3, + y = 23, # nothing in column 2 for row 2 + zz = NULL, finally = "stuff" ) ``` -* spacing around comma (0 before, > 1 after, >= 0 after last column on line) and - spacing around `=` (at least one before and after). -```{r} -# holds -call( - a = 3, k = 3, - b = 32, 222 -) - -# doesn't hold -call( - a = 3 , - b = 32 -) -``` - -* All commas from all columns are aligned. This means that for every column, all - commas must be on the same positions as the commas from the other lines. If - not all arguments are named in the first column, this column is not - considered. The reason to exclude the first column is that, as in the example - below, it is possible that some arguments are named while others are not. - Then, it is not generally possible to keep the first rule (i.e. indention - identical across lines). Also ensuring that the comma does not have any spaces - before it and its alignment with other lines does not hold true. This is shown - below with the line `f(x, y),`. For this reason, the requirements exclude the - first column in such cases. The *holds* example shows that is is possible (but - not required) for named arguments to also have the commas separating the first - and second column aligned. +**If not all arguments of the first column are named:**^[In the below example, +the first argument of the first column is named (`p = 2`). The second argument +of the first column is not (`31`).] The same as above, but the first column is +ignored. ```{r} -# holds -call( - a = ff("pk"), k = 3, x = 2, - b = f(-g), 22 + 1, yy = 1, - c = 1, - f(x, y), - k -) - -# doesn't hold -call( - a = 3, - b = 32, c = 2 +# not all arguments of first column named, hence, all (except the first +# column's) commas must match position +gell( + p = 2, g = gg(x), n = 3 * 3, # + 31, fds = -1, gz = f / 3, ) -``` -Note that the above definition does not check alignment of `=`, so _styler_ will -treat the following as aligned: - -```{r} -rge( - x = 99, x = 2, - fs = 1, y = 1, +# or all (except the first column's) `=` must match position +gell( + p = 2, g = gg(x), n = 3 * 3, # + 31, fds = -1, gz = f / 3 + 1, ) ``` @@ -229,5 +160,3 @@ not supported yet. ## Assignment not supported yet. - -