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.utils;
021
022import java.lang.reflect.Field;
023import java.lang.reflect.Modifier;
024import java.util.Arrays;
025import java.util.BitSet;
026import java.util.Locale;
027import java.util.Map;
028import java.util.Optional;
029import java.util.ResourceBundle;
030import java.util.Set;
031import java.util.function.Consumer;
032import java.util.function.Predicate;
033import java.util.stream.Collectors;
034import java.util.stream.IntStream;
035
036import com.puppycrawl.tools.checkstyle.api.DetailAST;
037import com.puppycrawl.tools.checkstyle.api.TokenTypes;
038
039/**
040 * Contains utility methods for tokens.
041 *
042 */
043public final class TokenUtil {
044
045    /** Maps from a token name to value. */
046    private static final Map<String, Integer> TOKEN_NAME_TO_VALUE;
047    /** Maps from a token value to name. */
048    private static final Map<Integer, String> TOKEN_VALUE_TO_NAME;
049
050    /** Array of all token IDs. */
051    private static final int[] TOKEN_IDS;
052
053    /** Format for exception message when getting token by given id. */
054    private static final String TOKEN_ID_EXCEPTION_FORMAT = "unknown TokenTypes id '%s'";
055
056    /** Format for exception message when getting token by given name. */
057    private static final String TOKEN_NAME_EXCEPTION_FORMAT = "unknown TokenTypes value '%s'";
058
059    // initialise the constants
060    static {
061        TOKEN_NAME_TO_VALUE = nameToValueMapFromPublicIntFields(TokenTypes.class);
062        TOKEN_VALUE_TO_NAME = invertMap(TOKEN_NAME_TO_VALUE);
063        TOKEN_IDS = TOKEN_NAME_TO_VALUE.values().stream().mapToInt(Integer::intValue).toArray();
064    }
065
066    /** Stop instances being created. */
067    private TokenUtil() {
068    }
069
070    /**
071     * Gets the IDENT token from the given AST node.
072     *
073     * <p>This method must only be used for AST types where the IDENT token
074     * is guaranteed to NEVER be null. The known types are:
075     * <ul>
076     * <li>{@link TokenTypes#METHOD_DEF}</li>
077     * <li>{@link TokenTypes#CLASS_DEF}</li>
078     * <li>{@link TokenTypes#VARIABLE_DEF}</li>
079     * <li>{@link TokenTypes#PARAMETER_DEF}, <b>but not receiver parameter</b>.</li>
080     * <li>{@link TokenTypes#INTERFACE_DEF}</li>
081     * <li>{@link TokenTypes#ENUM_DEF}</li>
082     * <li>{@link TokenTypes#ANNOTATION_DEF}</li>
083     * <li>{@link TokenTypes#RECORD_DEF}</li>
084     * <li>{@link TokenTypes#LITERAL_CATCH}</li>
085     * </ul>
086     *
087     * @param ast the AST node.
088     * @return the IDENT token (not null).
089     */
090    public static DetailAST getIdent(DetailAST ast) {
091        return NullUtil.notNull(ast.findFirstToken(TokenTypes.IDENT));
092    }
093
094    /**
095     * Gets the value of a static or instance field of type int or of another primitive type
096     * convertible to type int via a widening conversion. Does not throw any checked exceptions.
097     *
098     * @param field from which the int should be extracted
099     * @param object to extract the int value from
100     * @return the value of the field converted to type int
101     * @throws IllegalStateException if this Field object is enforcing Java language access control
102     *         and the underlying field is inaccessible
103     * @see Field#getInt(Object)
104     */
105    public static int getIntFromField(Field field, Object object) {
106        try {
107            return field.getInt(object);
108        }
109        catch (final IllegalAccessException exception) {
110            throw new IllegalStateException(exception + " for field " + field.getName(),
111                    exception);
112        }
113    }
114
115    /**
116     * Creates a map of 'field name' to 'field value' from all {@code public} {@code int} fields
117     * of a class.
118     *
119     * @param cls source class
120     * @return unmodifiable name to value map
121     */
122    public static Map<String, Integer> nameToValueMapFromPublicIntFields(Class<?> cls) {
123        return Arrays.stream(cls.getDeclaredFields())
124            .filter(fld -> Modifier.isPublic(fld.getModifiers()) && fld.getType() == Integer.TYPE)
125            .collect(Collectors.toUnmodifiableMap(
126                Field::getName, fld -> getIntFromField(fld, null))
127            );
128    }
129
130    /**
131     * Inverts a given map by exchanging each entry's key and value.
132     *
133     * @param map source map
134     * @return inverted map
135     */
136    public static Map<Integer, String> invertMap(Map<String, Integer> map) {
137        return map.entrySet().stream()
138            .collect(Collectors.toUnmodifiableMap(Map.Entry::getValue, Map.Entry::getKey));
139    }
140
141    /**
142     * Get total number of TokenTypes.
143     *
144     * @return total number of TokenTypes.
145     */
146    public static int getTokenTypesTotalNumber() {
147        return TOKEN_IDS.length;
148    }
149
150    /**
151     * Get all token IDs that are available in TokenTypes.
152     *
153     * @return array of token IDs
154     */
155    public static int[] getAllTokenIds() {
156        final int[] safeCopy = new int[TOKEN_IDS.length];
157        System.arraycopy(TOKEN_IDS, 0, safeCopy, 0, TOKEN_IDS.length);
158        return safeCopy;
159    }
160
161    /**
162     * Returns the name of a token for a given ID.
163     *
164     * @param id the ID of the token name to get
165     * @return a token name
166     * @throws IllegalArgumentException when id is not valid
167     */
168    public static String getTokenName(int id) {
169        final String name = TOKEN_VALUE_TO_NAME.get(id);
170        if (name == null) {
171            throw new IllegalArgumentException(
172                String.format(Locale.ROOT, TOKEN_ID_EXCEPTION_FORMAT, id));
173        }
174        return name;
175    }
176
177    /**
178     * Returns the ID of a token for a given name.
179     *
180     * @param name the name of the token ID to get
181     * @return a token ID
182     * @throws IllegalArgumentException when id is null
183     */
184    public static int getTokenId(String name) {
185        final Integer id = TOKEN_NAME_TO_VALUE.get(name);
186        if (id == null) {
187            throw new IllegalArgumentException(
188                String.format(Locale.ROOT, TOKEN_NAME_EXCEPTION_FORMAT, name));
189        }
190        return id;
191    }
192
193    /**
194     * Returns the short description of a token for a given name.
195     *
196     * @param name the name of the token ID to get
197     * @return a short description
198     * @throws IllegalArgumentException when name is unknown
199     */
200    public static String getShortDescription(String name) {
201        if (!TOKEN_NAME_TO_VALUE.containsKey(name)) {
202            throw new IllegalArgumentException(
203                String.format(Locale.ROOT, TOKEN_NAME_EXCEPTION_FORMAT, name));
204        }
205
206        final String tokenTypes =
207            "com.puppycrawl.tools.checkstyle.api.tokentypes";
208        final ResourceBundle bundle = ResourceBundle.getBundle(tokenTypes, Locale.ROOT);
209        return bundle.getString(name);
210    }
211
212    /**
213     * Is argument comment-related type (SINGLE_LINE_COMMENT,
214     * BLOCK_COMMENT_BEGIN, BLOCK_COMMENT_END, COMMENT_CONTENT).
215     *
216     * @param type
217     *        token type.
218     * @return true if type is comment-related type.
219     */
220    public static boolean isCommentType(int type) {
221        return type == TokenTypes.SINGLE_LINE_COMMENT
222                || type == TokenTypes.BLOCK_COMMENT_BEGIN
223                || type == TokenTypes.BLOCK_COMMENT_END
224                || type == TokenTypes.COMMENT_CONTENT;
225    }
226
227    /**
228     * Is argument comment-related type name (SINGLE_LINE_COMMENT,
229     * BLOCK_COMMENT_BEGIN, BLOCK_COMMENT_END, COMMENT_CONTENT).
230     *
231     * @param type
232     *        token type name.
233     * @return true if type is comment-related type name.
234     */
235    public static boolean isCommentType(String type) {
236        return isCommentType(getTokenId(type));
237    }
238
239    /**
240     * Finds the first {@link Optional} child token of {@link DetailAST} root node
241     * which matches the given predicate.
242     *
243     * @param root root node.
244     * @param predicate predicate.
245     * @return {@code Optional} of {@code DetailAST} node which matches the predicate.
246     */
247    public static Optional<DetailAST> findFirstTokenByPredicate(DetailAST root,
248                                                                Predicate<DetailAST> predicate) {
249        Optional<DetailAST> result = Optional.empty();
250        for (DetailAST ast = root.getFirstChild(); ast != null; ast = ast.getNextSibling()) {
251            if (predicate.test(ast)) {
252                result = Optional.of(ast);
253                break;
254            }
255        }
256        return result;
257    }
258
259    /**
260     * Performs an action for each child of {@link DetailAST} root node
261     * which matches the given token type.
262     *
263     * @param root root node.
264     * @param type token type to match.
265     * @param action action to perform on the nodes.
266     */
267    public static void forEachChild(DetailAST root, int type, Consumer<DetailAST> action) {
268        for (DetailAST ast = root.getFirstChild(); ast != null; ast = ast.getNextSibling()) {
269            if (ast.getType() == type) {
270                action.accept(ast);
271            }
272        }
273    }
274
275    /**
276     * Determines if two ASTs are on the same line.
277     *
278     * @param ast1   the first AST
279     * @param ast2   the second AST
280     *
281     * @return true if they are on the same line.
282     */
283    public static boolean areOnSameLine(DetailAST ast1, DetailAST ast2) {
284        return ast1.getLineNo() == ast2.getLineNo();
285    }
286
287    /**
288     * Is type declaration token type (CLASS_DEF, INTERFACE_DEF,
289     * ANNOTATION_DEF, ENUM_DEF, RECORD_DEF).
290     *
291     * @param type
292     *        token type.
293     * @return true if type is type declaration token type.
294     */
295    public static boolean isTypeDeclaration(int type) {
296        return type == TokenTypes.CLASS_DEF
297                || type == TokenTypes.INTERFACE_DEF
298                || type == TokenTypes.ANNOTATION_DEF
299                || type == TokenTypes.ENUM_DEF
300                || type == TokenTypes.RECORD_DEF;
301    }
302
303    /**
304     * Determines if the token type belongs to the given types.
305     *
306     * @param type the Token Type to check
307     * @param types the acceptable types
308     *
309     * @return true if type matches one of the given types.
310     */
311    public static boolean isOfType(int type, int... types) {
312        boolean matching = false;
313        for (int tokenType : types) {
314            if (tokenType == type) {
315                matching = true;
316                break;
317            }
318        }
319        return matching;
320    }
321
322    /**
323     * Determines if the token type belongs to the given types.
324     *
325     * @param type the Token Type to check
326     * @param types the acceptable types
327     *
328     * @return true if type matches one of the given types.
329     */
330    public static boolean isOfType(int type, Set<Integer> types) {
331        return types.contains(type);
332    }
333
334    /**
335     * Determines if the AST belongs to the given types.
336     *
337     * @param ast the AST node to check
338     * @param types the acceptable types
339     *
340     * @return true if type matches one of the given types.
341     */
342    public static boolean isOfType(DetailAST ast, int... types) {
343        return ast != null && isOfType(ast.getType(), types);
344    }
345
346    /**
347     * Determines if given AST is a root node, i.e. if the type of the token
348     * we are checking is {@code COMPILATION_UNIT} or {@code COMPACT_COMPILATION_UNIT}.
349     *
350     * @param ast AST to check
351     * @return true if AST is a root node
352     */
353    public static boolean isRootNode(DetailAST ast) {
354        return ast.getType() == TokenTypes.COMPILATION_UNIT
355                || ast.getType() == TokenTypes.COMPACT_COMPILATION_UNIT;
356    }
357
358    /**
359     * Checks if a token type is a literal true or false.
360     *
361     * @param tokenType the TokenType
362     * @return true if tokenType is LITERAL_TRUE or LITERAL_FALSE
363     */
364    public static boolean isBooleanLiteralType(final int tokenType) {
365        final boolean isTrue = tokenType == TokenTypes.LITERAL_TRUE;
366        final boolean isFalse = tokenType == TokenTypes.LITERAL_FALSE;
367        return isTrue || isFalse;
368    }
369
370    /**
371     * Creates a new {@code BitSet} from array of tokens.
372     *
373     * @param tokens to initialize the BitSet
374     * @return tokens as BitSet
375     */
376    public static BitSet asBitSet(int... tokens) {
377        return IntStream.of(tokens)
378                .collect(BitSet::new, BitSet::set, BitSet::or);
379    }
380
381    /**
382     * Creates a new {@code BitSet} from array of tokens.
383     *
384     * @param tokens to initialize the BitSet
385     * @return tokens as BitSet
386     */
387    public static BitSet asBitSet(String... tokens) {
388        return Arrays.stream(tokens)
389                .map(String::trim)
390                .filter(Predicate.not(String::isEmpty))
391                .mapToInt(TokenUtil::getTokenId)
392                .collect(BitSet::new, BitSet::set, BitSet::or);
393    }
394
395}