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.checks.javadoc.utils;
21
22 import java.util.ArrayList;
23 import java.util.List;
24 import java.util.regex.Matcher;
25 import java.util.regex.Pattern;
26
27 import com.puppycrawl.tools.checkstyle.api.LineColumn;
28
29 /**
30 * Tools for extracting inline tags from Javadoc comments.
31 *
32 */
33 public final class InlineTagUtil {
34
35 /**
36 * Inline tag pattern.
37 */
38 private static final Pattern INLINE_TAG_PATTERN = Pattern.compile(
39 "\\{@(\\p{Alpha}+)\\b(.*?)}", Pattern.DOTALL);
40
41 /** Pattern to recognize leading "*" characters in Javadoc. */
42 private static final Pattern JAVADOC_PREFIX_PATTERN = Pattern.compile(
43 "^\\s*\\*", Pattern.MULTILINE);
44
45 /** Pattern matching whitespace, used by {@link InlineTagUtil#collapseWhitespace(String)}. */
46 private static final Pattern WHITESPACE_PATTERN = Pattern.compile("\\s+");
47
48 /** Pattern matching a newline. */
49 private static final Pattern NEWLINE_PATTERN = Pattern.compile("\\n");
50
51 /** Line feed character. */
52 private static final char LINE_FEED = '\n';
53
54 /** Carriage return character. */
55 private static final char CARRIAGE_RETURN = '\r';
56
57 /** Prevent instantiation. */
58 private InlineTagUtil() {
59 }
60
61 /**
62 * Extract inline Javadoc tags from the given comment.
63 *
64 * @param lines The Javadoc comment (as lines).
65 * @return The extracted inline Javadoc tags.
66 * @throws IllegalArgumentException when comment lines contain newlines
67 */
68 public static List<TagInfo> extractInlineTags(String... lines) {
69 for (String line : lines) {
70 if (line.indexOf(LINE_FEED) != -1 || line.indexOf(CARRIAGE_RETURN) != -1) {
71 throw new IllegalArgumentException("comment lines cannot contain newlines");
72 }
73 }
74
75 final String commentText = convertLinesToString(lines);
76 final Matcher inlineTagMatcher = INLINE_TAG_PATTERN.matcher(commentText);
77
78 final List<TagInfo> tags = new ArrayList<>();
79
80 while (inlineTagMatcher.find()) {
81 final String tagName = inlineTagMatcher.group(1);
82
83 // Remove the leading asterisks (in case the tag spans a line) and collapse
84 // the whitespace.
85 String matchedTagValue = inlineTagMatcher.group(2);
86 matchedTagValue = removeLeadingJavaDoc(matchedTagValue);
87 matchedTagValue = collapseWhitespace(matchedTagValue);
88
89 final String tagValue = matchedTagValue;
90
91 final int startIndex = inlineTagMatcher.start(1);
92 final LineColumn position = getLineColumnOfIndex(commentText,
93 // correct start index offset
94 startIndex - 1);
95
96 tags.add(new TagInfo(tagName, tagValue, position));
97 }
98
99 return tags;
100 }
101
102 /**
103 * Convert array of string to single String.
104 *
105 * @param lines A number of lines, in order.
106 * @return The lines, joined together with newlines, as a single string.
107 */
108 private static String convertLinesToString(String... lines) {
109 final StringBuilder builder = new StringBuilder(1024);
110 for (String line : lines) {
111 builder.append(line);
112 builder.append(LINE_FEED);
113 }
114 return builder.toString();
115 }
116
117 /**
118 * Get LineColumn from string till index.
119 *
120 * @param source Source string.
121 * @param index An index into the string.
122 * @return A position in the source representing what line and column that index appears on.
123 */
124 private static LineColumn getLineColumnOfIndex(String source, int index) {
125 final String precedingText = source.subSequence(0, index).toString();
126 final String[] precedingLines = NEWLINE_PATTERN.split(precedingText);
127 final String lastLine = precedingLines[precedingLines.length - 1];
128 return new LineColumn(precedingLines.length, lastLine.length());
129 }
130
131 /**
132 * Collapse whitespaces.
133 *
134 * @param str Source string.
135 * @return The given string with all whitespace collapsed.
136 */
137 private static String collapseWhitespace(String str) {
138 final Matcher matcher = WHITESPACE_PATTERN.matcher(str);
139 return matcher.replaceAll(" ").trim();
140 }
141
142 /**
143 * Remove leading JavaDoc.
144 *
145 * @param source A string to remove leading Javadoc from.
146 * @return The given string with leading Javadoc "*" characters from each line removed.
147 */
148 private static String removeLeadingJavaDoc(String source) {
149 final Matcher matcher = JAVADOC_PREFIX_PATTERN.matcher(source);
150 return matcher.replaceAll("");
151 }
152
153 }