001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2024 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.whitespace;
021
022import java.util.Locale;
023
024import com.puppycrawl.tools.checkstyle.StatelessCheck;
025import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
026import com.puppycrawl.tools.checkstyle.api.DetailAST;
027import com.puppycrawl.tools.checkstyle.api.TokenTypes;
028import com.puppycrawl.tools.checkstyle.utils.CodePointUtil;
029import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
030
031/**
032 * <div>
033 * Checks the padding between the identifier of a method definition,
034 * constructor definition, method call, constructor invocation, record, or record pattern;
035 * and the left parenthesis of the parameter list.
036 * That is, if the identifier and left parenthesis are on the same line,
037 * checks whether a space is required immediately after the identifier or
038 * such a space is forbidden.
039 * If they are not on the same line, reports a violation, unless configured to
040 * allow line breaks. To allow linebreaks after the identifier, set property
041 * {@code allowLineBreaks} to {@code true}.
042 * </div>
043 * <ul>
044 * <li>
045 * Property {@code allowLineBreaks} - Allow a line break between the identifier
046 * and left parenthesis.
047 * Type is {@code boolean}.
048 * Default value is {@code false}.
049 * </li>
050 * <li>
051 * Property {@code option} - Specify policy on how to pad method parameter.
052 * Type is {@code com.puppycrawl.tools.checkstyle.checks.whitespace.PadOption}.
053 * Default value is {@code nospace}.
054 * </li>
055 * <li>
056 * Property {@code tokens} - tokens to check
057 * Type is {@code java.lang.String[]}.
058 * Validation type is {@code tokenSet}.
059 * Default value is:
060 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">
061 * CTOR_DEF</a>,
062 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_CALL">
063 * CTOR_CALL</a>,
064 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_NEW">
065 * LITERAL_NEW</a>,
066 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_CALL">
067 * METHOD_CALL</a>,
068 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">
069 * METHOD_DEF</a>,
070 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#SUPER_CTOR_CALL">
071 * SUPER_CTOR_CALL</a>,
072 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
073 * ENUM_CONSTANT_DEF</a>,
074 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
075 * RECORD_DEF</a>,
076 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_PATTERN_DEF">
077 * RECORD_PATTERN_DEF</a>.
078 * </li>
079 * </ul>
080 *
081 * <p>
082 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
083 * </p>
084 *
085 * <p>
086 * Violation Message Keys:
087 * </p>
088 * <ul>
089 * <li>
090 * {@code line.previous}
091 * </li>
092 * <li>
093 * {@code ws.notPreceded}
094 * </li>
095 * <li>
096 * {@code ws.preceded}
097 * </li>
098 * </ul>
099 *
100 * @since 3.4
101 */
102
103@StatelessCheck
104public class MethodParamPadCheck
105    extends AbstractCheck {
106
107    /**
108     * A key is pointing to the warning message text in "messages.properties"
109     * file.
110     */
111    public static final String MSG_LINE_PREVIOUS = "line.previous";
112
113    /**
114     * A key is pointing to the warning message text in "messages.properties"
115     * file.
116     */
117    public static final String MSG_WS_PRECEDED = "ws.preceded";
118
119    /**
120     * A key is pointing to the warning message text in "messages.properties"
121     * file.
122     */
123    public static final String MSG_WS_NOT_PRECEDED = "ws.notPreceded";
124
125    /**
126     * Allow a line break between the identifier and left parenthesis.
127     */
128    private boolean allowLineBreaks;
129
130    /** Specify policy on how to pad method parameter. */
131    private PadOption option = PadOption.NOSPACE;
132
133    @Override
134    public int[] getDefaultTokens() {
135        return getAcceptableTokens();
136    }
137
138    @Override
139    public int[] getAcceptableTokens() {
140        return new int[] {
141            TokenTypes.CTOR_DEF,
142            TokenTypes.CTOR_CALL,
143            TokenTypes.LITERAL_NEW,
144            TokenTypes.METHOD_CALL,
145            TokenTypes.METHOD_DEF,
146            TokenTypes.SUPER_CTOR_CALL,
147            TokenTypes.ENUM_CONSTANT_DEF,
148            TokenTypes.RECORD_DEF,
149            TokenTypes.RECORD_PATTERN_DEF,
150        };
151    }
152
153    @Override
154    public int[] getRequiredTokens() {
155        return CommonUtil.EMPTY_INT_ARRAY;
156    }
157
158    @Override
159    public void visitToken(DetailAST ast) {
160        final DetailAST parenAST;
161        if (ast.getType() == TokenTypes.METHOD_CALL) {
162            parenAST = ast;
163        }
164        else {
165            parenAST = ast.findFirstToken(TokenTypes.LPAREN);
166            // array construction => parenAST == null
167        }
168
169        if (parenAST != null) {
170            final int[] line = getLineCodePoints(parenAST.getLineNo() - 1);
171            if (CodePointUtil.hasWhitespaceBefore(parenAST.getColumnNo(), line)) {
172                if (!allowLineBreaks) {
173                    log(parenAST, MSG_LINE_PREVIOUS, parenAST.getText());
174                }
175            }
176            else {
177                final int before = parenAST.getColumnNo() - 1;
178                if (option == PadOption.NOSPACE
179                    && CommonUtil.isCodePointWhitespace(line, before)) {
180                    log(parenAST, MSG_WS_PRECEDED, parenAST.getText());
181                }
182                else if (option == PadOption.SPACE
183                         && !CommonUtil.isCodePointWhitespace(line, before)) {
184                    log(parenAST, MSG_WS_NOT_PRECEDED, parenAST.getText());
185                }
186            }
187        }
188    }
189
190    /**
191     * Setter to allow a line break between the identifier and left parenthesis.
192     *
193     * @param allowLineBreaks whether whitespace should be
194     *     flagged at line breaks.
195     * @since 3.4
196     */
197    public void setAllowLineBreaks(boolean allowLineBreaks) {
198        this.allowLineBreaks = allowLineBreaks;
199    }
200
201    /**
202     * Setter to specify policy on how to pad method parameter.
203     *
204     * @param optionStr string to decode option from
205     * @throws IllegalArgumentException if unable to decode
206     * @since 3.4
207     */
208    public void setOption(String optionStr) {
209        option = PadOption.valueOf(optionStr.trim().toUpperCase(Locale.ENGLISH));
210    }
211
212}