1 ////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code for adherence to a set of rules.
3 // Copyright (C) 2001-2019 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 String LINE_FEED = "\n";
53
54 /** Carriage return character. */
55 private static final String CARRIAGE_RETURN = "\r";
56
57 /** Prevent instantiation. */
58 private InlineTagUtil() {
59 }
60
61 /**
62 * Extract inline Javadoc tags from the given comment.
63 * @param lines The Javadoc comment (as lines).
64 * @return The extracted inline Javadoc tags.
65 */
66 public static List<TagInfo> extractInlineTags(String... lines) {
67 for (String line : lines) {
68 if (line.contains(LINE_FEED) || line.contains(CARRIAGE_RETURN)) {
69 throw new IllegalArgumentException("comment lines cannot contain newlines");
70 }
71 }
72
73 final String commentText = convertLinesToString(lines);
74 final Matcher inlineTagMatcher = INLINE_TAG_PATTERN.matcher(commentText);
75
76 final List<TagInfo> tags = new ArrayList<>();
77
78 while (inlineTagMatcher.find()) {
79 final String tagName = inlineTagMatcher.group(1);
80
81 // Remove the leading asterisks (in case the tag spans a line) and collapse
82 // the whitespace.
83 String matchedTagValue = inlineTagMatcher.group(2);
84 matchedTagValue = removeLeadingJavaDoc(matchedTagValue);
85 matchedTagValue = collapseWhitespace(matchedTagValue);
86
87 final String tagValue = matchedTagValue;
88
89 final int startIndex = inlineTagMatcher.start(1);
90 final LineColumn position = getLineColumnOfIndex(commentText,
91 // correct start index offset
92 startIndex - 1);
93
94 tags.add(new TagInfo(tagName, tagValue, position));
95 }
96
97 return tags;
98 }
99
100 /**
101 * Convert array of string to single String.
102 * @param lines A number of lines, in order.
103 * @return The lines, joined together with newlines, as a single string.
104 */
105 private static String convertLinesToString(String... lines) {
106 final StringBuilder builder = new StringBuilder(1024);
107 for (String line : lines) {
108 builder.append(line);
109 builder.append(LINE_FEED);
110 }
111 return builder.toString();
112 }
113
114 /**
115 * Get LineColumn from string till index.
116 * @param source Source string.
117 * @param index An index into the string.
118 * @return A position in the source representing what line and column that index appears on.
119 */
120 private static LineColumn getLineColumnOfIndex(String source, int index) {
121 final String precedingText = source.subSequence(0, index).toString();
122 final String[] precedingLines = NEWLINE_PATTERN.split(precedingText);
123 final String lastLine = precedingLines[precedingLines.length - 1];
124 return new LineColumn(precedingLines.length, lastLine.length());
125 }
126
127 /**
128 * Collapse whitespaces.
129 * @param str Source string.
130 * @return The given string with all whitespace collapsed.
131 */
132 private static String collapseWhitespace(String str) {
133 final Matcher matcher = WHITESPACE_PATTERN.matcher(str);
134 return matcher.replaceAll(" ").trim();
135 }
136
137 /**
138 * Remove leading JavaDoc.
139 * @param source A string to remove leading Javadoc from.
140 * @return The given string with leading Javadoc "*" characters from each line removed.
141 */
142 private static String removeLeadingJavaDoc(String source) {
143 final Matcher matcher = JAVADOC_PREFIX_PATTERN.matcher(source);
144 return matcher.replaceAll("");
145 }
146
147 }