|
| 1 | +# `regex-replace` |
| 2 | + |
| 3 | +`regex-replace` is Flint's built-in, line-oriented rewrite engine. It applies |
| 4 | +regular-expression rules to selected files and can add text when a rule |
| 5 | +matches. It does not parse a programming language or contain Java-specific |
| 6 | +logic; the language convention is expressed by the configured regular |
| 7 | +expressions. |
| 8 | + |
| 9 | +This makes it useful for repository-specific mechanical changes that do not |
| 10 | +belong in a general-purpose formatter. |
| 11 | + |
| 12 | +## Example: qualified Java references to static imports |
| 13 | + |
| 14 | +One example is replacing frequently used qualified Java references with static |
| 15 | +imports. Given: |
| 16 | + |
| 17 | +```java |
| 18 | +import java.util.Objects; |
| 19 | + |
| 20 | +class Example { |
| 21 | + void check(Object value) { |
| 22 | + Objects.requireNonNull(value); |
| 23 | + } |
| 24 | +} |
| 25 | +``` |
| 26 | + |
| 27 | +the desired result is: |
| 28 | + |
| 29 | +```java |
| 30 | +import static java.util.Objects.requireNonNull; |
| 31 | +import java.util.Objects; |
| 32 | + |
| 33 | +class Example { |
| 34 | + void check(Object value) { |
| 35 | + requireNonNull(value); |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +The rule has two effects: |
| 41 | + |
| 42 | +1. It rewrites `Objects.requireNonNull` to `requireNonNull`. |
| 43 | +2. It adds the corresponding import once, before the first import or after |
| 44 | + the package declaration when the file has no imports. |
| 45 | + |
| 46 | +Here is a realistic configuration based on the static-import migration this |
| 47 | +check was designed to support: |
| 48 | + |
| 49 | +```toml |
| 50 | +[checks.regex-replace] |
| 51 | +patterns = ["*.java"] |
| 52 | +exclude = ["generated/**", "build/**"] |
| 53 | + |
| 54 | +[[checks.regex-replace.sets]] |
| 55 | +name = "static-imports" |
| 56 | + |
| 57 | +# Rules inherit this replacement unless they specify one themselves. |
| 58 | +# $1 is the first capture group in each direct rule. |
| 59 | +replacement = '$1' |
| 60 | +skip_line_pattern = '^\s*import ' |
| 61 | +add_lines_before_pattern = '^\s*import ' |
| 62 | +add_lines_fallback_after_pattern = '^\s*package ' |
| 63 | + |
| 64 | +# Do not rewrite examples or references inside block comments. |
| 65 | +ignore_regions = [ |
| 66 | + { start_pattern = '^\s*/\*', end_pattern = '\*/' }, |
| 67 | +] |
| 68 | + |
| 69 | +[[checks.regex-replace.sets.rules]] |
| 70 | +pattern = '\bObjects\.(requireNonNull)\b' |
| 71 | +add_lines = ['import static java.util.Objects.$1;'] |
| 72 | + |
| 73 | +[[checks.regex-replace.sets.rules]] |
| 74 | +pattern = '\bElementMatchers\.([a-z][a-zA-Z0-9]*)\b' |
| 75 | +add_lines = ['import static net.bytebuddy.matcher.ElementMatchers.$1;'] |
| 76 | + |
| 77 | +[[checks.regex-replace.sets.rules]] |
| 78 | +pattern = '\bMockito\.(mock|mockStatic|spy|when|verify|never|times)\b' |
| 79 | +add_lines = ['import static org.mockito.Mockito.$1;'] |
| 80 | + |
| 81 | +[[checks.regex-replace.sets.rules]] |
| 82 | +pattern = '(^|[^.])\bLevel\.([A-Z][A-Z_0-9]*)\b' |
| 83 | +replacement = '$1$2' |
| 84 | +add_lines = ['import static java.util.logging.Level.$2;'] |
| 85 | +content_pattern = '(?m)^\s*import java\.util\.logging\.Level;$' |
| 86 | + |
| 87 | +[[checks.regex-replace.sets.rules]] |
| 88 | +pattern = '\bAttributeKey\.(stringKey|longKey|booleanKey|doubleKey)\b' |
| 89 | +add_lines = ['import static io.opentelemetry.api.common.AttributeKey.$1;'] |
| 90 | +line_exclude_pattern = '= AttributeKey\.' |
| 91 | +file_pattern = 'Test\.java$' |
| 92 | + |
| 93 | +# Generate rules from existing imports. For example, an import of |
| 94 | +# io.opentelemetry.semconv.http.HttpAttributes lets the same rule rewrite |
| 95 | +# HttpAttributes.HTTP_REQUEST_METHOD and add the matching static import. |
| 96 | +[[checks.regex-replace.sets.derived_rules]] |
| 97 | +source_pattern = '^import (?P<package>io\.opentelemetry\.semconv(?:\.[a-z][a-z.]*)?\.)(?P<class>[A-Z][a-zA-Z0-9]+);$' |
| 98 | +pattern = '\b{class}\.([A-Z][A-Z_0-9]*)\b' |
| 99 | +add_lines = ['import static {package}$1;'] |
| 100 | +source_exclude_pattern = 'SchemaUrls' |
| 101 | +``` |
| 102 | + |
| 103 | +Run it like any other fixable Flint check: |
| 104 | + |
| 105 | +```bash |
| 106 | +flint run regex-replace |
| 107 | +flint run --fix regex-replace |
| 108 | +``` |
| 109 | + |
| 110 | +## How the configuration is organized |
| 111 | + |
| 112 | +### File selection |
| 113 | + |
| 114 | +The check-level `patterns` and `exclude` select the files Flint gives to the |
| 115 | +linter. Each rule set can add its own `patterns` and `exclude`, using the same |
| 116 | +glob syntax as `[settings].exclude`: |
| 117 | + |
| 118 | +```toml |
| 119 | +[checks.regex-replace] |
| 120 | +patterns = ["*.java", "*.kt"] |
| 121 | +exclude = ["generated/**"] |
| 122 | + |
| 123 | +[[checks.regex-replace.sets]] |
| 124 | +name = "java-only" |
| 125 | +patterns = ["*.java"] |
| 126 | +exclude = ["examples/**"] |
| 127 | +``` |
| 128 | + |
| 129 | +This lets one `regex-replace` check contain independent rule sets for |
| 130 | +different file types or directory scopes. |
| 131 | + |
| 132 | +### Rule sets and defaults |
| 133 | + |
| 134 | +Sets are evaluated in order. A set groups rules that share policy and defaults: |
| 135 | + |
| 136 | +- `replacement` is inherited by direct and derived rules. |
| 137 | +- A rule-level `replacement` overrides the set default. |
| 138 | +- If neither is configured, the replacement is `$0`, preserving the match. |
| 139 | +- `add_lines_before_pattern` and |
| 140 | + `add_lines_fallback_after_pattern` control where unique added lines go. |
| 141 | +- `skip_line_pattern` skips entire lines for every rule in the set. |
| 142 | +- `ignore_regions` skips balanced regions for every rule in the set. |
| 143 | + |
| 144 | +Added lines are deduplicated against the file, so rerunning the fixer does not |
| 145 | +keep adding the same import. |
| 146 | + |
| 147 | +### Rule filters |
| 148 | + |
| 149 | +Direct rules support additional filters: |
| 150 | + |
| 151 | +- `content_pattern` — only apply when the whole file contains a match. |
| 152 | +- `content_exclude_pattern` — skip the rule when the whole file contains a |
| 153 | + match. |
| 154 | +- `line_exclude_pattern` — skip a line when its nearby context matches. |
| 155 | +- `file_pattern` — restrict the rule using the file name. |
| 156 | + |
| 157 | +Derived rules use `source_pattern` to find source lines and named captures such |
| 158 | +as `{package}` and `{class}` to generate a rule. Their |
| 159 | +`source_exclude_pattern` prevents selected source lines from generating rules. |
| 160 | +Capture groups from the generated rule remain available as `$1`, `$2`, and so |
| 161 | +on in `replacement` and `add_lines`. |
| 162 | + |
| 163 | +### Ignored regions |
| 164 | + |
| 165 | +`ignore_regions` is line-based and generic. Each `start_pattern` and |
| 166 | +`end_pattern` is a regular expression matched against a complete source line; |
| 167 | +the marker lines and every line between them are skipped. The markers must be |
| 168 | +balanced. This is useful for block comments, generated snippets, or repository |
| 169 | +conventions that should not be rewritten. |
| 170 | + |
| 171 | +It is deliberately separate from formatter-specific formatter-off handling: |
| 172 | +`regex-replace` skips those lines, while a formatter integration may instead |
| 173 | +format a temporary copy and restore the protected contents afterward. |
| 174 | + |
| 175 | +## Limitations |
| 176 | + |
| 177 | +`regex-replace` is intentionally not a parser or import sorter. It cannot |
| 178 | +prove that a replacement is syntactically valid, resolve overloaded methods, |
| 179 | +or determine whether a static import conflicts with another symbol. Keep the |
| 180 | +patterns narrow, use content and file filters where needed, and review the |
| 181 | +result of a new rule with `flint run --fix` before enabling it broadly. |
0 commit comments