////////////////////////////////////////////////////////////////////////////////
   // checkstyle: Checks Java source code for adherence to a set of rules.
   // Copyright (C) 2001-2019 the original author or authors.
   //
   // This library is free software; you can redistribute it and/or
   // modify it under the terms of the GNU Lesser General Public
   // License as published by the Free Software Foundation; either
   // version 2.1 of the License, or (at your option) any later version.
   //
  // This library is distributed in the hope that it will be useful,
  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  // Lesser General Public License for more details.
  //
  // You should have received a copy of the GNU Lesser General Public
  // License along with this library; if not, write to the Free Software
  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  ////////////////////////////////////////////////////////////////////////////////
  
  package com.puppycrawl.tools.checkstyle.checks.javadoc;
  
  import java.util.regex.Matcher;
  import java.util.regex.Pattern;
  
  import com.puppycrawl.tools.checkstyle.StatelessCheck;
  import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
  import com.puppycrawl.tools.checkstyle.api.DetailAST;
  import com.puppycrawl.tools.checkstyle.api.FileContents;
  import com.puppycrawl.tools.checkstyle.api.SeverityLevel;
  import com.puppycrawl.tools.checkstyle.api.TextBlock;
  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
  
  /**
   * <p>
   * Outputs a JavaDoc tag as information. Can be used e.g. with the stylesheets
   * that sort the report by author name.
   * To define the format for a tag, set property tagFormat to a
   * regular expression.
   * This check uses two different severity levels. The normal one is used for
   * reporting when the tag is missing. The additional one (tagSeverity) is used
   * for the level of reporting when the tag exists. The default value for
   * tagSeverity is info.
   * </p>
   * <p> An example of how to configure the check for printing author name is:
   *</p>
   * <pre>
   * &lt;module name="WriteTag"&gt;
   *    &lt;property name="tag" value="@author"/&gt;
   *    &lt;property name="tagFormat" value="\S"/&gt;
   * &lt;/module&gt;
   * </pre>
   * <p> An example of how to configure the check to print warnings if an
   * "@incomplete" tag is found, and not print anything if it is not found:
   *</p>
   * <pre>
   * &lt;module name="WriteTag"&gt;
   *    &lt;property name="tag" value="@incomplete"/&gt;
   *    &lt;property name="tagFormat" value="\S"/&gt;
   *    &lt;property name="severity" value="ignore"/&gt;
   *    &lt;property name="tagSeverity" value="warning"/&gt;
   * &lt;/module&gt;
   * </pre>
   *
   */
  @StatelessCheck
  public class WriteTagCheck
      extends AbstractCheck {
  
      /**
       * A key is pointing to the warning message text in "messages.properties"
       * file.
       */
      public static final String MSG_MISSING_TAG = "type.missingTag";
  
      /**
       * A key is pointing to the warning message text in "messages.properties"
       * file.
       */
      public static final String MSG_WRITE_TAG = "javadoc.writeTag";
  
      /**
       * A key is pointing to the warning message text in "messages.properties"
       * file.
       */
      public static final String MSG_TAG_FORMAT = "type.tagFormat";
  
      /** Compiled regexp to match tag. **/
      private Pattern tagRegExp;
      /** Compiled regexp to match tag content. **/
      private Pattern tagFormat;
  
      /** Regexp to match tag. */
      private String tag;
      /** The severity level of found tag reports. */
      private SeverityLevel tagSeverity = SeverityLevel.INFO;
  
      /**
       * Sets the tag to check.
      * @param tag tag to check
      */
     public void setTag(String tag) {
         this.tag = tag;
         tagRegExp = CommonUtil.createPattern(tag + "\\s*(.*$)");
     }
 
     /**
      * Set the tag format.
      * @param pattern a {@code String} value
      */
     public void setTagFormat(Pattern pattern) {
         tagFormat = pattern;
     }
 
     /**
      * Sets the tag severity level.
      *
      * @param severity  The new severity level
      * @see SeverityLevel
      */
     public final void setTagSeverity(SeverityLevel severity) {
         tagSeverity = severity;
     }
 
     @Override
     public int[] getDefaultTokens() {
         return new int[] {TokenTypes.INTERFACE_DEF,
                           TokenTypes.CLASS_DEF,
                           TokenTypes.ENUM_DEF,
                           TokenTypes.ANNOTATION_DEF,
         };
     }
 
     @Override
     public int[] getAcceptableTokens() {
         return new int[] {TokenTypes.INTERFACE_DEF,
                           TokenTypes.CLASS_DEF,
                           TokenTypes.ENUM_DEF,
                           TokenTypes.ANNOTATION_DEF,
                           TokenTypes.METHOD_DEF,
                           TokenTypes.CTOR_DEF,
                           TokenTypes.ENUM_CONSTANT_DEF,
                           TokenTypes.ANNOTATION_FIELD_DEF,
         };
     }
 
     @Override
     public int[] getRequiredTokens() {
         return CommonUtil.EMPTY_INT_ARRAY;
     }
 
     @Override
     public void visitToken(DetailAST ast) {
         final FileContents contents = getFileContents();
         final int lineNo = ast.getLineNo();
         final TextBlock cmt =
             contents.getJavadocBefore(lineNo);
         if (cmt == null) {
             log(lineNo, MSG_MISSING_TAG, tag);
         }
         else {
             checkTag(lineNo, cmt.getText());
         }
     }
 
     /**
      * Verifies that a type definition has a required tag.
      * @param lineNo the line number for the type definition.
      * @param comment the Javadoc comment for the type definition.
      */
     private void checkTag(int lineNo, String... comment) {
         if (tagRegExp != null) {
             boolean hasTag = false;
             for (int i = 0; i < comment.length; i++) {
                 final String commentValue = comment[i];
                 final Matcher matcher = tagRegExp.matcher(commentValue);
                 if (matcher.find()) {
                     hasTag = true;
                     final int contentStart = matcher.start(1);
                     final String content = commentValue.substring(contentStart);
                     if (tagFormat == null || tagFormat.matcher(content).find()) {
                         logTag(lineNo + i - comment.length, tag, content);
                     }
                     else {
                         log(lineNo + i - comment.length, MSG_TAG_FORMAT, tag, tagFormat.pattern());
                     }
                 }
             }
             if (!hasTag) {
                 log(lineNo, MSG_MISSING_TAG, tag);
             }
         }
     }
 
     /**
      * Log a message.
      *
      * @param line the line number where the error was found
      * @param tagName the javadoc tag to be logged
      * @param tagValue the contents of the tag
      *
      * @see java.text.MessageFormat
      */
     private void logTag(int line, String tagName, String tagValue) {
         final String originalSeverity = getSeverity();
         setSeverity(tagSeverity.getName());
 
         log(line, MSG_WRITE_TAG, tagName, tagValue);
 
         setSeverity(originalSeverity);
     }
 
 }