Skip to content

Commit 1379092

Browse files
mike-solomonmike-solomon
authored
Document ImportLayoutStyle (#446)
Fixes: #253 Co-authored-by: Mike Solomon <[email protected]>
1 parent 039ff5b commit 1379092

File tree

1 file changed

+80
-3
lines changed

1 file changed

+80
-3
lines changed

‎docs/concepts-and-explanations/styles.md‎

Lines changed: 80 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Regardless of where you define the style, the style must adhere to the following
4141
:::
4242

4343
| Key | Type | Description |
44-
| ------------ | ---------------- | ----------------------------------------------------------------- |
44+
|--------------|------------------|-------------------------------------------------------------------|
4545
| type | const | A constant: `specs.openrewrite.org/v1beta/style` |
4646
| name | string | A fully qualified, unique name for this style |
4747
| displayName | string | A human-readable name for this style (does not end with a period) |
@@ -66,6 +66,83 @@ styleConfigs:
6666
6767
To see how you would use this style in your project, please jump to [using styles](#using-styles).
6868
69+
#### Style configs
70+
71+
The `styleConfigs` array is where you define the specific formatting rules for your style. Each entry references a style config class and its configuration options.
72+
73+
You can find all available Java style configs in the [rewrite-java style package](https://github.com/openrewrite/rewrite/tree/main/rewrite-java/src/main/java/org/openrewrite/java/style). Some of the most commonly used ones include:
74+
75+
| Style config | Description |
76+
|--------------------------|-------------------------------------------------------|
77+
| `TabsAndIndentsStyle` | Tabs vs. spaces, indent size, continuation indent |
78+
| `SpacesStyle` | Whitespace around operators, brackets, keywords |
79+
| `ImportLayoutStyle` | Import grouping, ordering, and star import thresholds |
80+
| `BlankLinesStyle` | Blank lines before/after classes, methods, fields |
81+
| `WrappingAndBracesStyle` | Line wrapping and brace placement |
82+
83+
When creating your own style, you can combine multiple style configs to fully define your formatting preferences. If you don't configure a particular style config, OpenRewrite will do its best to detect the settings from your existing code.
84+
85+
#### ImportLayoutStyle
86+
87+
Let's take a look at one of the more complicated style configs: `ImportLayoutStyle`. This style config controls how imports are grouped, ordered, and when star imports should be used. You can adjust the following properties on it:
88+
89+
| Property | Type | Default | Description |
90+
|-----------------------------|------------------|------------------|--------------------------------------------------------------------------------------------------------|
91+
| `classCountToUseStarImport` | int | 5 | How many imports from the same package must be present before collapsing into a star import |
92+
| `nameCountToUseStarImport` | int | 3 | How many static imports from the same type must be present before collapsing into a static star import |
93+
| `layout` | array of strings | [IntelliJ default](https://github.com/openrewrite/rewrite/blob/main/rewrite-java/src/main/java/org/openrewrite/java/style/IntelliJ.java#L62-L71) | An ordered list defining how imports should be grouped and ordered |
94+
| `packagesToFold` | array of strings | empty | Packages that should always use star imports when 1 or more types are in use |
95+
96+
**Layout syntax**
97+
98+
The `layout` property in `ImportLayoutStyle` accepts an array of strings that define import groupings. Each string must use one of the following formats:
99+
100+
| Syntax | Description |
101+
|-------------------------------------------------|---------------------------------------------------------------------|
102+
| `<blank line>` | Adds a blank line separator between import groups |
103+
| `import <package>.*` | Match imports from a specific package, including subpackages |
104+
| `import <package>.* without subpackages` | Match imports from only that exact package, not subpackages |
105+
| `import static <package>.*` | Match static imports from a specific package, including subpackages |
106+
| `import static <package>.* without subpackages` | Match static imports from only that exact package |
107+
| `import all other imports` | Catchall for all remaining non-static imports |
108+
| `import static all other imports` | Catchall for all remaining static imports |
109+
110+
:::warning
111+
The layout **must** contain at least one `import all other imports` entry and one `import static all other imports` entry.
112+
:::
113+
114+
**Full example**
115+
116+
Below is a full example of how you'd use `ImportLayoutStyle`. This example layout is very similar to the Google Java style:
117+
118+
```yaml
119+
---
120+
type: specs.openrewrite.org/v1beta/style
121+
name: com.yourorg.CustomImportLayout
122+
styleConfigs:
123+
- org.openrewrite.java.style.ImportLayoutStyle:
124+
classCountToUseStarImport: 999
125+
nameCountToUseStarImport: 999
126+
layout:
127+
- 'import java.*'
128+
- 'import javax.*'
129+
- '<blank line>'
130+
- 'import all other imports'
131+
- '<blank line>'
132+
- 'import static all other imports'
133+
packagesToFold:
134+
- 'import java.awt.*'
135+
- 'import static org.junit.jupiter.api.Assertions.*'
136+
```
137+
138+
This configuration will:
139+
140+
* Group `java.*` imports first, then `javax.*` imports
141+
* Add a blank line, then all other non-static imports
142+
* Add another blank line, then all static imports
143+
* Avoid star imports unless there are 999+ imports from the same package
144+
* Always use star imports for `java.awt.*` and static imports from `org.junit.jupiter.api.Assertions`
145+
69146
### Programmatically in Java
70147

71148
When you go to [specify a style to use](#using-styles), the style needs to be a `NamedStyles`. A `NamedStyles` contains one or more `Style` objects.
@@ -87,7 +164,7 @@ Update your `build.gradle` file to include an `activeStyle` such as in:
87164
rewrite {
88165
activeRecipe("someRecipe")
89166
90-
// This style is made up for the sake of example.
167+
// This style is made up to have an example.
91168
activeStyle("com.yourorg.YesTabsNoStarImports")
92169
}
93170
```
@@ -108,7 +185,7 @@ Update your `pom.xml` file to include an `<activeStyles>` such as in:
108185
<!-- Recipes here -->
109186
</activeRecipes>
110187
<activeStyles>
111-
<!-- This style is made up for sake of example. It isn't packaged with OpenRewrite -->
188+
<!-- This style is made up to have an example. It isn't packaged with OpenRewrite -->
112189
<style>com.yourorg.YesTabsNoStarImports</style>
113190
</activeStyles>
114191
</configuration>

0 commit comments

Comments
 (0)