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.site; 021 022import java.io.IOException; 023import java.nio.file.Files; 024import java.nio.file.Path; 025import java.util.ArrayList; 026import java.util.Collection; 027import java.util.List; 028import java.util.Locale; 029import java.util.regex.Pattern; 030import java.util.stream.Collectors; 031 032import org.apache.maven.doxia.macro.AbstractMacro; 033import org.apache.maven.doxia.macro.Macro; 034import org.apache.maven.doxia.macro.MacroExecutionException; 035import org.apache.maven.doxia.macro.MacroRequest; 036import org.apache.maven.doxia.sink.Sink; 037import org.codehaus.plexus.component.annotations.Component; 038 039/** 040 * A macro that inserts a snippet of code or configuration from a file. 041 */ 042@Component(role = Macro.class, hint = "example") 043public class ExampleMacro extends AbstractMacro { 044 045 /** Starting delimiter for config snippets. */ 046 private static final String XML_CONFIG_START = "/*xml"; 047 048 /** Ending delimiter for config snippets. */ 049 private static final String XML_CONFIG_END = "*/"; 050 051 /** Starting delimiter for code snippets. */ 052 private static final String CODE_SNIPPET_START = "// xdoc section -- start"; 053 054 /** Ending delimiter for code snippets. */ 055 private static final String CODE_SNIPPET_END = "// xdoc section -- end"; 056 057 /** Eight whitespace characters. All example source tags are indented 8 spaces. */ 058 private static final String INDENTATION = " "; 059 060 /** The pattern of xml code blocks. */ 061 private static final Pattern XML_PATTERN = Pattern.compile( 062 "^\\s*(<!DOCTYPE\\s+.*?>|<\\?xml\\s+.*?>|<module\\s+.*?>)\\s*", 063 Pattern.DOTALL 064 ); 065 066 /** The path of the last file. */ 067 private String lastPath = ""; 068 069 /** The line contents of the last file. */ 070 private List<String> lastLines = new ArrayList<>(); 071 072 @Override 073 public void execute(Sink sink, MacroRequest request) throws MacroExecutionException { 074 final String path = (String) request.getParameter("path"); 075 final String type = (String) request.getParameter("type"); 076 077 List<String> lines = lastLines; 078 if (!path.equals(lastPath)) { 079 lines = readFile("src/xdocs-examples/" + path); 080 lastPath = path; 081 lastLines = lines; 082 } 083 084 if ("config".equals(type)) { 085 final String config = getConfigSnippet(lines); 086 087 if (config.isBlank()) { 088 final String message = String.format(Locale.ROOT, 089 "Empty config snippet from %s, check" 090 + " for xml config snippet delimiters in input file.", path 091 ); 092 throw new MacroExecutionException(message); 093 } 094 095 writeSnippet(sink, config); 096 } 097 else if ("code".equals(type)) { 098 String code = getCodeSnippet(lines); 099 // Replace tabs with spaces for FileTabCharacterCheck examples 100 if (path.contains("filetabcharacter")) { 101 code = code.replace("\t", " "); 102 } 103 104 if (code.isBlank()) { 105 final String message = String.format(Locale.ROOT, 106 "Empty code snippet from %s, check" 107 + " for code snippet delimiters in input file.", path 108 ); 109 throw new MacroExecutionException(message); 110 } 111 112 writeSnippet(sink, code); 113 } 114 else if ("raw".equals(type)) { 115 final String content = String.join(ModuleJavadocParsingUtil.NEWLINE, lines); 116 writeSnippet(sink, content); 117 } 118 else { 119 final String message = String.format(Locale.ROOT, "Unknown example type: %s", type); 120 throw new MacroExecutionException(message); 121 } 122 } 123 124 /** 125 * Read the file at the given path and returns its contents as a list of lines. 126 * 127 * @param path the path to the file to read. 128 * @return the contents of the file as a list of lines. 129 * @throws MacroExecutionException if the file could not be read. 130 */ 131 private static List<String> readFile(String path) throws MacroExecutionException { 132 try { 133 final Path exampleFilePath = Path.of(path); 134 return Files.readAllLines(exampleFilePath); 135 } 136 catch (IOException ioException) { 137 final String message = String.format(Locale.ROOT, "Failed to read %s", path); 138 throw new MacroExecutionException(message, ioException); 139 } 140 } 141 142 /** 143 * Extract a configuration snippet from the given lines. Config delimiters use the whole 144 * line for themselves and have no indentation. We use equals() instead of contains() 145 * to be more strict because some examples contain those delimiters. 146 * 147 * @param lines the lines to extract the snippet from. 148 * @return the configuration snippet. 149 */ 150 private static String getConfigSnippet(Collection<String> lines) { 151 return lines.stream() 152 .dropWhile(line -> !XML_CONFIG_START.equals(line)) 153 .skip(1) 154 .takeWhile(line -> !XML_CONFIG_END.equals(line)) 155 .collect(Collectors.joining(ModuleJavadocParsingUtil.NEWLINE)); 156 } 157 158 /** 159 * Extract a code snippet from the given lines. Code delimiters can be indented, so 160 * we use contains() instead of equals(). 161 * 162 * @param lines the lines to extract the snippet from. 163 * @return the code snippet. 164 */ 165 private static String getCodeSnippet(Collection<String> lines) { 166 return lines.stream() 167 .dropWhile(line -> !line.contains(CODE_SNIPPET_START)) 168 .skip(1) 169 .takeWhile(line -> !line.contains(CODE_SNIPPET_END)) 170 .collect(Collectors.joining(ModuleJavadocParsingUtil.NEWLINE)); 171 } 172 173 /** 174 * Writes the given snippet inside a formatted source block. 175 * 176 * @param sink the sink to write to. 177 * @param snippet the snippet to write. 178 */ 179 private static void writeSnippet(Sink sink, String snippet) { 180 sink.rawText("<div class=\"wrapper\">"); 181 final boolean isXml = isXml(snippet); 182 183 final String languageClass; 184 if (isXml) { 185 languageClass = "language-xml"; 186 } 187 else { 188 languageClass = "language-java"; 189 } 190 sink.rawText("<pre class=\"prettyprint\"><code class=\"" + languageClass + "\">" 191 + ModuleJavadocParsingUtil.NEWLINE); 192 sink.rawText(escapeHtml(snippet).trim() + ModuleJavadocParsingUtil.NEWLINE); 193 sink.rawText("</code></pre>"); 194 sink.rawText("</div>"); 195 } 196 197 /** 198 * Escapes HTML special characters in the snippet. 199 * 200 * @param snippet the snippet to escape. 201 * @return the escaped snippet. 202 */ 203 private static String escapeHtml(String snippet) { 204 return snippet.replace("&", "&") 205 .replace("<", "<") 206 .replace(">", ">"); 207 } 208 209 /** 210 * Determines if the given snippet is likely an XML fragment. 211 * 212 * @param snippet the code snippet to analyze. 213 * @return {@code true} if the snippet appears to be XML, otherwise {@code false}. 214 */ 215 private static boolean isXml(String snippet) { 216 return XML_PATTERN.matcher(snippet.trim()).matches(); 217 } 218}