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         * Sets the property name.
222         *
223         * @param val the property name.
224         * @return this builder.
225         */
226        public Builder name(String val) {
227            buildName = val;
228            return this;
229        }
230
231        /**
232         * Sets the xdoc-safe HTML description.
233         *
234         * @param val the description.
235         * @return this builder.
236         */
237        public Builder description(String val) {
238            buildDescription = val;
239            return this;
240        }
241
242        /**
243         * Sets the resolved type string.
244         *
245         * @param val the type string.
246         * @return this builder.
247         */
248        public Builder type(String val) {
249            buildType = val;
250            return this;
251        }
252
253        /**
254         * Sets the token property type.
255         *
256         * @param val the token property type.
257         * @return this builder.
258         */
259        public Builder tokenPropertyType(TokenPropertyType val) {
260            buildTokenPropertyType = val;
261            return this;
262        }
263
264        /**
265         * Sets the configurable token names.
266         *
267         * @param val the list of token names.
268         * @return this builder.
269         */
270        public Builder configurableTokens(Collection<String> val) {
271            buildConfigurableTokens = List.copyOf(val);
272            return this;
273        }
274
275        /**
276         * Sets the default value string.
277         *
278         * @param val the default value string.
279         * @return this builder.
280         */
281        public Builder defaultValue(String val) {
282            buildDefaultValue = val;
283            return this;
284        }
285
286        /**
287         * Sets the default value token names.
288         *
289         * @param val the list of token names.
290         * @return this builder.
291         */
292        public Builder defaultValueTokens(Collection<String> val) {
293            buildDefaultValueTokens = List.copyOf(val);
294            return this;
295        }
296
297        /**
298         * Sets the since version string.
299         *
300         * @param val the since version.
301         * @return this builder.
302         */
303        public Builder sinceVersion(String val) {
304            buildSinceVersion = val;
305            return this;
306        }
307
308        /**
309         * Builds and returns the {@link PropertyDetails}.
310         *
311         * @return a new {@link PropertyDetails} instance.
312         */
313        public PropertyDetails build() {
314            return new PropertyDetails(this);
315        }
316    }
317}