Source code

001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2019 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 format specified
029 * by the format property. 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 * @since 3.0
165 */
166public class LocalVariableNameCheck
167    extends AbstractNameCheck {
168
169    /**
170     * Allow one character variable name in
171     * <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html">
172     * initialization expressions</a>
173     * in FOR loop if one char variable name is prohibited by {@code format} regexp. For example:
174     * <pre>
175     * for (int i = 1; i &lt; 10; i++) { // OK
176     *     int j = 1; // violation
177     * }
178     * for (int K = 1; K &lt; 10; K++) { // OK
179     *     int j = 1; // violation
180     * }
181     * List list = new ArrayList();
182     * for (Object o : list) { // OK
183     *     int j = 1; // violation
184     * }
185     * for (Object O : list) { // OK
186     *     int j = 1; // violation
187     * }
188     * </pre>
189     */
190    private boolean allowOneCharVarInForLoop;
191
192    /** Creates a new {@code LocalVariableNameCheck} instance. */
193    public LocalVariableNameCheck() {
194        super("^[a-z][a-zA-Z0-9]*$");
195    }
196
197    /**
198     * Setter to allow one character variable name in
199     * <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/for.html">
200     * initialization expressions</a>
201     * in FOR loop if one char variable name is prohibited by {@code format} regexp. For example:
202     * <pre>
203     * for (int i = 1; i &lt; 10; i++) { // OK
204     *     int j = 1; // violation
205     * }
206     * for (int K = 1; K &lt; 10; K++) { // OK
207     *     int j = 1; // violation
208     * }
209     * List list = new ArrayList();
210     * for (Object o : list) { // OK
211     *     int j = 1; // violation
212     * }
213     * for (Object O : list) { // OK
214     *     int j = 1; // violation
215     * }
216     * </pre>
217     *
218     * @param allow Flag for allowing or not one character name in FOR loop.
219     */
220    public final void setAllowOneCharVarInForLoop(boolean allow) {
221        allowOneCharVarInForLoop = allow;
222    }
223
224    @Override
225    public int[] getDefaultTokens() {
226        return getRequiredTokens();
227    }
228
229    @Override
230    public int[] getAcceptableTokens() {
231        return getRequiredTokens();
232    }
233
234    @Override
235    public int[] getRequiredTokens() {
236        return new int[] {
237            TokenTypes.VARIABLE_DEF,
238        };
239    }
240
241    @Override
242    protected final boolean mustCheckName(DetailAST ast) {
243        final boolean result;
244        if (allowOneCharVarInForLoop && isForLoopVariable(ast)) {
245            final String variableName = ast.findFirstToken(TokenTypes.IDENT).getText();
246            result = variableName.length() != 1;
247        }
248        else {
249            final DetailAST modifiersAST = ast.findFirstToken(TokenTypes.MODIFIERS);
250            final boolean isFinal = modifiersAST.findFirstToken(TokenTypes.FINAL) != null;
251            result = !isFinal && ScopeUtil.isLocalVariableDef(ast);
252        }
253        return result;
254    }
255
256    /**
257     * Checks if a variable is the loop's one.
258     * @param variableDef variable definition.
259     * @return true if a variable is the loop's one.
260     */
261    private static boolean isForLoopVariable(DetailAST variableDef) {
262        final int parentType = variableDef.getParent().getType();
263        return parentType == TokenTypes.FOR_INIT
264                || parentType == TokenTypes.FOR_EACH_CLAUSE;
265    }
266
267}