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