Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2024 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.api;
021
022import java.util.ArrayList;
023import java.util.Collection;
024import java.util.Collections;
025import java.util.HashMap;
026import java.util.List;
027import java.util.Map;
028import java.util.regex.Pattern;
029
030import com.puppycrawl.tools.checkstyle.grammar.CommentListener;
031import com.puppycrawl.tools.checkstyle.utils.CheckUtil;
032import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
033
034/**
035 * Represents the contents of a file.
036 *
037 */
038public final class FileContents implements CommentListener {
039
040    /**
041     * The pattern to match a single-line comment containing only the comment
042     * itself -- no code.
043     */
044    private static final String MATCH_SINGLELINE_COMMENT_PAT = "^\\s*//.*$";
045    /** Compiled regexp to match a single-line comment line. */
046    private static final Pattern MATCH_SINGLELINE_COMMENT = Pattern
047            .compile(MATCH_SINGLELINE_COMMENT_PAT);
048
049    /** The text. */
050    private final FileText text;
051
052    /**
053     * Map of the Javadoc comments indexed on the last line of the comment.
054     * The hack is it assumes that there is only one Javadoc comment per line.
055     */
056    private final Map<Integer, TextBlock> javadocComments = new HashMap<>();
057    /** Map of the C++ comments indexed on the first line of the comment. */
058    private final Map<Integer, TextBlock> cppComments = new HashMap<>();
059
060    /**
061     * Map of the C comments indexed on the first line of the comment to a list
062     * of comments on that line.
063     */
064    private final Map<Integer, List<TextBlock>> clangComments = new HashMap<>();
065
066    /**
067     * Creates a new {@code FileContents} instance.
068     *
069     * @param text the contents of the file
070     */
071    public FileContents(FileText text) {
072        this.text = new FileText(text);
073    }
074
075    /**
076     * Get the full text of the file.
077     *
078     * @return an object containing the full text of the file
079     */
080    public FileText getText() {
081        return new FileText(text);
082    }
083
084    /**
085     * Gets the lines in the file.
086     *
087     * @return the lines in the file
088     */
089    public String[] getLines() {
090        return text.toLinesArray();
091    }
092
093    /**
094     * Get the line from text of the file.
095     *
096     * @param index index of the line
097     * @return line from text of the file
098     */
099    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}