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.checks.header; 021 022import java.io.File; 023import java.util.ArrayList; 024import java.util.BitSet; 025import java.util.List; 026import java.util.regex.Pattern; 027import java.util.regex.PatternSyntaxException; 028 029import com.puppycrawl.tools.checkstyle.StatelessCheck; 030import com.puppycrawl.tools.checkstyle.api.FileText; 031import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 032import com.puppycrawl.tools.checkstyle.utils.TokenUtil; 033 034/** 035 * <div> 036 * Checks the header of a source file against a header that contains a 037 * <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html"> 038 * pattern</a> for each line of the source header. 039 * </div> 040 * <ul> 041 * <li> 042 * Property {@code charset} - Specify the character encoding to use when reading the headerFile. 043 * Type is {@code java.lang.String}. 044 * Default value is {@code the charset property of the parent 045 * <a href="https://checkstyle.org/config.html#Checker">Checker</a> module}. 046 * </li> 047 * <li> 048 * Property {@code fileExtensions} - Specify the file extensions of the files to process. 049 * Type is {@code java.lang.String[]}. 050 * Default value is {@code ""}. 051 * </li> 052 * <li> 053 * Property {@code header} - Define the required header specified inline. 054 * Individual header lines must be separated by the string {@code "\n"} 055 * (even on platforms with a different line separator). 056 * For header lines containing {@code "\n\n"} checkstyle will 057 * forcefully expect an empty line to exist. See examples below. 058 * Regular expressions must not span multiple lines. 059 * Type is {@code java.lang.String}. 060 * Default value is {@code null}. 061 * </li> 062 * <li> 063 * Property {@code headerFile} - Specify the name of the file containing the required header. 064 * Type is {@code java.net.URI}. 065 * Default value is {@code null}. 066 * </li> 067 * <li> 068 * Property {@code multiLines} - Specify the line numbers to repeat (zero or more times). 069 * Type is {@code int[]}. 070 * Default value is {@code ""}. 071 * </li> 072 * </ul> 073 * 074 * <p> 075 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker} 076 * </p> 077 * 078 * <p> 079 * Violation Message Keys: 080 * </p> 081 * <ul> 082 * <li> 083 * {@code header.mismatch} 084 * </li> 085 * <li> 086 * {@code header.missing} 087 * </li> 088 * </ul> 089 * 090 * @since 6.9 091 */ 092@StatelessCheck 093public class RegexpHeaderCheck extends AbstractHeaderCheck { 094 095 /** 096 * A key is pointing to the warning message text in "messages.properties" 097 * file. 098 */ 099 public static final String MSG_HEADER_MISSING = "header.missing"; 100 101 /** 102 * A key is pointing to the warning message text in "messages.properties" 103 * file. 104 */ 105 public static final String MSG_HEADER_MISMATCH = "header.mismatch"; 106 107 /** Regex pattern for a blank line. **/ 108 private static final String EMPTY_LINE_PATTERN = "^$"; 109 110 /** Compiled regex pattern for a blank line. **/ 111 private static final Pattern BLANK_LINE = Pattern.compile(EMPTY_LINE_PATTERN); 112 113 /** The compiled regular expressions. */ 114 private final List<Pattern> headerRegexps = new ArrayList<>(); 115 116 /** Specify the line numbers to repeat (zero or more times). */ 117 private BitSet multiLines = new BitSet(); 118 119 /** 120 * Setter to specify the line numbers to repeat (zero or more times). 121 * 122 * @param list line numbers to repeat in header. 123 * @since 3.4 124 */ 125 public void setMultiLines(int... list) { 126 multiLines = TokenUtil.asBitSet(list); 127 } 128 129 @Override 130 protected void processFiltered(File file, FileText fileText) { 131 final int headerSize = getHeaderLines().size(); 132 final int fileSize = fileText.size(); 133 134 if (headerSize - multiLines.cardinality() > fileSize) { 135 log(1, MSG_HEADER_MISSING); 136 } 137 else { 138 int headerLineNo = 0; 139 int index; 140 for (index = 0; headerLineNo < headerSize && index < fileSize; index++) { 141 final String line = fileText.get(index); 142 boolean isMatch = isMatch(line, headerLineNo); 143 while (!isMatch && isMultiLine(headerLineNo)) { 144 headerLineNo++; 145 isMatch = headerLineNo == headerSize 146 || isMatch(line, headerLineNo); 147 } 148 if (!isMatch) { 149 log(index + 1, MSG_HEADER_MISMATCH, getHeaderLine(headerLineNo)); 150 break; 151 } 152 if (!isMultiLine(headerLineNo)) { 153 headerLineNo++; 154 } 155 } 156 if (index == fileSize) { 157 // if file finished, but we have at least one non-multi-line 158 // header isn't completed 159 logFirstSinglelineLine(headerLineNo, headerSize); 160 } 161 } 162 } 163 164 /** 165 * Returns the line from the header. Where the line is blank return the regexp pattern 166 * for a blank line. 167 * 168 * @param headerLineNo header line number to return 169 * @return the line from the header 170 */ 171 private String getHeaderLine(int headerLineNo) { 172 String line = getHeaderLines().get(headerLineNo); 173 if (line.isEmpty()) { 174 line = EMPTY_LINE_PATTERN; 175 } 176 return line; 177 } 178 179 /** 180 * Logs warning if any non-multiline lines left in header regexp. 181 * 182 * @param startHeaderLine header line number to start from 183 * @param headerSize whole header size 184 */ 185 private void logFirstSinglelineLine(int startHeaderLine, int headerSize) { 186 for (int lineNum = startHeaderLine; lineNum < headerSize; lineNum++) { 187 if (!isMultiLine(lineNum)) { 188 log(1, MSG_HEADER_MISSING); 189 break; 190 } 191 } 192 } 193 194 /** 195 * Checks if a code line matches the required header line. 196 * 197 * @param line the code line 198 * @param headerLineNo the header line number. 199 * @return true if and only if the line matches the required header line. 200 */ 201 private boolean isMatch(String line, int headerLineNo) { 202 return headerRegexps.get(headerLineNo).matcher(line).find(); 203 } 204 205 /** 206 * Returns true if line is multiline header lines or false. 207 * 208 * @param lineNo a line number 209 * @return if {@code lineNo} is one of the repeat header lines. 210 */ 211 private boolean isMultiLine(int lineNo) { 212 return multiLines.get(lineNo + 1); 213 } 214 215 @Override 216 protected void postProcessHeaderLines() { 217 final List<String> headerLines = getHeaderLines(); 218 for (String line : headerLines) { 219 try { 220 if (line.isEmpty()) { 221 headerRegexps.add(BLANK_LINE); 222 } 223 else { 224 headerRegexps.add(Pattern.compile(line)); 225 } 226 } 227 catch (final PatternSyntaxException ex) { 228 throw new IllegalArgumentException("line " 229 + (headerRegexps.size() + 1) 230 + " in header specification" 231 + " is not a regular expression", ex); 232 } 233 } 234 } 235 236 /** 237 * Setter to define the required header specified inline. 238 * Individual header lines must be separated by the string {@code "\n"} 239 * (even on platforms with a different line separator). 240 * For header lines containing {@code "\n\n"} checkstyle will forcefully 241 * expect an empty line to exist. See examples below. 242 * Regular expressions must not span multiple lines. 243 * 244 * @param header the header value to validate and set (in that order) 245 * @since 5.0 246 */ 247 @Override 248 public void setHeader(String header) { 249 if (!CommonUtil.isBlank(header)) { 250 if (!CommonUtil.isPatternValid(header)) { 251 throw new IllegalArgumentException("Unable to parse format: " + header); 252 } 253 super.setHeader(header); 254 } 255 } 256 257}