///////////////////////////////////////////////////////////////////////////////////////////////
   // 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.blocks;
  
  import java.util.Locale;
  import java.util.Optional;
  
  import javax.annotation.Nullable;
  
  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.TokenTypes;
  import com.puppycrawl.tools.checkstyle.utils.CodePointUtil;
  import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
  import com.puppycrawl.tools.checkstyle.utils.NullUtil;
  import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
  
  /**
   * <div>
   * Checks for the placement of left curly braces (<code>'{'</code>) for code blocks.
   * </div>
   *
   * @since 3.0
   */
  @StatelessCheck
  public class LeftCurlyCheck extends AbstractCheck {
  
      /**
       * A key is pointing to the warning message text in "messages.properties" file.
       */
      public static final String MSG_KEY_LINE_NEW = "line.new";
  
      /**
       * A key is pointing to the warning message text in "messages.properties" file.
       */
      public static final String MSG_KEY_LINE_PREVIOUS = "line.previous";
  
      /**
       * A key is pointing to the warning message text in "messages.properties" file.
       */
      public static final String MSG_KEY_LINE_BREAK_AFTER = "line.break.after";
  
      /** Open curly brace literal. */
      private static final String OPEN_CURLY_BRACE = "{";
  
      /** Allow to ignore enums when left curly brace policy is EOL. */
      private boolean ignoreEnums = true;
  
      /**
       * Specify the policy on placement of a left curly brace (<code>'{'</code>).
       */
      private LeftCurlyOption option = LeftCurlyOption.EOL;
  
      /**
       * Creates a new {@code LeftCurlyCheck} instance.
       */
      public LeftCurlyCheck() {
          // no code by default
      }
  
      /**
       * Setter to specify the policy on placement of a left curly brace (<code>'{'</code>).
       *
       * @param optionStr string to decode option from
       * @throws IllegalArgumentException if unable to decode
       * @since 3.0
       */
      public void setOption(String optionStr) {
          option = LeftCurlyOption.valueOf(optionStr.trim().toUpperCase(Locale.ENGLISH));
      }
  
      /**
       * Setter to allow to ignore enums when left curly brace policy is EOL.
       *
       * @param ignoreEnums check's option for ignoring enums.
       * @since 6.9
       */
      public void setIgnoreEnums(boolean ignoreEnums) {
          this.ignoreEnums = ignoreEnums;
      }
  
     @Override
     public int[] getDefaultTokens() {
         return getAcceptableTokens();
     }
 
     @Override
     public int[] getAcceptableTokens() {
         return new int[] {
             TokenTypes.ANNOTATION_DEF,
             TokenTypes.CLASS_DEF,
             TokenTypes.CTOR_DEF,
             TokenTypes.ENUM_CONSTANT_DEF,
             TokenTypes.ENUM_DEF,
             TokenTypes.INTERFACE_DEF,
             TokenTypes.LAMBDA,
             TokenTypes.LITERAL_CASE,
             TokenTypes.LITERAL_CATCH,
             TokenTypes.LITERAL_DEFAULT,
             TokenTypes.LITERAL_DO,
             TokenTypes.LITERAL_ELSE,
             TokenTypes.LITERAL_FINALLY,
             TokenTypes.LITERAL_FOR,
             TokenTypes.LITERAL_IF,
             TokenTypes.LITERAL_SWITCH,
             TokenTypes.LITERAL_SYNCHRONIZED,
             TokenTypes.LITERAL_TRY,
             TokenTypes.LITERAL_WHILE,
             TokenTypes.METHOD_DEF,
             TokenTypes.OBJBLOCK,
             TokenTypes.STATIC_INIT,
             TokenTypes.RECORD_DEF,
             TokenTypes.COMPACT_CTOR_DEF,
             TokenTypes.SWITCH_RULE,
         };
     }
 
     @Override
     public int[] getRequiredTokens() {
         return CommonUtil.EMPTY_INT_ARRAY;
     }
 
     /**
      * Visits token.
      *
      * @param ast the token to process
      * @noinspection SwitchStatementWithTooManyBranches
      * @noinspectionreason SwitchStatementWithTooManyBranches - we cannot reduce
      *      the number of branches in this switch statement, since many tokens
      *      require specific methods to find the first left curly
      */
     @Override
     public void visitToken(DetailAST ast) {
         final DetailAST startToken;
         final DetailAST brace = switch (ast.getType()) {
             case TokenTypes.CTOR_DEF, TokenTypes.METHOD_DEF, TokenTypes.COMPACT_CTOR_DEF -> {
                 startToken = skipModifierAnnotations(ast);
                 yield ast.findFirstToken(TokenTypes.SLIST);
             }
             case TokenTypes.INTERFACE_DEF, TokenTypes.CLASS_DEF, TokenTypes.ANNOTATION_DEF,
                  TokenTypes.ENUM_DEF, TokenTypes.ENUM_CONSTANT_DEF, TokenTypes.RECORD_DEF -> {
                 startToken = skipModifierAnnotations(ast);
                 yield ast.findFirstToken(TokenTypes.OBJBLOCK);
             }
             case TokenTypes.LITERAL_WHILE, TokenTypes.LITERAL_CATCH,
                  TokenTypes.LITERAL_SYNCHRONIZED, TokenTypes.LITERAL_FOR, TokenTypes.LITERAL_TRY,
                  TokenTypes.LITERAL_FINALLY, TokenTypes.LITERAL_DO,
                  TokenTypes.LITERAL_IF, TokenTypes.STATIC_INIT, TokenTypes.LAMBDA,
                  TokenTypes.SWITCH_RULE -> {
                 startToken = ast;
                 yield ast.findFirstToken(TokenTypes.SLIST);
             }
             case TokenTypes.LITERAL_ELSE -> {
                 startToken = ast;
                 yield getBraceAsFirstChild(ast);
             }
             case TokenTypes.LITERAL_CASE, TokenTypes.LITERAL_DEFAULT -> {
                 startToken = ast;
                 yield getBraceFromSwitchMember(ast);
             }
             case TokenTypes.OBJBLOCK -> {
                 startToken = ast;
                 DetailAST braceToken = null;
                 if (ast.getParent().getType() == TokenTypes.LITERAL_NEW) {
                     braceToken = ast;
                 }
                 yield braceToken;
             }
             default -> {
                 // only expected DEFAULT Token is LITERAL_SWITCH
                 startToken = ast;
                 yield ast.findFirstToken(TokenTypes.LCURLY);
             }
         };
 
         if (brace != null) {
             verifyBrace(brace, startToken);
         }
     }
 
     /**
      * Gets the brace of a switch statement/ expression member.
      *
      * @param ast {@code DetailAST}.
      * @return {@code DetailAST} if the first child is {@code TokenTypes.SLIST},
      *     {@code null} otherwise.
      */
     @Nullable
     private static DetailAST getBraceFromSwitchMember(DetailAST ast) {
         final DetailAST brace;
         final DetailAST parent = ast.getParent();
         if (parent.getType() == TokenTypes.SWITCH_RULE) {
             brace = parent.findFirstToken(TokenTypes.SLIST);
         }
         else {
             brace = getBraceAsFirstChild(ast.getNextSibling());
         }
         return brace;
     }
 
     /**
      * Gets a SLIST if it is the first child of the AST.
      *
      * @param ast {@code DetailAST}.
      * @return {@code DetailAST} if the first child is {@code TokenTypes.SLIST},
      *     {@code null} otherwise.
      */
     @Nullable
     private static DetailAST getBraceAsFirstChild(DetailAST ast) {
         DetailAST brace = null;
         if (ast != null) {
             final DetailAST candidate = ast.getFirstChild();
             if (candidate != null && candidate.getType() == TokenTypes.SLIST) {
                 brace = candidate;
             }
         }
         return brace;
     }
 
     /**
      * Skip all {@code TokenTypes.ANNOTATION}s to the first non-annotation.
      *
      * @param ast {@code DetailAST}.
      * @return {@code DetailAST} or null if there are no annotations.
      */
     private static DetailAST skipModifierAnnotations(DetailAST ast) {
         DetailAST resultNode = ast;
         final DetailAST modifiers = ast.findFirstToken(TokenTypes.MODIFIERS);
 
         if (modifiers != null) {
             resultNode = findLastAnnotation(modifiers)
                     .map(annotation -> {
                         final DetailAST nextNode;
                         if (annotation.getNextSibling() == null) {
                             nextNode = modifiers.getNextSibling();
                         }
                         else {
                             nextNode = annotation.getNextSibling();
                         }
                         return nextNode;
                     })
                     .orElse(resultNode);
         }
         return resultNode;
     }
 
     /**
      * Find the last token of type {@code TokenTypes.ANNOTATION} under the given set of modifiers.
      *
      * @param modifiers {@code DetailAST}.
      * @return Optional containing the last annotation, if found.
      */
     private static Optional<DetailAST> findLastAnnotation(DetailAST modifiers) {
         DetailAST annotation = modifiers.findFirstToken(TokenTypes.ANNOTATION);
         while (annotation != null && annotation.getNextSibling() != null
                && annotation.getNextSibling().getType() == TokenTypes.ANNOTATION) {
             annotation = annotation.getNextSibling();
         }
         return Optional.ofNullable(annotation);
     }
 
     /**
      * Verifies that a specified left curly brace is placed correctly
      * according to policy, using the code points of the line containing the brace.
      *
      * @param brace token for left curly brace
      * @param startToken token for start of expression
      */
     private void verifyBrace(final DetailAST brace,
                              final DetailAST startToken) {
         final int[] braceLine = getLineCodePoints(brace.getLineNo() - 1);
 
         // Check for being told to ignore, or have '{}' which is a special case
         if (braceLine.length <= brace.getColumnNo() + 1
                 || braceLine[brace.getColumnNo() + 1] != '}') {
             if (option == LeftCurlyOption.NL) {
                 if (!CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
                     log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
                 }
             }
             else if (option == LeftCurlyOption.EOL) {
                 validateEol(startToken, brace);
             }
             else if (option == LeftCurlyOption.NL_OR_SINGLELINE) {
                 validateNlOrSingleline(brace, braceLine);
             }
             else if (!TokenUtil.areOnSameLine(startToken, brace)) {
                 validateNewLinePosition(brace, startToken, braceLine);
             }
         }
     }
 
     /**
      * Validate NL_OR_SINGLELINE case. A brace that opens a block which ends on
      * the same line is allowed to stay at the end of that line, otherwise the NL rule is applied.
      *
      * @param brace brace AST
      * @param braceLine line content
      */
     private void validateNlOrSingleline(DetailAST brace, int... braceLine) {
         if (!isSingleLineBlock(brace)
                 && !CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
             log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
         }
     }
 
     /**
      * Checks whether the block opened by the given left curly brace ends on the
      * same line, that is, its matching right curly brace is on that same line.
      *
      * @param brace token for left curly brace
      * @return true if the whole block fits on a single line
      */
     private static boolean isSingleLineBlock(DetailAST brace) {
         final DetailAST block;
         if (brace.getType() == TokenTypes.LCURLY) {
             block = brace.getParent();
         }
         else {
             block = brace;
         }
         return TokenUtil.areOnSameLine(brace, block.getLastChild());
     }
 
     /**
      * Validate EOL case.
      *
      * @param startToken token for start of expression.
      * @param brace brace AST
      */
     private void validateEol(DetailAST startToken, DetailAST brace) {
         if (!isOnLineWithBlockPreviousToken(brace)) {
             log(brace, MSG_KEY_LINE_PREVIOUS, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
         }
         if (!hasLineBreakAfter(startToken, brace)) {
             log(brace, MSG_KEY_LINE_BREAK_AFTER, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
         }
     }
 
     /**
      * Validate token on new Line position.
      *
      * @param brace brace AST
      * @param startToken start Token
      * @param braceLine code points of the line containing the brace
      */
     private void validateNewLinePosition(DetailAST brace, DetailAST startToken, int... braceLine) {
         // not on the same line
         if (startToken.getLineNo() + 1 == brace.getLineNo()) {
             if (CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
                 log(brace, MSG_KEY_LINE_PREVIOUS, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
             }
             else {
                 log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
             }
         }
         else if (!CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
             log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
         }
     }
 
     /**
      * Checks if left curly has line break after.
      *
      * @param startToken token for start of expression.
      * @param curlyBrace
      *        Left curly token.
      * @return
      *        True, left curly has line break after.
      */
     private boolean hasLineBreakAfter(DetailAST startToken, DetailAST curlyBrace) {
         DetailAST nextToken = curlyBrace.getNextSibling();
         if (curlyBrace.getType() == TokenTypes.OBJBLOCK
                 && (!ignoreEnums || startToken.getType() != TokenTypes.ENUM_DEF)) {
             nextToken = NullUtil.notNull(curlyBrace.findFirstToken(TokenTypes.LCURLY))
                     .getNextSibling();
 
         }
         else if (curlyBrace.getType() == TokenTypes.SLIST) {
             nextToken = curlyBrace.getFirstChild();
         }
         if (nextToken != null && nextToken.getType() == TokenTypes.INSTANCE_INIT
                 && startToken.getType() == TokenTypes.OBJBLOCK) {
             nextToken = null;
         }
         return nextToken == null
                 || nextToken.getType() == TokenTypes.RCURLY
                 || !TokenUtil.areOnSameLine(curlyBrace, nextToken);
     }
 
     /**
      * Checks if the given brace is with a token of a block.
      *
      * @param brace the brace token to check
      * @return true if the brace is on the same line as its previous token
      */
     private static boolean isOnLineWithBlockPreviousToken(DetailAST brace) {
         DetailAST endToken = brace.getPreviousSibling();
         if (brace.getParent().getType() == TokenTypes.SLIST) {
             endToken = brace.getParent().getPreviousSibling();
         }
         while (endToken != null && endToken.hasChildren()) {
             endToken = endToken.getLastChild();
         }
         if (endToken == null || brace.getParent().getType() == TokenTypes.LAMBDA) {
             endToken = brace.getParent();
         }
         return TokenUtil.areOnSameLine(brace, endToken);
     }
 
 }