1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2024 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.function.Consumer;
31 import java.util.function.Predicate;
32 import java.util.stream.Collectors;
33 import java.util.stream.IntStream;
34
35 import com.puppycrawl.tools.checkstyle.api.DetailAST;
36 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
37
38 /**
39 * Contains utility methods for tokens.
40 *
41 */
42 public final class TokenUtil {
43
44 /** Maps from a token name to value. */
45 private static final Map<String, Integer> TOKEN_NAME_TO_VALUE;
46 /** Maps from a token value to name. */
47 private static final Map<Integer, String> TOKEN_VALUE_TO_NAME;
48
49 /** Array of all token IDs. */
50 private static final int[] TOKEN_IDS;
51
52 /** Format for exception message when getting token by given id. */
53 private static final String TOKEN_ID_EXCEPTION_FORMAT = "unknown TokenTypes id '%s'";
54
55 /** Format for exception message when getting token by given name. */
56 private static final String TOKEN_NAME_EXCEPTION_FORMAT = "unknown TokenTypes value '%s'";
57
58 // initialise the constants
59 static {
60 TOKEN_NAME_TO_VALUE = nameToValueMapFromPublicIntFields(TokenTypes.class);
61 TOKEN_VALUE_TO_NAME = invertMap(TOKEN_NAME_TO_VALUE);
62 TOKEN_IDS = TOKEN_NAME_TO_VALUE.values().stream().mapToInt(Integer::intValue).toArray();
63 }
64
65 /** Stop instances being created. **/
66 private TokenUtil() {
67 }
68
69 /**
70 * Gets the value of a static or instance field of type int or of another primitive type
71 * convertible to type int via a widening conversion. Does not throw any checked exceptions.
72 *
73 * @param field from which the int should be extracted
74 * @param object to extract the int value from
75 * @return the value of the field converted to type int
76 * @throws IllegalStateException if this Field object is enforcing Java language access control
77 * and the underlying field is inaccessible
78 * @see Field#getInt(Object)
79 */
80 public static int getIntFromField(Field field, Object object) {
81 try {
82 return field.getInt(object);
83 }
84 catch (final IllegalAccessException exception) {
85 throw new IllegalStateException(exception);
86 }
87 }
88
89 /**
90 * Creates a map of 'field name' to 'field value' from all {@code public} {@code int} fields
91 * of a class.
92 *
93 * @param cls source class
94 * @return unmodifiable name to value map
95 */
96 public static Map<String, Integer> nameToValueMapFromPublicIntFields(Class<?> cls) {
97 return Arrays.stream(cls.getDeclaredFields())
98 .filter(fld -> Modifier.isPublic(fld.getModifiers()) && fld.getType() == Integer.TYPE)
99 .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 }