Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2026 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library is distributed in the hope that it will be useful,
011// but WITHOUT ANY WARRANTY; without even the implied warranty of
012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018///////////////////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.site;
021
022import java.util.Collection;
023import java.util.List;
024
025/**
026 * Immutable data object holding all pre-computed details for a single module property.
027 * Built by {@link SiteUtil#buildPropertyDetails}; consumed by {@link PropertiesMacro}
028 * purely for formatting. No internal Checkstyle AST or Javadoc tree types appear here.
029 */
030public final class PropertyDetails {
031
032    /**
033     * Describes how the type cell and default-value cell should be rendered
034     * for token-related properties.
035     */
036    public enum TokenPropertyType {
037        /** Normal property — renders a plain link to property_types.xml. */
038        STANDARD,
039        /**
040         * {@code tokens} property that accepts every token —
041         * renders "set of any supported tokens" with a link.
042         */
043        TOKEN_SET,
044        /** {@code tokens} property with a configurable subset of TokenTypes. */
045        TOKEN_SUBSET,
046        /** {@code javadocTokens} property with a configurable subset of JavadocTokenTypes. */
047        JAVADOC_TOKEN_SUBSET,
048    }
049
050    /** The property name. */
051    private final String name;
052
053    /**
054     * The human-readable description, already rendered as xdoc-safe HTML.
055     * Produced by {@code SiteUtil.getPropertyDescriptionForXdoc}.
056     */
057    private final String description;
058
059    /**
060     * The resolved type string, e.g. {@code "boolean"}, {@code "int"},
061     * {@code "subset of tokens TokenTypes"}.
062     * Meaningful only when {@link #tokenPropertyType} is {@link TokenPropertyType#STANDARD}.
063     */
064    private final String type;
065
066    /**
067     * Determines how the type cell is rendered by {@link PropertiesMacro}.
068     * Defaults to {@link TokenPropertyType#STANDARD}.
069     */
070    private final TokenPropertyType tokenPropertyType;
071
072    /**
073     * The list of configurable token names used when
074     * {@link #tokenPropertyType} is {@link TokenPropertyType#TOKEN_SUBSET}
075     * or {@link TokenPropertyType#JAVADOC_TOKEN_SUBSET}.
076     * Empty otherwise.
077     */
078    private final List<String> configurableTokens;
079
080    /**
081     * The pre-resolved default value string, e.g. {@code "{}"}, {@code "true"},
082     * {@code "all files"}, {@code "TokenTypes"}.
083     * When the default value cell must render individual token links,
084     * {@link #defaultValueTokens} is used instead and this field is empty.
085     */
086    private final String defaultValue;
087
088    /**
089     * Pre-resolved list of token names used when the default-value cell must
090     * render each token as an individual link.
091     * Empty when {@link #defaultValue} should be rendered verbatim.
092     */
093    private final List<String> defaultValueTokens;
094
095    /** The "since" version string, e.g. {@code "8.3"}. */
096    private final String sinceVersion;
097
098    /**
099     * 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}