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.api;
21
22 import java.util.ArrayList;
23 import java.util.Collection;
24 import java.util.Collections;
25 import java.util.HashMap;
26 import java.util.List;
27 import java.util.Map;
28 import java.util.regex.Pattern;
29
30 import com.puppycrawl.tools.checkstyle.grammar.CommentListener;
31 import com.puppycrawl.tools.checkstyle.utils.CheckUtil;
32 import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
33
34 /**
35 * Represents the contents of a file.
36 *
37 */
38 public final class FileContents implements CommentListener {
39
40 /**
41 * The pattern to match a single-line comment containing only the comment
42 * itself -- no code.
43 */
44 private static final String MATCH_SINGLELINE_COMMENT_PAT = "^\\s*//.*$";
45 /** Compiled regexp to match a single-line comment line. */
46 private static final Pattern MATCH_SINGLELINE_COMMENT = Pattern
47 .compile(MATCH_SINGLELINE_COMMENT_PAT);
48
49 /** The text. */
50 private final FileText text;
51
52 /**
53 * Map of the Javadoc comments indexed on the last line of the comment.
54 * The hack is it assumes that there is only one Javadoc comment per line.
55 */
56 private final Map<Integer, TextBlock> javadocComments = new HashMap<>();
57 /** Map of the C++ comments indexed on the first line of the comment. */
58 private final Map<Integer, TextBlock> cppComments = new HashMap<>();
59
60 /**
61 * Map of the C comments indexed on the first line of the comment to a list
62 * of comments on that line.
63 */
64 private final Map<Integer, List<TextBlock>> clangComments = new HashMap<>();
65
66 /**
67 * Creates a new {@code FileContents} instance.
68 *
69 * @param text the contents of the file
70 */
71 public FileContents(FileText text) {
72 this.text = new FileText(text);
73 }
74
75 /**
76 * Get the full text of the file.
77 *
78 * @return an object containing the full text of the file
79 */
80 public FileText getText() {
81 return new FileText(text);
82 }
83
84 /**
85 * Gets the lines in the file.
86 *
87 * @return the lines in the file
88 */
89 public String[] getLines() {
90 return text.toLinesArray();
91 }
92
93 /**
94 * Get the line from text of the file.
95 *
96 * @param index index of the line
97 * @return line from text of the file
98 */
99 public String getLine(int index) {
100 return text.get(index);
101 }
102
103 /**
104 * Gets the name of the file.
105 *
106 * @return the name of the file
107 */
108 public String getFileName() {
109 return text.getFile().toString();
110 }
111
112 @Override
113 public void reportSingleLineComment(String type, int startLineNo,
114 int startColNo) {
115 reportSingleLineComment(startLineNo, startColNo);
116 }
117
118 /**
119 * Report the location of a single-line comment.
120 *
121 * @param startLineNo the starting line number
122 * @param startColNo the starting column number
123 **/
124 public void reportSingleLineComment(int startLineNo, int startColNo) {
125 final String line = line(startLineNo - 1);
126 final String[] txt = {line.substring(startColNo)};
127 final Comment comment = new Comment(txt, startColNo, startLineNo,
128 line.length() - 1);
129 cppComments.put(startLineNo, comment);
130 }
131
132 @Override
133 public void reportBlockComment(String type, int startLineNo,
134 int startColNo, int endLineNo, int endColNo) {
135 reportBlockComment(startLineNo, startColNo, endLineNo, endColNo);
136 }
137
138 /**
139 * Report the location of a block comment.
140 *
141 * @param startLineNo the starting line number
142 * @param startColNo the starting column number
143 * @param endLineNo the ending line number
144 * @param endColNo the ending column number
145 **/
146 public void reportBlockComment(int startLineNo, int startColNo,
147 int endLineNo, int endColNo) {
148 final String[] cComment = extractBlockComment(startLineNo, startColNo,
149 endLineNo, endColNo);
150 final Comment comment = new Comment(cComment, startColNo, endLineNo,
151 endColNo);
152
153 // save the comment
154 final List<TextBlock> entries = clangComments.computeIfAbsent(startLineNo,
155 empty -> new ArrayList<>());
156
157 entries.add(comment);
158
159 // Remember if possible Javadoc comment
160 final String firstLine = line(startLineNo - 1);
161 if (firstLine.contains("/**") && !firstLine.contains("/**/")) {
162 javadocComments.put(endLineNo - 1, comment);
163 }
164 }
165
166 /**
167 * Returns the specified block comment as a String array.
168 *
169 * @param startLineNo the starting line number
170 * @param startColNo the starting column number
171 * @param endLineNo the ending line number
172 * @param endColNo the ending column number
173 * @return block comment as an array
174 **/
175 private String[] extractBlockComment(int startLineNo, int startColNo,
176 int endLineNo, int endColNo) {
177 final String[] returnValue;
178 if (startLineNo == endLineNo) {
179 returnValue = new String[1];
180 returnValue[0] = line(startLineNo - 1).substring(startColNo,
181 endColNo + 1);
182 }
183 else {
184 returnValue = new String[endLineNo - startLineNo + 1];
185 returnValue[0] = line(startLineNo - 1).substring(startColNo);
186 for (int i = startLineNo; i < endLineNo; i++) {
187 returnValue[i - startLineNo + 1] = line(i);
188 }
189 returnValue[returnValue.length - 1] = line(endLineNo - 1).substring(0,
190 endColNo + 1);
191 }
192 return returnValue;
193 }
194
195 /**
196 * Get a single-line.
197 * For internal use only, as getText().get(lineNo) is just as
198 * suitable for external use and avoids method duplication.
199 *
200 * @param lineNo the number of the line to get
201 * @return the corresponding line, without terminator
202 * @throws IndexOutOfBoundsException if lineNo is invalid
203 */
204 private String line(int lineNo) {
205 return text.get(lineNo);
206 }
207
208 /**
209 * Returns the Javadoc comment before the specified line.
210 * A return value of {@code null} means there is no such comment.
211 *
212 * @param lineNoBefore the line number to check before
213 * @return the Javadoc comment, or {@code null} if none
214 **/
215 public TextBlock getJavadocBefore(int lineNoBefore) {
216 // Lines start at 1 to the callers perspective, so need to take off 2
217 int lineNo = lineNoBefore - 2;
218
219 // skip blank lines
220 while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
221 lineNo--;
222 }
223
224 return javadocComments.get(lineNo);
225 }
226
227 /**
228 * Checks if the specified line is blank.
229 *
230 * @param lineNo the line number to check
231 * @return if the specified line consists only of tabs and spaces.
232 **/
233 public boolean lineIsBlank(int lineNo) {
234 return CommonUtil.isBlank(line(lineNo));
235 }
236
237 /**
238 * Checks if the specified line is a single-line comment without code.
239 *
240 * @param lineNo the line number to check
241 * @return if the specified line consists of only a single-line comment
242 * without code.
243 **/
244 public boolean lineIsComment(int lineNo) {
245 return MATCH_SINGLELINE_COMMENT.matcher(line(lineNo)).matches();
246 }
247
248 /**
249 * Checks if the specified position intersects with a comment.
250 *
251 * @param startLineNo the starting line number
252 * @param startColNo the starting column number
253 * @param endLineNo the ending line number
254 * @param endColNo the ending column number
255 * @return true if the positions intersects with a comment.
256 **/
257 public boolean hasIntersectionWithComment(int startLineNo,
258 int startColNo, int endLineNo, int endColNo) {
259 return hasIntersectionWithBlockComment(startLineNo, startColNo, endLineNo, endColNo)
260 || hasIntersectionWithSingleLineComment(startLineNo, startColNo, endLineNo,
261 endColNo);
262 }
263
264 /**
265 * Checks if the specified position intersects with a block comment.
266 *
267 * @param startLineNo the starting line number
268 * @param startColNo the starting column number
269 * @param endLineNo the ending line number
270 * @param endColNo the ending column number
271 * @return true if the positions intersects with a block comment.
272 */
273 private boolean hasIntersectionWithBlockComment(int startLineNo, int startColNo,
274 int endLineNo, int endColNo) {
275 // Check C comments (all comments should be checked)
276 final Collection<List<TextBlock>> values = clangComments.values();
277 return values.stream()
278 .flatMap(List::stream)
279 .anyMatch(comment -> comment.intersects(startLineNo, startColNo, endLineNo, endColNo));
280 }
281
282 /**
283 * Checks if the specified position intersects with a single-line comment.
284 *
285 * @param startLineNo the starting line number
286 * @param startColNo the starting column number
287 * @param endLineNo the ending line number
288 * @param endColNo the ending column number
289 * @return true if the positions intersects with a single-line comment.
290 */
291 private boolean hasIntersectionWithSingleLineComment(int startLineNo, int startColNo,
292 int endLineNo, int endColNo) {
293 boolean hasIntersection = false;
294 // Check CPP comments (line searching is possible)
295 for (int lineNumber = startLineNo; lineNumber <= endLineNo;
296 lineNumber++) {
297 final TextBlock comment = cppComments.get(lineNumber);
298 if (comment != null && comment.intersects(startLineNo, startColNo,
299 endLineNo, endColNo)) {
300 hasIntersection = true;
301 break;
302 }
303 }
304 return hasIntersection;
305 }
306
307 /**
308 * Returns a map of all the single-line comments. The key is a line number,
309 * the value is the comment {@link TextBlock} at the line.
310 *
311 * @return the Map of comments
312 */
313 public Map<Integer, TextBlock> getSingleLineComments() {
314 return Collections.unmodifiableMap(cppComments);
315 }
316
317 /**
318 * Returns a map of all block comments. The key is the line number, the
319 * value is a {@link List} of block comment {@link TextBlock}s
320 * that start at that line.
321 *
322 * @return the map of comments
323 */
324 public Map<Integer, List<TextBlock>> getBlockComments() {
325 return Collections.unmodifiableMap(clangComments);
326 }
327
328 /**
329 * Checks if the current file is a package-info.java file.
330 *
331 * @return true if the package file.
332 * @deprecated use {@link CheckUtil#isPackageInfo(String)} for the same functionality,
333 * or use {@link AbstractCheck#getFilePath()} to process your own standards.
334 */
335 @Deprecated(since = "10.2")
336 public boolean inPackageInfo() {
337 return "package-info.java".equals(text.getFile().getName());
338 }
339 }