001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2017 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 java.util.Arrays;
023import java.util.HashSet;
024import java.util.LinkedList;
025import java.util.List;
026import java.util.Set;
027import java.util.stream.Collectors;
028
029import com.puppycrawl.tools.checkstyle.StatelessCheck;
030import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
031import com.puppycrawl.tools.checkstyle.api.DetailAST;
032import com.puppycrawl.tools.checkstyle.api.TokenTypes;
033import com.puppycrawl.tools.checkstyle.utils.CheckUtils;
034import com.puppycrawl.tools.checkstyle.utils.CommonUtils;
035
036/**
037 * <p>
038 * The Check validate abbreviations(consecutive capital letters) length in
039 * identifier name, it also allows to enforce camel case naming. Please read more at
040 * <a href=
041 *  "http://checkstyle.sourceforge.net/reports/google-java-style-20170228.html#s5.3-camel-case">
042 * Google Style Guide</a> to get to know how to avoid long abbreviations in names.
043 * </p>
044 * <p>
045 * {@code allowedAbbreviationLength} specifies how many consecutive capital letters are
046 * allowed in the identifier.
047 * A value of <i>3</i> indicates that up to 4 consecutive capital letters are allowed,
048 * one after the other, before a violation is printed. The identifier 'MyTEST' would be
049 * allowed, but 'MyTESTS' would not be.
050 * A value of <i>0</i> indicates that only 1 consecutive capital letter is allowed. This
051 * is what should be used to enforce strict camel casing. The identifier 'MyTest' would
052 * be allowed, but 'MyTEst' would not be.
053 * </p>
054 * <p>
055 * Option {@code allowedAbbreviationLength} indicates on the allowed amount of capital
056 * letters in abbreviations in the classes, interfaces,
057 * variables and methods names. Default value is '3'.
058 * </p>
059 * <p>
060 * Option {@code allowedAbbreviations} - list of abbreviations that
061 * must be skipped for checking. Abbreviations should be separated by comma,
062 * no spaces are allowed.
063 * </p>
064 * <p>
065 * Option {@code ignoreFinal} allow to skip variables with {@code final} modifier.
066 * Default value is {@code true}.
067 * </p>
068 * <p>
069 * Option {@code ignoreStatic} allow to skip variables with {@code static} modifier.
070 * Default value is {@code true}.
071 * </p>
072 * <p>
073 * Option {@code ignoreOverriddenMethod} - Allows to
074 * ignore methods tagged with {@code @Override} annotation
075 * (that usually mean inherited name). Default value is {@code true}.
076 * </p>
077 * Default configuration
078 * <pre>
079 * &lt;module name="AbbreviationAsWordInName" /&gt;
080 * </pre>
081 * <p>
082 * To configure to check variables and classes identifiers, do not ignore
083 * variables with static modifier
084 * and allow no abbreviations (enforce camel case phrase) but allow XML and URL abbreviations.
085 * </p>
086 * <pre>
087 * &lt;module name="AbbreviationAsWordInName"&gt;
088 *     &lt;property name="tokens" value="VARIABLE_DEF,CLASS_DEF"/&gt;
089 *     &lt;property name="ignoreStatic" value="false"/&gt;
090 *     &lt;property name="allowedAbbreviationLength" value="1"/&gt;
091 *     &lt;property name="allowedAbbreviations" value="XML,URL"/&gt;
092 * &lt;/module&gt;
093 * </pre>
094 *
095 * @author Roman Ivanov, Daniil Yaroslvtsev, Baratali Izmailov
096 */
097@StatelessCheck
098public class AbbreviationAsWordInNameCheck extends AbstractCheck {
099
100    /**
101     * Warning message key.
102     */
103    public static final String MSG_KEY = "abbreviation.as.word";
104
105    /**
106     * The default value of "allowedAbbreviationLength" option.
107     */
108    private static final int DEFAULT_ALLOWED_ABBREVIATIONS_LENGTH = 3;
109
110    /**
111     * Variable indicates on the allowed amount of capital letters in
112     * abbreviations in the classes, interfaces, variables and methods names.
113     */
114    private int allowedAbbreviationLength =
115            DEFAULT_ALLOWED_ABBREVIATIONS_LENGTH;
116
117    /**
118     * Set of allowed abbreviation to ignore in check.
119     */
120    private Set<String> allowedAbbreviations = new HashSet<>();
121
122    /** Allows to ignore variables with 'final' modifier. */
123    private boolean ignoreFinal = true;
124
125    /** Allows to ignore variables with 'static' modifier. */
126    private boolean ignoreStatic = true;
127
128    /** Allows to ignore methods with '@Override' annotation. */
129    private boolean ignoreOverriddenMethods = true;
130
131    /**
132     * Sets ignore option for variables with 'final' modifier.
133     * @param ignoreFinal
134     *        Defines if ignore variables with 'final' modifier or not.
135     */
136    public void setIgnoreFinal(boolean ignoreFinal) {
137        this.ignoreFinal = ignoreFinal;
138    }
139
140    /**
141     * Sets ignore option for variables with 'static' modifier.
142     * @param ignoreStatic
143     *        Defines if ignore variables with 'static' modifier or not.
144     */
145    public void setIgnoreStatic(boolean ignoreStatic) {
146        this.ignoreStatic = ignoreStatic;
147    }
148
149    /**
150     * Sets ignore option for methods with "@Override" annotation.
151     * @param ignoreOverriddenMethods
152     *        Defines if ignore methods with "@Override" annotation or not.
153     */
154    public void setIgnoreOverriddenMethods(boolean ignoreOverriddenMethods) {
155        this.ignoreOverriddenMethods = ignoreOverriddenMethods;
156    }
157
158    /**
159     * Allowed abbreviation length in names.
160     * @param allowedAbbreviationLength
161     *            amount of allowed capital letters in abbreviation.
162     */
163    public void setAllowedAbbreviationLength(int allowedAbbreviationLength) {
164        this.allowedAbbreviationLength = allowedAbbreviationLength;
165    }
166
167    /**
168     * Set a list of abbreviations that must be skipped for checking.
169     * Abbreviations should be separated by comma, no spaces is allowed.
170     * @param allowedAbbreviations
171     *        an string of abbreviations that must be skipped from checking,
172     *        each abbreviation separated by comma.
173     */
174    public void setAllowedAbbreviations(String... allowedAbbreviations) {
175        if (allowedAbbreviations != null) {
176            this.allowedAbbreviations =
177                Arrays.stream(allowedAbbreviations).collect(Collectors.toSet());
178        }
179    }
180
181    @Override
182    public int[] getDefaultTokens() {
183        return new int[] {
184            TokenTypes.CLASS_DEF,
185            TokenTypes.INTERFACE_DEF,
186            TokenTypes.ENUM_DEF,
187            TokenTypes.ANNOTATION_DEF,
188            TokenTypes.ANNOTATION_FIELD_DEF,
189            TokenTypes.PARAMETER_DEF,
190            TokenTypes.VARIABLE_DEF,
191            TokenTypes.METHOD_DEF,
192        };
193    }
194
195    @Override
196    public int[] getAcceptableTokens() {
197        return new int[] {
198            TokenTypes.CLASS_DEF,
199            TokenTypes.INTERFACE_DEF,
200            TokenTypes.ENUM_DEF,
201            TokenTypes.ANNOTATION_DEF,
202            TokenTypes.ANNOTATION_FIELD_DEF,
203            TokenTypes.PARAMETER_DEF,
204            TokenTypes.VARIABLE_DEF,
205            TokenTypes.METHOD_DEF,
206            TokenTypes.ENUM_CONSTANT_DEF,
207        };
208    }
209
210    @Override
211    public int[] getRequiredTokens() {
212        return CommonUtils.EMPTY_INT_ARRAY;
213    }
214
215    @Override
216    public void visitToken(DetailAST ast) {
217
218        if (!isIgnoreSituation(ast)) {
219
220            final DetailAST nameAst = ast.findFirstToken(TokenTypes.IDENT);
221            final String typeName = nameAst.getText();
222
223            final String abbr = getDisallowedAbbreviation(typeName);
224            if (abbr != null) {
225                log(nameAst.getLineNo(), MSG_KEY, typeName, allowedAbbreviationLength + 1);
226            }
227        }
228    }
229
230    /**
231     * Checks if it is an ignore situation.
232     * @param ast input DetailAST node.
233     * @return true if it is an ignore situation found for given input DetailAST
234     *         node.
235     * @noinspection SimplifiableIfStatement
236     */
237    private boolean isIgnoreSituation(DetailAST ast) {
238        final DetailAST modifiers = ast.getFirstChild();
239
240        final boolean result;
241        if (ast.getType() == TokenTypes.VARIABLE_DEF) {
242            if ((ignoreFinal || ignoreStatic)
243                    && isInterfaceDeclaration(ast)) {
244                // field declarations in interface are static/final
245                result = true;
246            }
247            else {
248                result = ignoreFinal
249                          && modifiers.findFirstToken(TokenTypes.FINAL) != null
250                    || ignoreStatic
251                        && modifiers.findFirstToken(TokenTypes.LITERAL_STATIC) != null;
252            }
253        }
254        else if (ast.getType() == TokenTypes.METHOD_DEF) {
255            result = ignoreOverriddenMethods && hasOverrideAnnotation(modifiers);
256        }
257        else {
258            result = CheckUtils.isReceiverParameter(ast);
259        }
260        return result;
261    }
262
263    /**
264     * Check that variable definition in interface or @interface definition.
265     * @param variableDefAst variable definition.
266     * @return true if variable definition(variableDefAst) is in interface
267     *     or @interface definition.
268     */
269    private static boolean isInterfaceDeclaration(DetailAST variableDefAst) {
270        boolean result = false;
271        final DetailAST astBlock = variableDefAst.getParent();
272        final DetailAST astParent2 = astBlock.getParent();
273
274        if (astParent2.getType() == TokenTypes.INTERFACE_DEF
275                || astParent2.getType() == TokenTypes.ANNOTATION_DEF) {
276            result = true;
277        }
278        return result;
279    }
280
281    /**
282     * Checks that the method has "@Override" annotation.
283     * @param methodModifiersAST
284     *        A DetailAST nod is related to the given method modifiers
285     *        (MODIFIERS type).
286     * @return true if method has "@Override" annotation.
287     */
288    private static boolean hasOverrideAnnotation(DetailAST methodModifiersAST) {
289        boolean result = false;
290        for (DetailAST child : getChildren(methodModifiersAST)) {
291            if (child.getType() == TokenTypes.ANNOTATION) {
292                final DetailAST annotationIdent = child.findFirstToken(TokenTypes.IDENT);
293
294                if (annotationIdent != null && "Override".equals(annotationIdent.getText())) {
295                    result = true;
296                    break;
297                }
298            }
299        }
300        return result;
301    }
302
303    /**
304     * Gets the disallowed abbreviation contained in given String.
305     * @param str
306     *        the given String.
307     * @return the disallowed abbreviation contained in given String as a
308     *         separate String.
309     */
310    private String getDisallowedAbbreviation(String str) {
311        int beginIndex = 0;
312        boolean abbrStarted = false;
313        String result = null;
314
315        for (int index = 0; index < str.length(); index++) {
316            final char symbol = str.charAt(index);
317
318            if (Character.isUpperCase(symbol)) {
319                if (!abbrStarted) {
320                    abbrStarted = true;
321                    beginIndex = index;
322                }
323            }
324            else if (abbrStarted) {
325                abbrStarted = false;
326
327                final int endIndex = index - 1;
328                // -1 as a first capital is usually beginning of next word
329                result = getAbbreviationIfIllegal(str, beginIndex, endIndex);
330                if (result != null) {
331                    break;
332                }
333                beginIndex = -1;
334            }
335        }
336        // if abbreviation at the end of name and it is not single character (example: scaleX)
337        if (abbrStarted && beginIndex != str.length() - 1) {
338            final int endIndex = str.length();
339            result = getAbbreviationIfIllegal(str, beginIndex, endIndex);
340        }
341        return result;
342    }
343
344    /**
345     * Get Abbreviation if it is illegal.
346     * @param str name
347     * @param beginIndex begin index
348     * @param endIndex end index
349     * @return true is abbreviation is bigger that required and not in ignore list
350     */
351    private String getAbbreviationIfIllegal(String str, int beginIndex, int endIndex) {
352        String result = null;
353        final int abbrLength = endIndex - beginIndex;
354        if (abbrLength > allowedAbbreviationLength) {
355            final String abbr = str.substring(beginIndex, endIndex);
356            if (!allowedAbbreviations.contains(abbr)) {
357                result = abbr;
358            }
359        }
360        return result;
361    }
362
363    /**
364     * Gets all the children which are one level below on the current DetailAST
365     * parent node.
366     * @param node
367     *        Current parent node.
368     * @return The list of children one level below on the current parent node.
369     */
370    private static List<DetailAST> getChildren(final DetailAST node) {
371        final List<DetailAST> result = new LinkedList<>();
372        DetailAST curNode = node.getFirstChild();
373        while (curNode != null) {
374            result.add(curNode);
375            curNode = curNode.getNextSibling();
376        }
377        return result;
378    }
379
380}