You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -5,158 +5,88 @@ you what's wrong, it just rewrites the code for you to fit its style rules.
5
5
6
6
You can learn more about the history, purpose and implementation of Styler from our talk: [Styler: Elixir Style-Guide Enforcer @ GigCity Elixir 2023](https://www.youtube.com/watch?v=6pF8Hl5EuD4)
7
7
8
+
-----------------------
9
+
10
+
Styler's documentation is under work as part of releasing 1.0.
11
+
12
+
You can find the [0.11.9 documentation and readme here.](https://hexdocs.pm/styler/readme.html)
13
+
8
14
## Installation
9
15
10
16
Add `:styler` as a dependency to your project's `mix.exs`:
Please excuse the mess below as I find spare to to update our documentation =)
27
+
28
+
29
+
@TODO put this somewhere more reasonable
30
+
**Note** Styler's only public API is its usage as a formatter plugin. While you're welcome to play with its internals,
31
+
they can and will change without that change being reflected in Styler's semantic version.
32
+
20
33
Then add `Styler` as a plugin to your `.formatter.exs` file
21
34
22
35
```elixir
23
36
[
24
37
plugins: [Styler]
38
+
# optionally: include styler configuration
39
+
# , styler: [alias_lifting_excludes: []]
25
40
]
26
41
```
27
42
28
-
And that's it! Now when you run `mix format` you'll also get the benefits of Styler's *definitely-always-right* style fixes.
43
+
And that's it! Now when you run `mix format` you'll also get the benefits of Styler's Stylish Stylings.
29
44
30
45
### Configuration
31
46
32
-
There isn't any! This is intentional.
47
+
@TODO document: config for lifting, and why we won't add options other configs
33
48
34
49
Styler is @adobe's internal Style Guide Enforcer - allowing exceptions to the styles goes against that ethos. Happily, it's open source and thus yours to do with as you will =)
35
50
36
51
## Features (or as we call them, "Styles")
37
52
38
-
At this point, Styler does a lot. We've catalogued a list of Credo rules that it automatically fixes, but it does some things -
39
-
like shrinking function heads down to a single line when possible - that Credo doesn't care about.
40
-
41
-
Ultimately, the best way to see what Styler does is to just try it out! What could go wrong? (You're using version control, right?)
53
+
@TODO link examples
42
54
43
-
### Credo Rules Styler Replaces
55
+
https://hexdocs.pm/styler/1.0.0-rc.0/styles.html
44
56
45
-
If you're using Credo and Styler, **we recommend disabling these rules in `.credo.exs`** to save on unnecessary checks in CI.
57
+
## Styler & Credo
46
58
47
-
Disabling the rules means updating your `.credo.exs` depending on your configuration:
48
-
49
-
- if you're using `checks: %{enabled: [...]}`, ensure none of the checks are listed in your enabled checks
50
-
- if you're using `checks: %{disabled: [...]}`, copy/paste the snippet below into the list
51
-
- if you're using `checks: [...]`, copy/paste the snippet below into the list and ensure none of the checks appear earlier in the list
52
-
53
-
```elixir
54
-
# Styler Rewrites
55
-
#
56
-
# The following rules are automatically rewritten by Styler and so disabled here to save time
57
-
# Some of the rules have `priority: :high`, meaning Credo runs them unless we explicitly disable them
58
-
# (removing them from this file wouldn't be enough, the `false` is required)
59
-
#
60
-
# Some rules have a comment before them explaining ways Styler deviates from the Credo rule.
**Speed**: Expect the first run to take some time as `Styler` rewrites violations of styles.
106
64
107
65
Once styled the first time, future styling formats shouldn't take noticeably more time.
108
66
109
-
### Troubleshooting: Compilation broke due to Module Directive rearrangement
110
-
111
-
Styler naively moves module attributes, which can break compilation. For now, the only fix is some elbow grease.
112
-
113
-
#### Module Attribute dependency
114
-
115
-
Another common compilation break on the first run is a `@moduledoc` that depended on another module attribute which
116
-
was moved below it.
117
-
118
-
For example, given the following broken code after an initial `mix format`:
67
+
## Styler can break your code
119
68
120
-
```elixir
121
-
defmoduleMyGreatLibrarydo
122
-
@moduledocmake_pretty_docs(@library_options)
123
-
useOptionsMagic, my_opts:@library_options
124
-
125
-
@library_options [ ... ]
126
-
end
127
-
```
128
-
129
-
You can fix the code by moving the static value outside of the module into a naked variable and then reference it in the module. (Note that `use` macros need an `unquote` wrapping the variable!)
130
-
131
-
Yes, this is a thing you can do in a `.ex` file =)
132
-
133
-
```elixir
134
-
library_options = [ ... ]
135
-
136
-
defmoduleMyGreatLibrarydo
137
-
@moduledocmake_pretty_docs(library_options)
138
-
useOptionsMagic, my_opts:unquote(library_options)
139
-
140
-
@library_options library_options
141
-
end
142
-
```
69
+
@TODO link troubleshooting
70
+
mention our rewrite of case true false to if and how we're OK with this being _Styler_, not _SemanticallyEquivalentRewriter_.
0 commit comments