This vignette describes how you can distribute your own style guide.
It builds on vignette("customizing_styler") and assumes you
understand how to create a style guide with
create_style_guide().
There are a few packages that implement a third-party style guide that are maintained by styler contributors:
Other available style guides include:
To start out, you can use the GitHub Template for third-party style guides that has already the right directory structure and patterns described below in place.
You made one too? Please submit a PR to include it in the list.
The style guides mentioned above follow best practices and can serve as a good and rather minimal example of how to implement your own style guide. Most importantly, these two packages:
style argument set to the custom style guide, plus custom
style guides. The advantage of this is that you can use that namespace
as a drop-in replacement for styler everywhere. In particular, if you
want to use the tidyverse style guide, use
styler::style_pkg(), if you want to use a third-party style
guide, use the other namespace,
e.g. styler.mlr::style_pkg():::.
These internals are subject to change without prior notice, which is why
the packages also have unit tests. Also note that importing internals
from another package means your package can’t be added to CRAN because
packages calling private methods from other packages don’t pass CRAN
checks. The only way around this would be to export some styler
internals, e.g. via a {styler.infra} package, but that would be a lot of
work on our side and therefore not currently on the roadmap. Another
alternative for developers might be to use https://github.com/wch/staticimports, which we have not
explored so far.*-in.R and *-out.R files that are checked with
styler:::test_collection().When creating a custom style guide and distribute it, we want to
quickly recall important arguments for create_style_guide()
from the docs:
style_guide_name, style_guide_version and
more_specs_style_guide: These arguments are relevant for
caching and make sure the user’s cache is invalidated on releasing a new
version. The documentation specifies how to set these arguments.transformers_drop: This argument can be created with
specify_transformers_drop() to define conditions under
which a transformer can be removed from the style guide without an
effect on the result. This makes styler faster. For example, if you have
a transformer that removes the token ; and replaces it with
a line break, it is only required if the code to style contains this
token. Since this will hardly be the case for people who adhere to the
tidyverse style guide, we formulate such a rule like thisstyler::specify_transformers_drop(
spaces = list(style_space_around_tilde = "'~'"),
tokens = list(resolve_semicolon = "';'")
)
#> $space
#> $space$style_space_around_tilde
#> [1] "'~'"
#>
#>
#> $indention
#> NULL
#>
#> $line_break
#> NULL
#>
#> $token
#> $token$resolve_semicolon
#> [1] "';'"Where the name must correspond to the transformer function in question and the value is the token that must be absent in order to drop the transformer.