Source code

001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2020 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.naming;
021
022import com.puppycrawl.tools.checkstyle.api.DetailAST;
023import com.puppycrawl.tools.checkstyle.api.TokenTypes;
024import com.puppycrawl.tools.checkstyle.utils.ScopeUtil;
025
026/**
027 * <p>
028 * Checks that local, non-{@code final} variable names conform to a specified pattern.
029 * A catch parameter is considered to be
030 * a local variable.
031 * </p>
032 * <ul>
033 * <li>
034 * Property {@code format} - Specifies valid identifiers. Default value is
035 * {@code "^[a-z][a-zA-Z0-9]*$"}.
036 * </li>
037 * <li>
038 * Property {@code allowOneCharVarInForLoop} - Allow one character variable name in
039 * <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html">
040 * initialization expressions</a>
041 * in FOR loop if one char variable name is prohibited by {@code format} regexp. For example:
042 * <pre>
043 * for (int i = 1; i &lt; 10; i++) { // OK
044 *     int j = 1; // violation
045 * }
046 * for (int K = 1; K &lt; 10; K++) { // OK
047 *     int j = 1; // violation
048 * }
049 * List list = new ArrayList();
050 * for (Object o : list) { // OK
051 *     int j = 1; // violation
052 * }
053 * for (Object O : list) { // OK
054 *     int j = 1; // violation
055 * }
056 * </pre>
057 * Default value is {@code false}.
058 * </li>
059 * </ul>
060 * <p>
061 * An example of how to configure the check is:
062 * </p>
063 * <pre>
064 * &lt;module name="LocalVariableName"/&gt;
065 * </pre>
066 * <p>Code Example:</p>
067 * <pre>
068 * class MyClass {
069 *   void MyMethod() {
070 *     for (int var = 1; var &lt; 10; var++) {} // OK
071 *     for (int VAR = 1; VAR &lt; 10; VAR++) {} // violation, name 'VAR' must match
072 *                                           // pattern '^[a-z][a-zA-Z0-9]*$'
073 *     for (int i = 1; i &lt; 10; i++) {} // OK
074 *     for (int var_1 = 0; var_1 &lt; 10; var_1++) {} // violation, name 'var_1' must match
075 *                                                    // pattern '^[a-z][a-zA-Z0-9]*$'
076 *   }
077 * }
078 * </pre>
079 * <p>
080 * An example of how to configure the check for names that begin with a lower
081 * case letter, followed by letters, digits, and underscores is:
082 * </p>
083 * <pre>
084 * &lt;module name="LocalVariableName"&gt;
085 *   &lt;property name="format" value="^[a-z](_?[a-zA-Z0-9]+)*$"/&gt;
086 * &lt;/module&gt;
087 * </pre>
088 * <p>Code Example:</p>
089 * <pre>
090 * class MyClass {
091 *   void MyMethod() {
092 *     for (int var = 1; var &lt; 10; var++) {} // OK
093 *     for (int VAR = 1; VAR &lt; 10; VAR++) {} // violation, name 'VAR' must match
094 *                                              // pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
095 *     for (int i = 1; i &lt; 10; i++) {} // OK
096 *     for (int var_1 = 0; var_1 &lt; 10; var_1++) {} // OK
097 *   }
098 * }
099 * </pre>
100 * <p>
101 * An example of one character variable name in
102 * initialization expression(like "i") in FOR loop:
103 * </p>
104 * <pre>
105 * for(int i = 1; i &lt; 10; i++) {}
106 * for(int K = 1; K &lt; 10; K++) {}
107 * List list = new ArrayList();
108 * for (Object o : list) {}
109 * for (Object O : list) {}
110 * </pre>
111 * <p>
112 * An example of how to configure the check to allow one character variable name in
113 * <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html">
114 * initialization expressions</a> in FOR loop, where regexp allows 2 or more chars:
115 * </p>
116 * <pre>
117 * &lt;module name="LocalVariableName"&gt;
118 *   &lt;property name="format" value="^[a-z][_a-zA-Z0-9]+$"/&gt;
119 *   &lt;property name="allowOneCharVarInForLoop" value="true"/&gt;
120 * &lt;/module&gt;
121 * </pre>
122 * <p>Code Example:</p>
123 * <pre>
124 * class MyClass {
125 *   void MyMethod() {
126 *     int good = 1;
127 *     int g = 0; // violation
128 *     for (int v = 1; v &lt; 10; v++) { // OK
129 *         int a = 1; // violation
130 *     }
131 *     for (int V = 1; V &lt; 10; V++) { // OK
132 *         int I = 1; // violation
133 *     }
134 *     List list = new ArrayList();
135 *     for (Object o : list) { // OK
136 *         String a = ""; // violation
137 *     }
138 *     for (Object O : list) { // OK
139 *         String A = ""; // violation
140 *     }
141 *   }
142 * }
143 * </pre>
144 * <p>
145 * An example of how to configure the check to that all variables have 3 or more chars in name:
146 * </p>
147 * <pre>
148 * &lt;module name="LocalVariableName"&gt;
149 *   &lt;property name="format" value="^[a-z][_a-zA-Z0-9]{2,}$"/&gt;
150 * &lt;/module&gt;
151 * </pre>
152 * <p>Code Example:</p>
153 * <pre>
154 * class MyClass {
155 *   void MyMethod() {
156 *     int goodName = 0;
157 *     int i = 1; // violation
158 *     for (int var = 1; var &lt; 10; var++) { //OK
159 *       int j = 1; // violation
160 *     }
161 *   }
162 * }
163 * </pre>
164 *
165 * @since 3.0
166 */
167public class LocalVariableNameCheck
168    extends AbstractNameCheck {
169
170    /**
171     * Allow one character variable name in
172     * <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html">
173     * initialization expressions</a>
174     * in FOR loop if one char variable name is prohibited by {@code format} regexp. For example:
175     * <pre>
176     * for (int i = 1; i &lt; 10; i++) { // OK
177     *     int j = 1; // violation
178     * }
179     * for (int K = 1; K &lt; 10; K++) { // OK
180     *     int j = 1; // violation
181     * }
182     * List list = new ArrayList();
183     * for (Object o : list) { // OK
184     *     int j = 1; // violation
185     * }
186     * for (Object O : list) { // OK
187     *     int j = 1; // violation
188     * }
189     * </pre>
190     */
191    private boolean allowOneCharVarInForLoop;
192
193    /** Creates a new {@code LocalVariableNameCheck} instance. */
194    public LocalVariableNameCheck() {
195        super("^[a-z][a-zA-Z0-9]*$");
196    }
197
198    /**
199     * Setter to allow one character variable name in
200     * <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html">
201     * initialization expressions</a>
202     * in FOR loop if one char variable name is prohibited by {@code format} regexp. For example:
203     * <pre>
204     * for (int i = 1; i &lt; 10; i++) { // OK
205     *     int j = 1; // violation
206     * }
207     * for (int K = 1; K &lt; 10; K++) { // OK
208     *     int j = 1; // violation
209     * }
210     * List list = new ArrayList();
211     * for (Object o : list) { // OK
212     *     int j = 1; // violation
213     * }
214     * for (Object O : list) { // OK
215     *     int j = 1; // violation
216     * }
217     * </pre>
218     *
219     * @param allow Flag for allowing or not one character name in FOR loop.
220     */
221    public final void setAllowOneCharVarInForLoop(boolean allow) {
222        allowOneCharVarInForLoop = allow;
223    }
224
225    @Override
226    public int[] getDefaultTokens() {
227        return getRequiredTokens();
228    }
229
230    @Override
231    public int[] getAcceptableTokens() {
232        return getRequiredTokens();
233    }
234
235    @Override
236    public int[] getRequiredTokens() {
237        return new int[] {
238            TokenTypes.VARIABLE_DEF,
239        };
240    }
241
242    @Override
243    protected final boolean mustCheckName(DetailAST ast) {
244        final boolean result;
245        if (allowOneCharVarInForLoop && isForLoopVariable(ast)) {
246            final String variableName = ast.findFirstToken(TokenTypes.IDENT).getText();
247            result = variableName.length() != 1;
248        }
249        else {
250            final DetailAST modifiersAST = ast.findFirstToken(TokenTypes.MODIFIERS);
251            final boolean isFinal = modifiersAST.findFirstToken(TokenTypes.FINAL) != null;
252            result = !isFinal && ScopeUtil.isLocalVariableDef(ast);
253        }
254        return result;
255    }
256
257    /**
258     * Checks if a variable is the loop's one.
259     *
260     * @param variableDef variable definition.
261     * @return true if a variable is the loop's one.
262     */
263    private static boolean isForLoopVariable(DetailAST variableDef) {
264        final int parentType = variableDef.getParent().getType();
265        return parentType == TokenTypes.FOR_INIT
266                || parentType == TokenTypes.FOR_EACH_CLAUSE;
267    }
268
269}