///////////////////////////////////////////////////////////////////////////////////////////////
   // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
   // Copyright (C) 2001-2026 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.ArrayList;
  import java.util.List;
  import java.util.regex.Pattern;
  
  import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
  import com.puppycrawl.tools.checkstyle.PropertyType;
  import com.puppycrawl.tools.checkstyle.XdocsPropertyType;
  import com.puppycrawl.tools.checkstyle.api.DetailNode;
  import com.puppycrawl.tools.checkstyle.api.JavadocCommentsTokenTypes;
  import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
  import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
  
  /**
   * <div>
   * Checks that Javadoc comments do not match a configured regular expression.
   * </div>
   *
   * <p>
   * The check can operate on raw Javadoc source or on the text visible to readers.
   * Raw matching includes Javadoc tags, HTML tags, HTML attributes, and formatting
   * characters. Visible-text matching ignores markup and matches only Javadoc text content.
   * </p>
   *
   * @since 13.10.0
   */
  @FileStatefulCheck
  public class JavadocRegexpCheck extends AbstractJavadocCheck {
  
      /**
       * A key is pointing to the warning message text in "messages.properties" file.
       */
      public static final String MSG_JAVADOC_REGEXP = "javadoc.regexp.match";
  
      /**
       * Text fragments visible to readers of the current Javadoc comment.
       */
      private final List<String> visibleText = new ArrayList<>();
  
      /**
       * Specify the regular expression to match forbidden Javadoc content.
       */
      @XdocsPropertyType(PropertyType.PATTERN)
      private String format = "^$";
  
      /**
       * Control whether to ignore case when matching.
       */
      private boolean ignoreCase;
  
      /**
       * Control whether to ignore Javadoc and HTML markup when matching.
       */
      private boolean ignoreMarkup;
  
      /**
       * Line number of the previous collected text node.
       */
      private int previousTextLineNumber;
  
      /**
       * Creates a new {@code JavadocRegexpCheck} instance.
       */
      public JavadocRegexpCheck() {
          // no code by default
      }
  
      /**
       * Setter to specify the regular expression to match forbidden Javadoc content.
       *
       * @param format regular expression to match forbidden Javadoc content.
       * @since 13.10.0
       */
      public void setFormat(String format) {
          this.format = format;
      }
  
      /**
       * Setter to control whether to ignore case when matching.
      *
      * @param ignoreCase whether to ignore case when matching.
      * @since 13.10.0
      */
     public void setIgnoreCase(boolean ignoreCase) {
         this.ignoreCase = ignoreCase;
     }
 
     /**
      * Setter to control whether to ignore Javadoc and HTML markup when matching.
      *
      * @param ignoreMarkup whether to ignore Javadoc and HTML markup when matching.
      * @since 13.10.0
      */
     public void setIgnoreMarkup(boolean ignoreMarkup) {
         this.ignoreMarkup = ignoreMarkup;
     }
 
     @Override
     public int[] getRequiredJavadocTokens() {
         return new int[] {
             JavadocCommentsTokenTypes.TEXT,
         };
     }
 
     @Override
     public int[] getDefaultJavadocTokens() {
         return getRequiredJavadocTokens();
     }
 
     @Override
     public void beginJavadocTree(DetailNode rootAst) {
         visibleText.clear();
     }
 
     @Override
     public void visitJavadocToken(DetailNode ast) {
         if (!isIgnoredText(ast)) {
             appendVisibleText(ast);
         }
     }
 
     @Override
     public void finishJavadocTree(DetailNode rootAst) {
         final String content;
         if (ignoreMarkup) {
             content = String.join("", visibleText);
         }
         else {
             content = JavadocUtil.getJavadocCommentContent(getBlockCommentAst());
         }
 
         final Pattern regexp = createRegexp();
         if (regexp.matcher(content).find()) {
             log(rootAst.getLineNumber(), MSG_JAVADOC_REGEXP, regexp.pattern());
         }
     }
 
     /**
      * Creates the regexp based on {@link #format} and {@link #ignoreCase}.
      *
      * @return pattern used to find forbidden content.
      */
     private Pattern createRegexp() {
         final int compileFlags;
         if (ignoreCase) {
             compileFlags = Pattern.CASE_INSENSITIVE;
         }
         else {
             compileFlags = 0;
         }
         return CommonUtil.createPattern(format, compileFlags);
     }
 
     /**
      * Appends visible text from a Javadoc text node.
      *
      * @param textNode text node to append.
      */
     private void appendVisibleText(DetailNode textNode) {
         if (!visibleText.isEmpty() && previousTextLineNumber < textNode.getLineNumber()) {
             visibleText.add(" ");
         }
         visibleText.add(textNode.getText());
         previousTextLineNumber = textNode.getLineNumber();
     }
 
     /**
      * Checks whether a text node belongs to a non-rendered HTML comment.
      *
      * @param textNode text node to check.
      * @return {@code true} if the text node should be ignored.
      */
     private static boolean isIgnoredText(DetailNode textNode) {
         boolean result = false;
         DetailNode current = textNode;
 
         while (current != null) {
             if (current.getType() == JavadocCommentsTokenTypes.HTML_COMMENT) {
                 result = true;
                 break;
             }
             current = current.getParent();
         }
 
         return result;
     }
 
 }