1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2026 the original author or authors.
4 //
5 // This library is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU Lesser General Public
7 // License as published by the Free Software Foundation; either
8 // version 2.1 of the License, or (at your option) any later version.
9 //
10 // This library is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // Lesser General Public License for more details.
14 //
15 // You should have received a copy of the GNU Lesser General Public
16 // License along with this library; if not, write to the Free Software
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 ///////////////////////////////////////////////////////////////////////////////////////////////
19
20 package com.puppycrawl.tools.checkstyle.site;
21
22 import java.util.Collection;
23 import java.util.List;
24
25 /**
26 * Immutable data object holding all pre-computed details for a single module property.
27 * Built by {@link SiteUtil#buildPropertyDetails}; consumed by {@link PropertiesMacro}
28 * purely for formatting. No internal Checkstyle AST or Javadoc tree types appear here.
29 */
30 public final class PropertyDetails {
31
32 /**
33 * Describes how the type cell and default-value cell should be rendered
34 * for token-related properties.
35 */
36 public enum TokenPropertyType {
37 /** Normal property — renders a plain link to property_types.xml. */
38 STANDARD,
39 /**
40 * {@code tokens} property that accepts every token —
41 * renders "set of any supported tokens" with a link.
42 */
43 TOKEN_SET,
44 /** {@code tokens} property with a configurable subset of TokenTypes. */
45 TOKEN_SUBSET,
46 /** {@code javadocTokens} property with a configurable subset of JavadocTokenTypes. */
47 JAVADOC_TOKEN_SUBSET,
48 }
49
50 /** The property name. */
51 private final String name;
52
53 /**
54 * The human-readable description, already rendered as xdoc-safe HTML.
55 * Produced by {@code SiteUtil.getPropertyDescriptionForXdoc}.
56 */
57 private final String description;
58
59 /**
60 * The resolved type string, e.g. {@code "boolean"}, {@code "int"},
61 * {@code "subset of tokens TokenTypes"}.
62 * Meaningful only when {@link #tokenPropertyType} is {@link TokenPropertyType#STANDARD}.
63 */
64 private final String type;
65
66 /**
67 * Determines how the type cell is rendered by {@link PropertiesMacro}.
68 * Defaults to {@link TokenPropertyType#STANDARD}.
69 */
70 private final TokenPropertyType tokenPropertyType;
71
72 /**
73 * The list of configurable token names used when
74 * {@link #tokenPropertyType} is {@link TokenPropertyType#TOKEN_SUBSET}
75 * or {@link TokenPropertyType#JAVADOC_TOKEN_SUBSET}.
76 * Empty otherwise.
77 */
78 private final List<String> configurableTokens;
79
80 /**
81 * The pre-resolved default value string, e.g. {@code "{}"}, {@code "true"},
82 * {@code "all files"}, {@code "TokenTypes"}.
83 * When the default value cell must render individual token links,
84 * {@link #defaultValueTokens} is used instead and this field is empty.
85 */
86 private final String defaultValue;
87
88 /**
89 * Pre-resolved list of token names used when the default-value cell must
90 * render each token as an individual link.
91 * Empty when {@link #defaultValue} should be rendered verbatim.
92 */
93 private final List<String> defaultValueTokens;
94
95 /** The "since" version string, e.g. {@code "8.3"}. */
96 private final String sinceVersion;
97
98 /**
99 * Creates a new {@code PropertyDetails} from the given builder.
100 *
101 * @param builder the builder to copy field values from.
102 */
103 private PropertyDetails(Builder builder) {
104 name = builder.buildName;
105 description = builder.buildDescription;
106 type = builder.buildType;
107 tokenPropertyType = builder.buildTokenPropertyType;
108 configurableTokens = List.copyOf(builder.buildConfigurableTokens);
109 defaultValue = builder.buildDefaultValue;
110 defaultValueTokens = List.copyOf(builder.buildDefaultValueTokens);
111 sinceVersion = builder.buildSinceVersion;
112 }
113
114 /**
115 * Returns the property name.
116 *
117 * @return the property name.
118 */
119 public String getName() {
120 return name;
121 }
122
123 /**
124 * Returns the xdoc-safe HTML description.
125 *
126 * @return the description.
127 */
128 public String getDescription() {
129 return description;
130 }
131
132 /**
133 * Returns the resolved type string. Meaningful only when
134 * {@link #getTokenPropertyType()} is {@link TokenPropertyType#STANDARD}.
135 *
136 * @return the type string, or {@code null} for token properties.
137 */
138 public String getType() {
139 return type;
140 }
141
142 /**
143 * Returns the rendering strategy for the type and default-value cells.
144 *
145 * @return the token property type.
146 */
147 public TokenPropertyType getTokenPropertyType() {
148 return tokenPropertyType;
149 }
150
151 /**
152 * Returns the list of configurable token names. Non-empty only when
153 * {@link #getTokenPropertyType()} is {@link TokenPropertyType#TOKEN_SUBSET}
154 * or {@link TokenPropertyType#JAVADOC_TOKEN_SUBSET}.
155 *
156 * @return an unmodifiable list of token names.
157 */
158 public List<String> getConfigurableTokens() {
159 return configurableTokens;
160 }
161
162 /**
163 * Returns the pre-resolved default value string. Empty when
164 * {@link #getDefaultValueTokens()} should be used instead.
165 *
166 * @return the default value string.
167 */
168 public String getDefaultValue() {
169 return defaultValue;
170 }
171
172 /**
173 * Returns the list of token names to render as individual links in the
174 * default-value cell. Empty when {@link #getDefaultValue()} should be used instead.
175 *
176 * @return an unmodifiable list of token names.
177 */
178 public List<String> getDefaultValueTokens() {
179 return defaultValueTokens;
180 }
181
182 /**
183 * Returns the "since" version string.
184 *
185 * @return the since version.
186 */
187 public String getSinceVersion() {
188 return sinceVersion;
189 }
190
191 /**
192 * Builder for {@link PropertyDetails}.
193 */
194 public static final class Builder {
195
196 /** The property name. */
197 private String buildName;
198
199 /** The xdoc-safe HTML description. */
200 private String buildDescription;
201
202 /** The resolved type string. */
203 private String buildType;
204
205 /** The token property type; defaults to STANDARD. */
206 private TokenPropertyType buildTokenPropertyType = TokenPropertyType.STANDARD;
207
208 /** The configurable token names. */
209 private List<String> buildConfigurableTokens = List.of();
210
211 /** The default value string. */
212 private String buildDefaultValue = "";
213
214 /** The default value token names. */
215 private List<String> buildDefaultValueTokens = List.of();
216
217 /** The since version string. */
218 private String buildSinceVersion = "";
219
220 /**
221 * Creates a new {@code Builder} instance.
222 */
223 public Builder() {
224 // no code by default
225 }
226
227 /**
228 * Sets the property name.
229 *
230 * @param val the property name.
231 * @return this builder.
232 */
233 public Builder name(String val) {
234 buildName = val;
235 return this;
236 }
237
238 /**
239 * Sets the xdoc-safe HTML description.
240 *
241 * @param val the description.
242 * @return this builder.
243 */
244 public Builder description(String val) {
245 buildDescription = val;
246 return this;
247 }
248
249 /**
250 * Sets the resolved type string.
251 *
252 * @param val the type string.
253 * @return this builder.
254 */
255 public Builder type(String val) {
256 buildType = val;
257 return this;
258 }
259
260 /**
261 * Sets the token property type.
262 *
263 * @param val the token property type.
264 * @return this builder.
265 */
266 public Builder tokenPropertyType(TokenPropertyType val) {
267 buildTokenPropertyType = val;
268 return this;
269 }
270
271 /**
272 * Sets the configurable token names.
273 *
274 * @param val the list of token names.
275 * @return this builder.
276 */
277 public Builder configurableTokens(Collection<String> val) {
278 buildConfigurableTokens = List.copyOf(val);
279 return this;
280 }
281
282 /**
283 * Sets the default value string.
284 *
285 * @param val the default value string.
286 * @return this builder.
287 */
288 public Builder defaultValue(String val) {
289 buildDefaultValue = val;
290 return this;
291 }
292
293 /**
294 * Sets the default value token names.
295 *
296 * @param val the list of token names.
297 * @return this builder.
298 */
299 public Builder defaultValueTokens(Collection<String> val) {
300 buildDefaultValueTokens = List.copyOf(val);
301 return this;
302 }
303
304 /**
305 * Sets the since version string.
306 *
307 * @param val the since version.
308 * @return this builder.
309 */
310 public Builder sinceVersion(String val) {
311 buildSinceVersion = val;
312 return this;
313 }
314
315 /**
316 * Builds and returns the {@link PropertyDetails}.
317 *
318 * @return a new {@link PropertyDetails} instance.
319 */
320 public PropertyDetails build() {
321 return new PropertyDetails(this);
322 }
323 }
324
325 }