Source code

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