Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2025 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;
023
024import javax.annotation.Nullable;
025
026import com.puppycrawl.tools.checkstyle.StatelessCheck;
027import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
028import com.puppycrawl.tools.checkstyle.api.DetailAST;
029import com.puppycrawl.tools.checkstyle.api.TokenTypes;
030import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
031import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
032
033/**
034 * <div>
035 * Checks for the placement of left curly braces (<code>'{'</code>) for code blocks.
036 * </div>
037 *
038 * <ul>
039 * <li>
040 * Property {@code ignoreEnums} - Allow to ignore enums when left curly brace policy is EOL.
041 * Type is {@code boolean}.
042 * Default value is {@code true}.
043 * </li>
044 * <li>
045 * Property {@code option} - Specify the policy on placement of a left curly brace
046 * (<code>'{'</code>).
047 * Type is {@code com.puppycrawl.tools.checkstyle.checks.blocks.LeftCurlyOption}.
048 * Default value is {@code eol}.
049 * </li>
050 * <li>
051 * Property {@code tokens} - tokens to check
052 * Type is {@code java.lang.String[]}.
053 * Validation type is {@code tokenSet}.
054 * Default value is:
055 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
056 * ANNOTATION_DEF</a>,
057 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">
058 * CLASS_DEF</a>,
059 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">
060 * CTOR_DEF</a>,
061 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
062 * ENUM_CONSTANT_DEF</a>,
063 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
064 * ENUM_DEF</a>,
065 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">
066 * INTERFACE_DEF</a>,
067 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LAMBDA">
068 * LAMBDA</a>,
069 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CASE">
070 * LITERAL_CASE</a>,
071 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">
072 * LITERAL_CATCH</a>,
073 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DEFAULT">
074 * LITERAL_DEFAULT</a>,
075 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">
076 * LITERAL_DO</a>,
077 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">
078 * LITERAL_ELSE</a>,
079 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">
080 * LITERAL_FINALLY</a>,
081 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">
082 * LITERAL_FOR</a>,
083 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">
084 * LITERAL_IF</a>,
085 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SWITCH">
086 * LITERAL_SWITCH</a>,
087 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SYNCHRONIZED">
088 * LITERAL_SYNCHRONIZED</a>,
089 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">
090 * LITERAL_TRY</a>,
091 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">
092 * LITERAL_WHILE</a>,
093 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">
094 * METHOD_DEF</a>,
095 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#OBJBLOCK">
096 * OBJBLOCK</a>,
097 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#STATIC_INIT">
098 * STATIC_INIT</a>,
099 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
100 * RECORD_DEF</a>,
101 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF">
102 * COMPACT_CTOR_DEF</a>.
103 * </li>
104 * </ul>
105 *
106 * <p>
107 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
108 * </p>
109 *
110 * <p>
111 * Violation Message Keys:
112 * </p>
113 * <ul>
114 * <li>
115 * {@code line.break.after}
116 * </li>
117 * <li>
118 * {@code line.new}
119 * </li>
120 * <li>
121 * {@code line.previous}
122 * </li>
123 * </ul>
124 *
125 * @since 3.0
126 */
127@StatelessCheck
128public class LeftCurlyCheck
129    extends AbstractCheck {
130
131    /**
132     * A key is pointing to the warning message text in "messages.properties"
133     * file.
134     */
135    public static final String MSG_KEY_LINE_NEW = "line.new";
136
137    /**
138     * A key is pointing to the warning message text in "messages.properties"
139     * file.
140     */
141    public static final String MSG_KEY_LINE_PREVIOUS = "line.previous";
142
143    /**
144     * A key is pointing to the warning message text in "messages.properties"
145     * file.
146     */
147    public static final String MSG_KEY_LINE_BREAK_AFTER = "line.break.after";
148
149    /** Open curly brace literal. */
150    private static final String OPEN_CURLY_BRACE = "{";
151
152    /** Allow to ignore enums when left curly brace policy is EOL. */
153    private boolean ignoreEnums = true;
154
155    /**
156     * Specify the policy on placement of a left curly brace (<code>'{'</code>).
157     */
158    private LeftCurlyOption option = LeftCurlyOption.EOL;
159
160    /**
161     * Setter to specify the policy on placement of a left curly brace (<code>'{'</code>).
162     *
163     * @param optionStr string to decode option from
164     * @throws IllegalArgumentException if unable to decode
165     * @since 3.0
166     */
167    public void setOption(String optionStr) {
168        option = LeftCurlyOption.valueOf(optionStr.trim().toUpperCase(Locale.ENGLISH));
169    }
170
171    /**
172     * Setter to allow to ignore enums when left curly brace policy is EOL.
173     *
174     * @param ignoreEnums check's option for ignoring enums.
175     * @since 6.9
176     */
177    public void setIgnoreEnums(boolean ignoreEnums) {
178        this.ignoreEnums = ignoreEnums;
179    }
180
181    @Override
182    public int[] getDefaultTokens() {
183        return getAcceptableTokens();
184    }
185
186    @Override
187    public int[] getAcceptableTokens() {
188        return new int[] {
189            TokenTypes.ANNOTATION_DEF,
190            TokenTypes.CLASS_DEF,
191            TokenTypes.CTOR_DEF,
192            TokenTypes.ENUM_CONSTANT_DEF,
193            TokenTypes.ENUM_DEF,
194            TokenTypes.INTERFACE_DEF,
195            TokenTypes.LAMBDA,
196            TokenTypes.LITERAL_CASE,
197            TokenTypes.LITERAL_CATCH,
198            TokenTypes.LITERAL_DEFAULT,
199            TokenTypes.LITERAL_DO,
200            TokenTypes.LITERAL_ELSE,
201            TokenTypes.LITERAL_FINALLY,
202            TokenTypes.LITERAL_FOR,
203            TokenTypes.LITERAL_IF,
204            TokenTypes.LITERAL_SWITCH,
205            TokenTypes.LITERAL_SYNCHRONIZED,
206            TokenTypes.LITERAL_TRY,
207            TokenTypes.LITERAL_WHILE,
208            TokenTypes.METHOD_DEF,
209            TokenTypes.OBJBLOCK,
210            TokenTypes.STATIC_INIT,
211            TokenTypes.RECORD_DEF,
212            TokenTypes.COMPACT_CTOR_DEF,
213        };
214    }
215
216    @Override
217    public int[] getRequiredTokens() {
218        return CommonUtil.EMPTY_INT_ARRAY;
219    }
220
221    /**
222     * Visits token.
223     *
224     * @param ast the token to process
225     * @noinspection SwitchStatementWithTooManyBranches
226     * @noinspectionreason SwitchStatementWithTooManyBranches - we cannot reduce
227     *      the number of branches in this switch statement, since many tokens
228     *      require specific methods to find the first left curly
229     */
230    @Override
231    public void visitToken(DetailAST ast) {
232        final DetailAST startToken;
233        final DetailAST brace = switch (ast.getType()) {
234            case TokenTypes.CTOR_DEF, TokenTypes.METHOD_DEF, TokenTypes.COMPACT_CTOR_DEF -> {
235                startToken = skipModifierAnnotations(ast);
236                yield ast.findFirstToken(TokenTypes.SLIST);
237            }
238            case TokenTypes.INTERFACE_DEF, TokenTypes.CLASS_DEF, TokenTypes.ANNOTATION_DEF,
239                 TokenTypes.ENUM_DEF, TokenTypes.ENUM_CONSTANT_DEF, TokenTypes.RECORD_DEF -> {
240                startToken = skipModifierAnnotations(ast);
241                yield ast.findFirstToken(TokenTypes.OBJBLOCK);
242            }
243            case TokenTypes.LITERAL_WHILE, TokenTypes.LITERAL_CATCH,
244                 TokenTypes.LITERAL_SYNCHRONIZED, TokenTypes.LITERAL_FOR, TokenTypes.LITERAL_TRY,
245                 TokenTypes.LITERAL_FINALLY, TokenTypes.LITERAL_DO,
246                 TokenTypes.LITERAL_IF, TokenTypes.STATIC_INIT, TokenTypes.LAMBDA -> {
247                startToken = ast;
248                yield ast.findFirstToken(TokenTypes.SLIST);
249            }
250            case TokenTypes.LITERAL_ELSE -> {
251                startToken = ast;
252                yield getBraceAsFirstChild(ast);
253            }
254            case TokenTypes.LITERAL_CASE, TokenTypes.LITERAL_DEFAULT -> {
255                startToken = ast;
256                yield getBraceFromSwitchMember(ast);
257            }
258            default -> {
259                // ATTENTION! We have default here, but we expect case TokenTypes.METHOD_DEF,
260                // TokenTypes.LITERAL_FOR, TokenTypes.LITERAL_WHILE, TokenTypes.LITERAL_DO only.
261                // It has been done to improve coverage to 100%. I couldn't replace it with
262                // if-else-if block because code was ugly and didn't pass pmd check.
263
264                startToken = ast;
265                yield ast.findFirstToken(TokenTypes.LCURLY);
266            }
267        };
268
269        if (brace != null) {
270            verifyBrace(brace, startToken);
271        }
272    }
273
274    /**
275     * Gets the brace of a switch statement/ expression member.
276     *
277     * @param ast {@code DetailAST}.
278     * @return {@code DetailAST} if the first child is {@code TokenTypes.SLIST},
279     *     {@code null} otherwise.
280     */
281    @Nullable
282    private static DetailAST getBraceFromSwitchMember(DetailAST ast) {
283        final DetailAST brace;
284        final DetailAST parent = ast.getParent();
285        if (parent.getType() == TokenTypes.SWITCH_RULE) {
286            brace = parent.findFirstToken(TokenTypes.SLIST);
287        }
288        else {
289            brace = getBraceAsFirstChild(ast.getNextSibling());
290        }
291        return brace;
292    }
293
294    /**
295     * Gets a SLIST if it is the first child of the AST.
296     *
297     * @param ast {@code DetailAST}.
298     * @return {@code DetailAST} if the first child is {@code TokenTypes.SLIST},
299     *     {@code null} otherwise.
300     */
301    @Nullable
302    private static DetailAST getBraceAsFirstChild(DetailAST ast) {
303        DetailAST brace = null;
304        if (ast != null) {
305            final DetailAST candidate = ast.getFirstChild();
306            if (candidate != null && candidate.getType() == TokenTypes.SLIST) {
307                brace = candidate;
308            }
309        }
310        return brace;
311    }
312
313    /**
314     * Skip all {@code TokenTypes.ANNOTATION}s to the first non-annotation.
315     *
316     * @param ast {@code DetailAST}.
317     * @return {@code DetailAST}.
318     */
319    private static DetailAST skipModifierAnnotations(DetailAST ast) {
320        DetailAST resultNode = ast;
321        final DetailAST modifiers = ast.findFirstToken(TokenTypes.MODIFIERS);
322
323        if (modifiers != null) {
324            final DetailAST lastAnnotation = findLastAnnotation(modifiers);
325
326            if (lastAnnotation != null) {
327                if (lastAnnotation.getNextSibling() == null) {
328                    resultNode = modifiers.getNextSibling();
329                }
330                else {
331                    resultNode = lastAnnotation.getNextSibling();
332                }
333            }
334        }
335        return resultNode;
336    }
337
338    /**
339     * Find the last token of type {@code TokenTypes.ANNOTATION}
340     * under the given set of modifiers.
341     *
342     * @param modifiers {@code DetailAST}.
343     * @return {@code DetailAST} or null if there are no annotations.
344     */
345    private static DetailAST findLastAnnotation(DetailAST modifiers) {
346        DetailAST annotation = modifiers.findFirstToken(TokenTypes.ANNOTATION);
347        while (annotation != null && annotation.getNextSibling() != null
348               && annotation.getNextSibling().getType() == TokenTypes.ANNOTATION) {
349            annotation = annotation.getNextSibling();
350        }
351        return annotation;
352    }
353
354    /**
355     * Verifies that a specified left curly brace is placed correctly
356     * according to policy.
357     *
358     * @param brace token for left curly brace
359     * @param startToken token for start of expression
360     */
361    private void verifyBrace(final DetailAST brace,
362                             final DetailAST startToken) {
363        final String braceLine = getLine(brace.getLineNo() - 1);
364
365        // Check for being told to ignore, or have '{}' which is a special case
366        if (braceLine.length() <= brace.getColumnNo() + 1
367                || braceLine.charAt(brace.getColumnNo() + 1) != '}') {
368            if (option == LeftCurlyOption.NL) {
369                if (!CommonUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
370                    log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
371                }
372            }
373            else if (option == LeftCurlyOption.EOL) {
374                validateEol(brace, braceLine);
375            }
376            else if (!TokenUtil.areOnSameLine(startToken, brace)) {
377                validateNewLinePosition(brace, startToken, braceLine);
378            }
379        }
380    }
381
382    /**
383     * Validate EOL case.
384     *
385     * @param brace brace AST
386     * @param braceLine line content
387     */
388    private void validateEol(DetailAST brace, String braceLine) {
389        if (CommonUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
390            log(brace, MSG_KEY_LINE_PREVIOUS, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
391        }
392        if (!hasLineBreakAfter(brace)) {
393            log(brace, MSG_KEY_LINE_BREAK_AFTER, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
394        }
395    }
396
397    /**
398     * Validate token on new Line position.
399     *
400     * @param brace brace AST
401     * @param startToken start Token
402     * @param braceLine content of line with Brace
403     */
404    private void validateNewLinePosition(DetailAST brace, DetailAST startToken, String braceLine) {
405        // not on the same line
406        if (startToken.getLineNo() + 1 == brace.getLineNo()) {
407            if (CommonUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
408                log(brace, MSG_KEY_LINE_PREVIOUS, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
409            }
410            else {
411                log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
412            }
413        }
414        else if (!CommonUtil.hasWhitespaceBefore(brace.getColumnNo(), braceLine)) {
415            log(brace, MSG_KEY_LINE_NEW, OPEN_CURLY_BRACE, brace.getColumnNo() + 1);
416        }
417    }
418
419    /**
420     * Checks if left curly has line break after.
421     *
422     * @param leftCurly
423     *        Left curly token.
424     * @return
425     *        True, left curly has line break after.
426     */
427    private boolean hasLineBreakAfter(DetailAST leftCurly) {
428        DetailAST nextToken = null;
429        if (leftCurly.getType() == TokenTypes.SLIST) {
430            nextToken = leftCurly.getFirstChild();
431        }
432        else {
433            if (!ignoreEnums
434                    && leftCurly.getParent().getParent().getType() == TokenTypes.ENUM_DEF) {
435                nextToken = leftCurly.getNextSibling();
436            }
437        }
438        return nextToken == null
439                || nextToken.getType() == TokenTypes.RCURLY
440                || !TokenUtil.areOnSameLine(leftCurly, nextToken);
441    }
442
443}