Gaps in documentation for custom style guides #1170

sorhawell · 2023-12-11T00:23:18Z

Hi stylers

Thank you for a very useful package. I think I have found 1 or perhaps 2 bugs:

It appears that style_text() ignores custom style unless cache is disabled.
It appears that style_file() w/o cache has unintended side effects such that it can only work once with a custom style. To work again the session must be restarted

# Prepare transformers
rpolars_style = function() {

  # derive from tidyverse
  transformers = styler::tidyverse_style()

  # reverse tranformer to make <- into =
  transformers$token$force_assignment_op = function (pd) {
    to_replace = pd$token == "LEFT_ASSIGN"
    pd$token[to_replace] = "EQ_ASSIGN"
    pd$text[to_replace] = "="
    pd
  }

  transformers
}


# CACHE does not take into account transformers
styler::style_text("foo <- 42; bar = TRUE", transformers = rpolars_style()) # good
#> foo = 42
#> bar = TRUE
styler::style_text("foo <- 42; bar = TRUE", transformers = styler::tidyverse_style()) # bad
#> foo <- 42
#> bar = TRUE
styler::style_text("foo <- 42; bar = TRUE", transformers = rpolars_style()) # bad
#> foo <- 42
#> bar = TRUE

styler::cache_clear(ask = FALSE)
styler::cache_deactivate()
#> Deactivated cache.
styler::style_text("foo <- 42; bar = TRUE", transformers = rpolars_style()) # good
#> foo = 42
#> bar = TRUE
styler::style_text("foo <- 42; bar = TRUE", transformers = styler::tidyverse_style()) # good
#> foo <- 42
#> bar <- TRUE
styler::style_text("foo <- 42; bar = TRUE", transformers = rpolars_style()) # good
#> foo = 42
#> bar = TRUE



writeLines("foo <- 42; bar = TRUE", "deleteme.R")
readLines("deleteme.R")
#> [1] "foo <- 42; bar = TRUE"
styler::style_file("deleteme.R", transformers = rpolars_style()) # good
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
readLines("deleteme.R")
#> [1] "foo = 42"   "bar = TRUE"
styler::style_file("deleteme.R", transformers = styler::tidyverse_style()) # good
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
readLines("deleteme.R")
#> [1] "foo <- 42"   "bar <- TRUE"
styler::style_file("deleteme.R", transformers = rpolars_style()) # bad
#> Styling  1  files:
#>  deleteme.R ✔ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    1   File unchanged.
#> ℹ    0   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
readLines("deleteme.R")
#> [1] "foo <- 42"   "bar <- TRUE"
styler::cache_clear(ask = FALSE)
styler::cache_deactivate()
#> Deactivated cache.
styler::style_file("deleteme.R", transformers = rpolars_style()) # bad
#> Styling  1  files:
#>  deleteme.R ✔ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    1   File unchanged.
#> ℹ    0   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
readLines("deleteme.R")
#> [1] "foo <- 42"   "bar <- TRUE"

^{Created on 2023-12-11 with reprex v2.0.2}

The text was updated successfully, but these errors were encountered:

sorhawell · 2023-12-11T00:42:42Z

styler 1.10.2


platform       x86_64-apple-darwin20       
arch           x86_64                      
os             darwin20                    
system         x86_64, darwin20            
status                                     
major          4                           
minor          3.0                         
year           2023                        
month          04                          
day            21                          
svn rev        84292                       
language       R                           
version.string R version 4.3.0 (2023-04-21)
nickname       Already Tomorrow

lorenzwalthert · 2023-12-11T06:25:39Z

Thanks. I believe that may happen because the style guide Name and version that {styler} uses to distinguish between style guides has not been overwritten. Hence, it’s impossible to distinguish your style guide from the tidyverse style when checking the cache. Please see the docs for that: https://styler.r-lib.org/reference/create_style_guide.html.

If you don’t create a style guide from scratch, you can just overwrite these attributes in the list returned by tidyverse_style() I believe. Can you try that? In any case, we should probably fix the docs in multiple places to account for that.

sorhawell · 2023-12-11T11:30:56Z

Thank you @lorenzwalthert . That indeed work perfectly.

I think what went wrong for me is that this guide is focused on making a new style from scratch
vignette("customizing_styler").

... and this guide focuses on deriving, but did not mention the style_guide_name requirement as far as I can see
vignette("remove rules")

Thank you very much !
From my point of view this issue can be closed.

# Prepare transformers
rpolars_style = function() {

  # derive from tidyverse
  transformers = styler::create_style_guide()
  transformers$style_guide_name = "rpolars_style"
  transformers$style_guide_version = "0.1.0"

  # reverse tranformer to make <- into =
  transformers$token$force_assignment_op = function (pd) {
    to_replace = pd$token == "LEFT_ASSIGN"
    pd$token[to_replace] = "EQ_ASSIGN"
    pd$text[to_replace] = "="
    pd
  }

  transformers
}


# CACHE does not take into account transformers
styler::style_text("foo <- 42; bar = TRUE", transformers = rpolars_style()) # good
#> foo = 42; bar = TRUE
styler::style_text("foo <- 42; bar = TRUE", transformers = styler::tidyverse_style()) # good
#> foo <- 42
#> bar <- TRUE
styler::style_text("foo <- 42; bar = TRUE", transformers = rpolars_style()) # good
#> foo = 42; bar = TRUE

writeLines("foo <- 42; bar = TRUE", "deleteme.R")
readLines("deleteme.R")
#> [1] "foo <- 42; bar = TRUE"
styler::style_file("deleteme.R", transformers = rpolars_style()) # good
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
readLines("deleteme.R")
#> [1] "foo = 42; bar = TRUE"
styler::style_file("deleteme.R", transformers = styler::tidyverse_style()) # good
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
readLines("deleteme.R")
#> [1] "foo <- 42"   "bar <- TRUE"
styler::style_file("deleteme.R", transformers = rpolars_style()) # good
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
readLines("deleteme.R")
#> [1] "foo = 42"   "bar = TRUE"

^{Created on 2023-12-11 with reprex v2.0.2}

lorenzwalthert · 2023-12-11T15:35:33Z

Glad it works. I think the docs need refactoring.

There should be a vignette called Customizing styling that outlines the three avenues of customization, as they are outlined in the Remove rules vignette with cross-links to the following other vignettes.
The Remove rules vignette should be called Derive from existing style guide and terminology should not exclusively be on removal. Should mention caching topic with style guide name and version as well as transformers to drop.
The Customizing styler vignette should be called Create style guide from scratch. Should mention caching topic with style guide name and version. Plus transformers to drop.

The should both mention the vignette on distributing style guides. We should be aware that renaming the vignettes will invalidate all links to those and maybe we can use pkgdown redirect feature.

sorhawell · 2023-12-11T20:01:45Z

I will try to figure something out by reading guidelines and a bit of source carefully :)

sorhawell · 2023-12-11T20:24:08Z

Now it works ... again :)

The Remove rules vignette should be called Derive from existing style guide and terminology should not exclusively be on removal.

yes and also transformer_drops was needed in my case

example

# Prepare transformers
rpolars_style = function() {
  
  # derive from tidyverse
  transformers = styler::tidyverse_style()
  transformers$style_guide_name = "rpolars_style"
  transformers$style_guide_version = "0.1.0"

  # reverse tranformer to make <- into =
  transformers$token$force_assignment_op = function (pd) {
    to_replace = pd$token == "LEFT_ASSIGN"
    pd$token[to_replace] = "EQ_ASSIGN"
    pd$text[to_replace] = "="
    pd
  }
  
  # Specify which tokens must be absent for a transformer to be dropped
  # https://styler.r-lib.org/reference/specify_transformers_drop.html?q=transformers%20_%20drop
  transformers$transformers_drop$token$force_assignment_op = "LEFT_ASSIGN"
  
  
  transformers
}


writeLines("
foo <- 42; bar = TRUE
f = function() {
  1
}
if(f()) {
  print('one')
}
", "deleteme.R")
cat(readLines("deleteme.R"),sep = "\n")
#> 
#> foo <- 42; bar = TRUE
#> f = function() {
#>   1
#> }
#> if(f()) {
#>   print('one')
#> }

styler::style_file("deleteme.R", transformers = rpolars_style(), style = rpolars_style) 
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
cat(readLines("deleteme.R"),sep = "\n") # good
#> foo = 42
#> bar = TRUE
#> f = function() {
#>   1
#> }
#> if (f()) {
#>   print("one")
#> }

styler::style_file("deleteme.R", transformers = styler::tidyverse_style())
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
cat(readLines("deleteme.R"),sep = "\n") # good
#> foo <- 42
#> bar <- TRUE
#> f <- function() {
#>   1
#> }
#> if (f()) {
#>   print("one")
#> }

styler::style_file("deleteme.R", transformers = rpolars_style(), style = rpolars_style)
#> Styling  1  files:
#>  deleteme.R ℹ 
#> ────────────────────────────────────────
#> Status   Count   Legend 
#> ✔    0   File unchanged.
#> ℹ    1   File changed.
#> ✖    0   Styling threw an error.
#> ────────────────────────────────────────
#> Please review the changes carefully!
cat(readLines("deleteme.R"),sep = "\n") # good
#> foo = 42
#> bar = TRUE
#> f = function() {
#>   1
#> }
#> if (f()) {
#>   print("one")
#> }

^{Created on 2023-12-11 with reprex v2.0.2}

lorenzwalthert · 2023-12-11T21:20:33Z

Ok great. Yeah true, updating which transformers should be dropped is also required, I completely forgot about that.

sorhawell mentioned this issue Dec 11, 2023

Is it worth continuing to use = for the assignment operator of R? pola-rs/r-polars#590

Closed

lorenzwalthert changed the title ~~styler cache prevents custom styling~~ Gaps in documentation Dec 11, 2023

lorenzwalthert changed the title ~~Gaps in documentation~~ Gaps in documentation for custom style guides Dec 11, 2023

This comment was marked as outdated.

Sign in to view

This comment was marked as duplicate.

Sign in to view

lorenzwalthert mentioned this issue Mar 27, 2024

Overriding tidyverse function arg style #1184

Closed

lorenzwalthert mentioned this issue Apr 5, 2024

Set linter and auto formatter pola-rs/r-polars#214

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Gaps in documentation for custom style guides #1170

Gaps in documentation for custom style guides #1170

sorhawell commented Dec 11, 2023 •

edited

sorhawell commented Dec 11, 2023 •

edited

lorenzwalthert commented Dec 11, 2023 •

edited

sorhawell commented Dec 11, 2023

lorenzwalthert commented Dec 11, 2023 •

edited

This comment was marked as outdated.

sorhawell commented Dec 11, 2023

This comment was marked as duplicate.

sorhawell commented Dec 11, 2023 •

edited

lorenzwalthert commented Dec 11, 2023

Gaps in documentation for custom style guides #1170

Gaps in documentation for custom style guides #1170

Comments

sorhawell commented Dec 11, 2023 • edited

sorhawell commented Dec 11, 2023 • edited

lorenzwalthert commented Dec 11, 2023 • edited

sorhawell commented Dec 11, 2023

lorenzwalthert commented Dec 11, 2023 • edited

This comment was marked as outdated.

sorhawell commented Dec 11, 2023

This comment was marked as duplicate.

sorhawell commented Dec 11, 2023 • edited

lorenzwalthert commented Dec 11, 2023

sorhawell commented Dec 11, 2023 •

edited

sorhawell commented Dec 11, 2023 •

edited

lorenzwalthert commented Dec 11, 2023 •

edited

lorenzwalthert commented Dec 11, 2023 •

edited

sorhawell commented Dec 11, 2023 •

edited