Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2025 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}