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; 021 022import java.io.File; 023import java.io.IOException; 024import java.io.PrintWriter; 025import java.nio.charset.StandardCharsets; 026import java.util.function.Consumer; 027import java.util.regex.Matcher; 028import java.util.regex.Pattern; 029 030import com.puppycrawl.tools.checkstyle.api.CheckstyleException; 031import com.puppycrawl.tools.checkstyle.api.DetailAST; 032import com.puppycrawl.tools.checkstyle.api.DetailNode; 033import com.puppycrawl.tools.checkstyle.api.JavadocCommentsTokenTypes; 034import com.puppycrawl.tools.checkstyle.api.TokenTypes; 035import com.puppycrawl.tools.checkstyle.utils.JavadocUtil; 036import picocli.CommandLine; 037import picocli.CommandLine.Command; 038import picocli.CommandLine.Option; 039import picocli.CommandLine.ParameterException; 040import picocli.CommandLine.Parameters; 041import picocli.CommandLine.ParseResult; 042 043/** 044 * This class is used internally in the build process to write a property file 045 * with short descriptions (the first sentences) of TokenTypes constants. 046 * Request: 724871 047 * For IDE plugins (like the eclipse plugin) it would be useful to have 048 * programmatic access to the first sentence of the TokenType constants, 049 * so they can use them in their configuration gui. 050 * 051 * @noinspection UseOfSystemOutOrSystemErr, unused, ClassIndependentOfModule 052 * @noinspectionreason UseOfSystemOutOrSystemErr - used for CLI output 053 * @noinspectionreason unused - main method is "unused" in code since it is driver method 054 * @noinspectionreason ClassIndependentOfModule - architecture of package requires this 055 */ 056public final class JavadocPropertiesGenerator { 057 058 /** 059 * This regexp is used to extract the first sentence from the text. 060 * The end of the sentence is determined by the symbol "period", "exclamation mark" or 061 * "question mark", followed by a space or the end of the text. 062 */ 063 private static final Pattern END_OF_SENTENCE_PATTERN = Pattern.compile( 064 "(([^.?!]|[.?!](?!\\s|$))*+[.?!])(\\s|$)"); 065 066 /** 067 * Don't create instance of this class, use the {@link #main(String[])} method instead. 068 */ 069 private JavadocPropertiesGenerator() { 070 } 071 072 /** 073 * TokenTypes.properties generator entry point. 074 * 075 * @param args the command line arguments 076 * @throws CheckstyleException if parser or lexer failed or if there is an IO problem 077 **/ 078 public static void main(String... args) throws CheckstyleException { 079 final CliOptions cliOptions = new CliOptions(); 080 final CommandLine cmd = new CommandLine(cliOptions); 081 try { 082 final ParseResult parseResult = cmd.parseArgs(args); 083 if (parseResult.isUsageHelpRequested()) { 084 cmd.usage(System.out); 085 } 086 else { 087 writePropertiesFile(cliOptions); 088 } 089 } 090 catch (ParameterException exc) { 091 System.err.println(exc.getMessage()); 092 exc.getCommandLine().usage(System.err); 093 } 094 } 095 096 /** 097 * Creates the .properties file from a .java file. 098 * 099 * @param options the user-specified options 100 * @throws CheckstyleException if a javadoc comment can not be parsed 101 */ 102 private static void writePropertiesFile(CliOptions options) throws CheckstyleException { 103 try (PrintWriter writer = new PrintWriter(options.outputFile, StandardCharsets.UTF_8)) { 104 final DetailAST top = JavaParser.parseFile(options.inputFile, 105 JavaParser.Options.WITH_COMMENTS).getFirstChild(); 106 final DetailAST objBlock = getClassBody(top); 107 if (objBlock != null) { 108 iteratePublicStaticIntFields(objBlock, writer::println); 109 } 110 } 111 catch (IOException exc) { 112 throw new CheckstyleException("Failed to write javadoc properties of '" 113 + options.inputFile + "' to '" + options.outputFile + "'", exc); 114 } 115 } 116 117 /** 118 * Walks over the type members and push the first javadoc sentence of every 119 * {@code public} {@code static} {@code int} field to the consumer. 120 * 121 * @param objBlock the OBJBLOCK of a class to iterate over its members 122 * @param consumer first javadoc sentence consumer 123 * @throws CheckstyleException if failed to parse a javadoc comment 124 */ 125 private static void iteratePublicStaticIntFields(DetailAST objBlock, Consumer<String> consumer) 126 throws CheckstyleException { 127 for (DetailAST member = objBlock.getFirstChild(); member != null; 128 member = member.getNextSibling()) { 129 if (isPublicStaticFinalIntField(member)) { 130 final DetailAST modifiers = member.findFirstToken(TokenTypes.MODIFIERS); 131 final String firstJavadocSentence = getFirstJavadocSentence(modifiers); 132 if (firstJavadocSentence != null) { 133 consumer.accept(getName(member) + "=" + firstJavadocSentence.trim()); 134 } 135 } 136 } 137 } 138 139 /** 140 * Finds the class body of the first class in the DetailAST. 141 * 142 * @param top AST to find the class body 143 * @return OBJBLOCK token if found; {@code null} otherwise 144 */ 145 private static DetailAST getClassBody(DetailAST top) { 146 DetailAST ast = top; 147 while (ast != null && ast.getType() != TokenTypes.CLASS_DEF) { 148 ast = ast.getNextSibling(); 149 } 150 DetailAST objBlock = null; 151 if (ast != null) { 152 objBlock = ast.findFirstToken(TokenTypes.OBJBLOCK); 153 } 154 return objBlock; 155 } 156 157 /** 158 * Checks that the DetailAST is a {@code public} {@code static} {@code final} {@code int} field. 159 * 160 * @param ast to process 161 * @return {@code true} if matches; {@code false} otherwise 162 */ 163 private static boolean isPublicStaticFinalIntField(DetailAST ast) { 164 boolean result = ast.getType() == TokenTypes.VARIABLE_DEF; 165 if (result) { 166 final DetailAST type = ast.findFirstToken(TokenTypes.TYPE); 167 final DetailAST arrayDeclarator = type.getFirstChild().getNextSibling(); 168 result = arrayDeclarator == null 169 && type.getFirstChild().getType() == TokenTypes.LITERAL_INT; 170 if (result) { 171 final DetailAST modifiers = ast.findFirstToken(TokenTypes.MODIFIERS); 172 result = modifiers.findFirstToken(TokenTypes.LITERAL_PUBLIC) != null 173 && modifiers.findFirstToken(TokenTypes.LITERAL_STATIC) != null 174 && modifiers.findFirstToken(TokenTypes.FINAL) != null; 175 } 176 } 177 return result; 178 } 179 180 /** 181 * Extracts the name of an ast. 182 * 183 * @param ast to extract the name 184 * @return the text content of the inner {@code TokenTypes.IDENT} node 185 */ 186 private static String getName(DetailAST ast) { 187 return ast.findFirstToken(TokenTypes.IDENT).getText(); 188 } 189 190 /** 191 * Extracts the first sentence as HTML formatted text from the comment of an DetailAST. 192 * The end of the sentence is determined by the symbol "period", "exclamation mark" or 193 * "question mark", followed by a space or the end of the text. Inline tags @code and @literal 194 * are converted to HTML code. 195 * 196 * @param ast to extract the first sentence 197 * @return the first sentence of the inner {@code TokenTypes.BLOCK_COMMENT_BEGIN} node 198 * or {@code null} if the first sentence is absent or malformed (does not end with period) 199 * @throws CheckstyleException if a javadoc comment can not be parsed or an unsupported inline 200 * tag found 201 */ 202 private static String getFirstJavadocSentence(DetailAST ast) throws CheckstyleException { 203 String firstSentence = null; 204 for (DetailAST child = ast.getFirstChild(); child != null && firstSentence == null; 205 child = child.getNextSibling()) { 206 // If there is an annotation, the javadoc comment will be a child of it. 207 if (child.getType() == TokenTypes.ANNOTATION) { 208 firstSentence = getFirstJavadocSentence(child); 209 } 210 // Otherwise, the javadoc comment will be right here. 211 else if (child.getType() == TokenTypes.BLOCK_COMMENT_BEGIN 212 && JavadocUtil.isJavadocComment(child)) { 213 final DetailNode tree = DetailNodeTreeStringPrinter.parseJavadocAsDetailNode(child); 214 firstSentence = getFirstJavadocSentence(tree); 215 } 216 } 217 return firstSentence; 218 } 219 220 /** 221 * Extracts the first sentence as HTML formatted text from a DetailNode. 222 * The end of the sentence is determined by the symbol "period", "exclamation mark" or 223 * "question mark", followed by a space or the end of the text. Inline tags @code and @literal 224 * are converted to HTML code. 225 * 226 * @param tree to extract the first sentence 227 * @return the first sentence of the node or {@code null} if the first sentence is absent or 228 * malformed (does not end with any of the end-of-sentence markers) 229 * @throws CheckstyleException if an unsupported inline tag found 230 */ 231 private static String getFirstJavadocSentence(DetailNode tree) throws CheckstyleException { 232 String firstSentence = null; 233 final StringBuilder builder = new StringBuilder(128); 234 235 for (DetailNode node = tree.getFirstChild(); node != null; 236 node = node.getNextSibling()) { 237 if (node.getType() == JavadocCommentsTokenTypes.TEXT) { 238 final Matcher matcher = END_OF_SENTENCE_PATTERN.matcher(node.getText()); 239 if (matcher.find()) { 240 // Commit the sentence if an end-of-sentence marker is found. 241 firstSentence = builder.append(matcher.group(1)).toString(); 242 break; 243 } 244 // Otherwise append the whole line and look for an end-of-sentence marker 245 // on the next line. 246 builder.append(node.getText()); 247 } 248 else if (node.getType() == JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG) { 249 formatInlineCodeTag(builder, node); 250 } 251 else { 252 formatHtmlElement(builder, node); 253 } 254 } 255 return firstSentence; 256 } 257 258 /** 259 * Converts inline code tag into HTML form. 260 * 261 * @param builder to append 262 * @param inlineTag to format 263 * @throws CheckstyleException if the inline javadoc tag is not a literal nor a code tag 264 */ 265 private static void formatInlineCodeTag(StringBuilder builder, DetailNode inlineTag) 266 throws CheckstyleException { 267 final int tagType = inlineTag.getFirstChild().getType(); 268 269 if (tagType != JavadocCommentsTokenTypes.LITERAL_INLINE_TAG 270 && tagType != JavadocCommentsTokenTypes.CODE_INLINE_TAG) { 271 throw new CheckstyleException("Unsupported inline tag " 272 + JavadocUtil.getTokenName(tagType)); 273 } 274 275 final boolean wrapWithCodeTag = tagType == JavadocCommentsTokenTypes.CODE_INLINE_TAG; 276 277 for (DetailNode node = inlineTag.getFirstChild().getFirstChild(); node != null; 278 node = node.getNextSibling()) { 279 switch (node.getType()) { 280 // The text to append. 281 case JavadocCommentsTokenTypes.TEXT: 282 if (wrapWithCodeTag) { 283 builder.append("<code>").append(node.getText().trim()).append("</code>"); 284 } 285 else { 286 builder.append(node.getText().trim()); 287 } 288 break; 289 // skip tag markers 290 case JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG_START: 291 case JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG_END: 292 case JavadocCommentsTokenTypes.TAG_NAME: 293 break; 294 default: 295 throw new CheckstyleException("Unsupported child in the inline tag " 296 + JavadocUtil.getTokenName(node.getType())); 297 } 298 } 299 } 300 301 /** 302 * Concatenates the HTML text from AST of a JavadocTokenTypes.HTML_ELEMENT. 303 * 304 * @param builder to append 305 * @param node to format 306 */ 307 private static void formatHtmlElement(StringBuilder builder, DetailNode node) { 308 switch (node.getType()) { 309 case JavadocCommentsTokenTypes.TAG_OPEN, 310 JavadocCommentsTokenTypes.TAG_CLOSE, 311 JavadocCommentsTokenTypes.TAG_SLASH, 312 JavadocCommentsTokenTypes.TAG_SLASH_CLOSE, 313 JavadocCommentsTokenTypes.TAG_NAME, 314 JavadocCommentsTokenTypes.TEXT -> 315 builder.append(node.getText()); 316 317 default -> { 318 for (DetailNode child = node.getFirstChild(); child != null; 319 child = child.getNextSibling()) { 320 formatHtmlElement(builder, child); 321 } 322 } 323 } 324 325 } 326 327 /** 328 * Helper class encapsulating the command line options and positional parameters. 329 */ 330 @Command(name = "java com.puppycrawl.tools.checkstyle.JavadocPropertiesGenerator", 331 mixinStandardHelpOptions = true) 332 private static final class CliOptions { 333 334 /** 335 * The command line option to specify the output file. 336 */ 337 @Option(names = "--destfile", required = true, description = "The output file.") 338 private File outputFile; 339 340 /** 341 * The command line positional parameter to specify the input file. 342 */ 343 @Parameters(index = "0", description = "The input file.") 344 private File inputFile; 345 } 346}