001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2026 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.checks.blocks; 021 022import java.util.Locale; 023import java.util.Optional; 024 025import javax.annotation.Nullable; 026 027import com.puppycrawl.tools.checkstyle.StatelessCheck; 028import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 029import com.puppycrawl.tools.checkstyle.api.DetailAST; 030import com.puppycrawl.tools.checkstyle.api.TokenTypes; 031import com.puppycrawl.tools.checkstyle.utils.CodePointUtil; 032import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 033import com.puppycrawl.tools.checkstyle.utils.NullUtil; 034import com.puppycrawl.tools.checkstyle.utils.TokenUtil; 035 036/** 037 * <div> 038 * Checks for the placement of left curly braces (<code>'{'</code>) for code blocks. 039 * </div> 040 * 041 * @since 3.0 042 */ 043@StatelessCheck 044public class LeftCurlyCheck extends AbstractCheck { 045 046 /** 047 * A key is pointing to the warning message text in "messages.properties" file. 048 */ 049 public static final String MSG_KEY_LINE_NEW = "line.new"; 050 051 /** 052 * A key is pointing to the warning message text in "messages.properties" file. 053 */ 054 public static final String MSG_KEY_LINE_PREVIOUS = "line.previous"; 055 056 /** 057 * A key is pointing to the warning message text in "messages.properties" file. 058 */ 059 public static final String MSG_KEY_LINE_BREAK_AFTER = "line.break.after"; 060 061 /** Open curly brace literal. */ 062 private static final String OPEN_CURLY_BRACE = "{"; 063 064 /** Allow to ignore enums when left curly brace policy is EOL. */ 065 private boolean ignoreEnums = true; 066 067 /** 068 * Specify the policy on placement of a left curly brace (<code>'{'</code>). 069 */ 070 private LeftCurlyOption option = LeftCurlyOption.EOL; 071 072 /** 073 * Creates a new {@code LeftCurlyCheck} instance. 074 */ 075 public LeftCurlyCheck() { 076 // no code by default 077 } 078 079 /** 080 * Setter to specify the policy on placement of a left curly brace (<code>'{'</code>). 081 * 082 * @param optionStr string to decode option from 083 * @throws IllegalArgumentException if unable to decode 084 * @since 3.0 085 */ 086 public void setOption(String optionStr) { 087 option = LeftCurlyOption.valueOf(optionStr.trim().toUpperCase(Locale.ENGLISH)); 088 } 089 090 /** 091 * Setter to allow to ignore enums when left curly brace policy is EOL. 092 * 093 * @param ignoreEnums check's option for ignoring enums. 094 * @since 6.9 095 */ 096 public void setIgnoreEnums(boolean ignoreEnums) { 097 this.ignoreEnums = ignoreEnums; 098 } 099 100 @Override 101 public int[] getDefaultTokens() { 102 return getAcceptableTokens(); 103 } 104 105 @Override 106 public int[] getAcceptableTokens() { 107 return new int[] { 108 TokenTypes.ANNOTATION_DEF, 109 TokenTypes.CLASS_DEF, 110 TokenTypes.CTOR_DEF, 111 TokenTypes.ENUM_CONSTANT_DEF, 112 TokenTypes.ENUM_DEF, 113 TokenTypes.INTERFACE_DEF, 114 TokenTypes.LAMBDA, 115 TokenTypes.LITERAL_CASE, 116 TokenTypes.LITERAL_CATCH, 117 TokenTypes.LITERAL_DEFAULT, 118 TokenTypes.LITERAL_DO, 119 TokenTypes.LITERAL_ELSE, 120 TokenTypes.LITERAL_FINALLY, 121 TokenTypes.LITERAL_FOR, 122 TokenTypes.LITERAL_IF, 123 TokenTypes.LITERAL_SWITCH, 124 TokenTypes.LITERAL_SYNCHRONIZED, 125 TokenTypes.LITERAL_TRY, 126 TokenTypes.LITERAL_WHILE, 127 TokenTypes.METHOD_DEF, 128 TokenTypes.OBJBLOCK, 129 TokenTypes.STATIC_INIT, 130 TokenTypes.RECORD_DEF, 131 TokenTypes.COMPACT_CTOR_DEF, 132 TokenTypes.SWITCH_RULE, 133 }; 134 } 135 136 @Override 137 public int[] getRequiredTokens() { 138 return CommonUtil.EMPTY_INT_ARRAY; 139 } 140 141 /** 142 * Visits token. 143 * 144 * @param ast the token to process 145 * @noinspection SwitchStatementWithTooManyBranches 146 * @noinspectionreason SwitchStatementWithTooManyBranches - we cannot reduce 147 * the number of branches in this switch statement, since many tokens 148 * require specific methods to find the first left curly 149 */ 150 @Override 151 public void visitToken(DetailAST ast) { 152 final DetailAST startToken; 153 final DetailAST brace = switch (ast.getType()) { 154 case TokenTypes.CTOR_DEF, TokenTypes.METHOD_DEF, TokenTypes.COMPACT_CTOR_DEF -> { 155 startToken = skipModifierAnnotations(ast); 156 yield ast.findFirstToken(TokenTypes.SLIST); 157 } 158 case TokenTypes.INTERFACE_DEF, TokenTypes.CLASS_DEF, TokenTypes.ANNOTATION_DEF, 159 TokenTypes.ENUM_DEF, TokenTypes.ENUM_CONSTANT_DEF, TokenTypes.RECORD_DEF -> { 160 startToken = skipModifierAnnotations(ast); 161 yield ast.findFirstToken(TokenTypes.OBJBLOCK); 162 } 163 case TokenTypes.LITERAL_WHILE, TokenTypes.LITERAL_CATCH, 164 TokenTypes.LITERAL_SYNCHRONIZED, TokenTypes.LITERAL_FOR, TokenTypes.LITERAL_TRY, 165 TokenTypes.LITERAL_FINALLY, TokenTypes.LITERAL_DO, 166 TokenTypes.LITERAL_IF, TokenTypes.STATIC_INIT, TokenTypes.LAMBDA, 167 TokenTypes.SWITCH_RULE -> { 168 startToken = ast; 169 yield ast.findFirstToken(TokenTypes.SLIST); 170 } 171 case TokenTypes.LITERAL_ELSE -> { 172 startToken = ast; 173 yield getBraceAsFirstChild(ast); 174 } 175 case TokenTypes.LITERAL_CASE, TokenTypes.LITERAL_DEFAULT -> { 176 startToken = ast; 177 yield getBraceFromSwitchMember(ast); 178 } 179 case TokenTypes.OBJBLOCK -> { 180 startToken = ast; 181 DetailAST braceToken = null; 182 if (ast.getParent().getType() == TokenTypes.LITERAL_NEW) { 183 braceToken = ast; 184 } 185 yield braceToken; 186 } 187 default -> { 188 // only expected DEFAULT Token is LITERAL_SWITCH 189 startToken = ast; 190 yield ast.findFirstToken(TokenTypes.LCURLY); 191 } 192 }; 193 194 if (brace != null) { 195 verifyBrace(brace, startToken); 196 } 197 } 198 199 /** 200 * Gets the brace of a switch statement/ expression member. 201 * 202 * @param ast {@code DetailAST}. 203 * @return {@code DetailAST} if the first child is {@code TokenTypes.SLIST}, 204 * {@code null} otherwise. 205 */ 206 @Nullable 207 private static DetailAST getBraceFromSwitchMember(DetailAST ast) { 208 final DetailAST brace; 209 final DetailAST parent = ast.getParent(); 210 if (parent.getType() == TokenTypes.SWITCH_RULE) { 211 brace = parent.findFirstToken(TokenTypes.SLIST); 212 } 213 else { 214 brace = getBraceAsFirstChild(ast.getNextSibling()); 215 } 216 return brace; 217 } 218 219 /** 220 * Gets a SLIST if it is the first child of the AST. 221 * 222 * @param ast {@code DetailAST}. 223 * @return {@code DetailAST} if the first child is {@code TokenTypes.SLIST}, 224 * {@code null} otherwise. 225 */ 226 @Nullable 227 private static DetailAST getBraceAsFirstChild(DetailAST ast) { 228 DetailAST brace = null; 229 if (ast != null) { 230 final DetailAST candidate = ast.getFirstChild(); 231 if (candidate != null && candidate.getType() == TokenTypes.SLIST) { 232 brace = candidate; 233 } 234 } 235 return brace; 236 } 237 238 /** 239 * Skip all {@code TokenTypes.ANNOTATION}s to the first non-annotation. 240 * 241 * @param ast {@code DetailAST}. 242 * @return {@code DetailAST} or null if there are no annotations. 243 */ 244 private static DetailAST skipModifierAnnotations(DetailAST ast) { 245 DetailAST resultNode = ast; 246 final DetailAST modifiers = ast.findFirstToken(TokenTypes.MODIFIERS); 247 248 if (modifiers != null) { 249 resultNode = findLastAnnotation(modifiers) 250 .map(annotation -> { 251 final DetailAST nextNode; 252 if (annotation.getNextSibling() == null) { 253 nextNode = modifiers.getNextSibling(); 254 } 255 else { 256 nextNode = annotation.getNextSibling(); 257 } 258 return nextNode; 259 }) 260 .orElse(resultNode); 261 } 262 return resultNode; 263 } 264 265 /** 266 * Find the last token of type {@code TokenTypes.ANNOTATION} under the given set of modifiers. 267 * 268 * @param modifiers {@code DetailAST}. 269 * @return Optional containing the last annotation, if found. 270 */ 271 private static Optional<DetailAST> findLastAnnotation(DetailAST modifiers) { 272 DetailAST annotation = modifiers.findFirstToken(TokenTypes.ANNOTATION); 273 while (annotation != null && annotation.getNextSibling() != null 274 && annotation.getNextSibling().getType() == TokenTypes.ANNOTATION) { 275 annotation = annotation.getNextSibling(); 276 } 277 return Optional.ofNullable(annotation); 278 } 279 280 /** 281 * Verifies that a specified left curly brace is placed correctly 282 * according to policy, using the code points of the line containing the brace. 283 * 284 * @param brace token for left curly brace 285 * @param startToken token for start of expression 286 */ 287 private void verifyBrace(final DetailAST brace, 288 final DetailAST startToken) { 289 final int[] braceLine = getLineCodePoints(brace.getLineNo() - 1); 290 291 // Check for being told to ignore, or have '{}' which is a special case 292 if (braceLine.length <= brace.getColumnNo() + 1 293 || braceLine[brace.getColumnNo() + 1] != '}') { 294 if (option == LeftCurlyOption.NL) { 295 if (!CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) { 296 log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1); 297 } 298 } 299 else if (option == LeftCurlyOption.EOL) { 300 validateEol(startToken, brace); 301 } 302 else if (option == LeftCurlyOption.NL_OR_SINGLELINE) { 303 validateNlOrSingleline(brace, braceLine); 304 } 305 else if (!TokenUtil.areOnSameLine(startToken, brace)) { 306 validateNewLinePosition(brace, startToken, braceLine); 307 } 308 } 309 } 310 311 /** 312 * Validate NL_OR_SINGLELINE case. A brace that opens a block which ends on 313 * the same line is allowed to stay at the end of that line, otherwise the NL rule is applied. 314 * 315 * @param brace brace AST 316 * @param braceLine line content 317 */ 318 private void validateNlOrSingleline(DetailAST brace, int... braceLine) { 319 if (!isSingleLineBlock(brace) 320 && !CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) { 321 log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1); 322 } 323 } 324 325 /** 326 * Checks whether the block opened by the given left curly brace ends on the 327 * same line, that is, its matching right curly brace is on that same line. 328 * 329 * @param brace token for left curly brace 330 * @return true if the whole block fits on a single line 331 */ 332 private static boolean isSingleLineBlock(DetailAST brace) { 333 final DetailAST block; 334 if (brace.getType() == TokenTypes.LCURLY) { 335 block = brace.getParent(); 336 } 337 else { 338 block = brace; 339 } 340 return TokenUtil.areOnSameLine(brace, block.getLastChild()); 341 } 342 343 /** 344 * Validate EOL case. 345 * 346 * @param startToken token for start of expression. 347 * @param brace brace AST 348 */ 349 private void validateEol(DetailAST startToken, DetailAST brace) { 350 if (!isOnLineWithBlockPreviousToken(brace)) { 351 log(brace, MSG_KEY_LINE_PREVIOUS, OPEN_CURLY_BRACE, brace.getColumnNo() + 1); 352 } 353 if (!hasLineBreakAfter(startToken, brace)) { 354 log(brace, MSG_KEY_LINE_BREAK_AFTER, OPEN_CURLY_BRACE, brace.getColumnNo() + 1); 355 } 356 } 357 358 /** 359 * Validate token on new Line position. 360 * 361 * @param brace brace AST 362 * @param startToken start Token 363 * @param braceLine code points of the line containing the brace 364 */ 365 private void validateNewLinePosition(DetailAST brace, DetailAST startToken, int... braceLine) { 366 // not on the same line 367 if (startToken.getLineNo() + 1 == brace.getLineNo()) { 368 if (CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) { 369 log(brace, MSG_KEY_LINE_PREVIOUS, OPEN_CURLY_BRACE, brace.getColumnNo() + 1); 370 } 371 else { 372 log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1); 373 } 374 } 375 else if (!CodePointUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) { 376 log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1); 377 } 378 } 379 380 /** 381 * Checks if left curly has line break after. 382 * 383 * @param startToken token for start of expression. 384 * @param curlyBrace 385 * Left curly token. 386 * @return 387 * True, left curly has line break after. 388 */ 389 private boolean hasLineBreakAfter(DetailAST startToken, DetailAST curlyBrace) { 390 DetailAST nextToken = curlyBrace.getNextSibling(); 391 if (curlyBrace.getType() == TokenTypes.OBJBLOCK 392 && (!ignoreEnums || startToken.getType() != TokenTypes.ENUM_DEF)) { 393 nextToken = NullUtil.notNull(curlyBrace.findFirstToken(TokenTypes.LCURLY)) 394 .getNextSibling(); 395 396 } 397 else if (curlyBrace.getType() == TokenTypes.SLIST) { 398 nextToken = curlyBrace.getFirstChild(); 399 } 400 if (nextToken != null && nextToken.getType() == TokenTypes.INSTANCE_INIT 401 && startToken.getType() == TokenTypes.OBJBLOCK) { 402 nextToken = null; 403 } 404 return nextToken == null 405 || nextToken.getType() == TokenTypes.RCURLY 406 || !TokenUtil.areOnSameLine(curlyBrace, nextToken); 407 } 408 409 /** 410 * Checks if the given brace is with a token of a block. 411 * 412 * @param brace the brace token to check 413 * @return true if the brace is on the same line as its previous token 414 */ 415 private static boolean isOnLineWithBlockPreviousToken(DetailAST brace) { 416 DetailAST endToken = brace.getPreviousSibling(); 417 if (brace.getParent().getType() == TokenTypes.SLIST) { 418 endToken = brace.getParent().getPreviousSibling(); 419 } 420 while (endToken != null && endToken.hasChildren()) { 421 endToken = endToken.getLastChild(); 422 } 423 if (endToken == null || brace.getParent().getType() == TokenTypes.LAMBDA) { 424 endToken = brace.getParent(); 425 } 426 return TokenUtil.areOnSameLine(brace, endToken); 427 } 428 429}