Source code

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