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