1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2025 the original author or authors.
4 //
5 // This library is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU Lesser General Public
7 // License as published by the Free Software Foundation; either
8 // version 2.1 of the License, or (at your option) any later version.
9 //
10 // This library is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // Lesser General Public License for more details.
14 //
15 // You should have received a copy of the GNU Lesser General Public
16 // License along with this library; if not, write to the Free Software
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 ///////////////////////////////////////////////////////////////////////////////////////////////
19
20 package com.puppycrawl.tools.checkstyle.utils;
21
22 import java.lang.reflect.Field;
23 import java.lang.reflect.Modifier;
24 import java.util.Arrays;
25 import java.util.BitSet;
26 import java.util.Locale;
27 import java.util.Map;
28 import java.util.Optional;
29 import java.util.ResourceBundle;
30 import java.util.Set;
31 import java.util.function.Consumer;
32 import java.util.function.Predicate;
33 import java.util.stream.Collectors;
34 import java.util.stream.IntStream;
35
36 import com.puppycrawl.tools.checkstyle.api.DetailAST;
37 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
38
39 /**
40 * Contains utility methods for tokens.
41 *
42 */
43 public final class TokenUtil {
44
45 /** Maps from a token name to value. */
46 private static final Map<String, Integer> TOKEN_NAME_TO_VALUE;
47 /** Maps from a token value to name. */
48 private static final Map<Integer, String> TOKEN_VALUE_TO_NAME;
49
50 /** Array of all token IDs. */
51 private static final int[] TOKEN_IDS;
52
53 /** Format for exception message when getting token by given id. */
54 private static final String TOKEN_ID_EXCEPTION_FORMAT = "unknown TokenTypes id '%s'";
55
56 /** Format for exception message when getting token by given name. */
57 private static final String TOKEN_NAME_EXCEPTION_FORMAT = "unknown TokenTypes value '%s'";
58
59 // initialise the constants
60 static {
61 TOKEN_NAME_TO_VALUE = nameToValueMapFromPublicIntFields(TokenTypes.class);
62 TOKEN_VALUE_TO_NAME = invertMap(TOKEN_NAME_TO_VALUE);
63 TOKEN_IDS = TOKEN_NAME_TO_VALUE.values().stream().mapToInt(Integer::intValue).toArray();
64 }
65
66 /** Stop instances being created. **/
67 private TokenUtil() {
68 }
69
70 /**
71 * Gets the value of a static or instance field of type int or of another primitive type
72 * convertible to type int via a widening conversion. Does not throw any checked exceptions.
73 *
74 * @param field from which the int should be extracted
75 * @param object to extract the int value from
76 * @return the value of the field converted to type int
77 * @throws IllegalStateException if this Field object is enforcing Java language access control
78 * and the underlying field is inaccessible
79 * @see Field#getInt(Object)
80 */
81 public static int getIntFromField(Field field, Object object) {
82 try {
83 return field.getInt(object);
84 }
85 catch (final IllegalAccessException exception) {
86 throw new IllegalStateException(exception);
87 }
88 }
89
90 /**
91 * Creates a map of 'field name' to 'field value' from all {@code public} {@code int} fields
92 * of a class.
93 *
94 * @param cls source class
95 * @return unmodifiable name to value map
96 */
97 public static Map<String, Integer> nameToValueMapFromPublicIntFields(Class<?> cls) {
98 return Arrays.stream(cls.getDeclaredFields())
99 .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 }