VariableDeclarationUsageDistanceCheck.java

////////////////////////////////////////////////////////////////////////////////

// checkstyle: Checks Java source code for adherence to a set of rules.

// Copyright (C) 2001-2018 the original author or authors.

//

// This library is free software; you can redistribute it and/or

// modify it under the terms of the GNU Lesser General Public

// License as published by the Free Software Foundation; either

// version 2.1 of the License, or (at your option) any later version.

//

// This library is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

// Lesser General Public License for more details.

//

// You should have received a copy of the GNU Lesser General Public

// License along with this library; if not, write to the Free Software

// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

////////////////////////////////////////////////////////////////////////////////

package com.puppycrawl.tools.checkstyle.checks.coding;

import java.util.AbstractMap.SimpleEntry;

import java.util.ArrayList;

import java.util.List;

import java.util.Map.Entry;

import java.util.regex.Matcher;

import java.util.regex.Pattern;

import antlr.collections.ASTEnumeration;

import com.puppycrawl.tools.checkstyle.StatelessCheck;

import com.puppycrawl.tools.checkstyle.api.AbstractCheck;

import com.puppycrawl.tools.checkstyle.api.DetailAST;

import com.puppycrawl.tools.checkstyle.api.FullIdent;

import com.puppycrawl.tools.checkstyle.api.TokenTypes;

/**

 * <p>

 * Checks the distance between declaration of variable and its first usage.

 * </p>

 * Example #1:

 * <pre>

 *      {@code int count;

 *      a = a + b;

 *      b = a + a;

 *      count = b; // DECLARATION OF VARIABLE 'count'

 *                 // SHOULD BE HERE (distance = 3)}

 * </pre>

 * Example #2:

 * <pre>

 *     {@code int count;

 *     {

 *         a = a + b;

 *         count = b; // DECLARATION OF VARIABLE 'count'

 *                    // SHOULD BE HERE (distance = 2)

 *     }}

 * </pre>

 *

 * <p>

 * Check can detect a block of initialization methods. If a variable is used in

 * such a block and there is no other statements after this variable then distance=1.

 * </p>

 *

 * <p><b>Case #1:</b>

 * <pre>

 * int <b>minutes</b> = 5;

 * Calendar cal = Calendar.getInstance();

 * cal.setTimeInMillis(timeNow);

 * cal.set(Calendar.SECOND, 0);

 * cal.set(Calendar.MILLISECOND, 0);

 * cal.set(Calendar.HOUR_OF_DAY, hh);

 * cal.set(Calendar.MINUTE, <b>minutes</b>);

 *

 * The distance for the variable <b>minutes</b> is 1 even

 * though this variable is used in the fifth method's call.

 * </pre>

 *

 * <p><b>Case #2:</b>

 * <pre>

 * int <b>minutes</b> = 5;

 * Calendar cal = Calendar.getInstance();

 * cal.setTimeInMillis(timeNow);

 * cal.set(Calendar.SECOND, 0);

 * cal.set(Calendar.MILLISECOND, 0);

 * <i>System.out.println(cal);</i>

 * cal.set(Calendar.HOUR_OF_DAY, hh);

 * cal.set(Calendar.MINUTE, <b>minutes</b>);

 *

 * The distance for the variable <b>minutes</b> is 6 because there is one more expression

 * (except the initialization block) between the declaration of this variable and its usage.

 * </pre>

 *

 * <p>There are several additional options to configure the check:

 * <pre>

 * 1. allowedDistance - allows to set a distance

 * between declaration of variable and its first usage.

 * 2. ignoreVariablePattern - allows to set a RegEx pattern for

 * ignoring the distance calculation for variables listed in this pattern.

 * 3. validateBetweenScopes - allows to calculate the distance between

 * declaration of variable and its first usage in the different scopes.

 * 4. ignoreFinal - allows to ignore variables with a 'final' modifier.

 * </pre>

 * ATTENTION!! (Not supported cases)

 * <pre>

 * Case #1:

 * {@code {

 * int c;

 * int a = 3;

 * int b = 2;

 *     {

 *     a = a + b;

 *     c = b;

 *     }

 * }}

 *

 * Distance for variable 'a' = 1;

 * Distance for variable 'b' = 1;

 * Distance for variable 'c' = 2.

 * </pre>

 * As distance by default is 1 the Check doesn't raise warning for variables 'a'

 * and 'b' to move them into the block.

 * <pre>

 * Case #2:

 * {@code int sum = 0;

 * for (int i = 0; i < 20; i++) {

 *     a++;

 *     b--;

 *     sum++;

 *     if (sum > 10) {

 *         res = true;

 *     }

 * }}

 * Distance for variable 'sum' = 3.

 * </pre>

 * <p>

 * As the distance is more then the default one, the Check raises warning for variable

 * 'sum' to move it into the 'for(...)' block. But there is situation when

 * variable 'sum' hasn't to be 0 within each iteration. So, to avoid such

 * warnings you can use Suppression Filter, provided by Checkstyle, for the

 * whole class.

 * </p>

 *

 * <p>

 * An example how to configure this Check:

 * </p>

 * <pre>

 * <module name="VariableDeclarationUsageDistance"/>

 * </pre>

 * <p>

 * An example of how to configure this Check:

 *  - to set the allowed distance to 4;

 *  - to ignore variables with prefix '^temp';

 *  - to force the validation between scopes;

 *  - to check the final variables;

 * </p>

 * <pre>

 * <module name="VariableDeclarationUsageDistance">

 *     <property name="allowedDistance" value="4"/>

 *     <property name="ignoreVariablePattern" value="^temp.*"/>

 *     <property name="validateBetweenScopes" value="true"/>

 *     <property name="ignoreFinal" value="false"/>

 * </module>

 * </pre>

 *

 * @author <a href="mailto:rd.ryly@gmail.com">Ruslan Diachenko</a>

 * @author <a href="mailto:barataliba@gmail.com">Baratali Izmailov</a>

 */

@StatelessCheck

    /**

     * Warning message key.

     */

    public static final String MSG_KEY = "variable.declaration.usage.distance";

    /**

     * Warning message key.

     */

    public static final String MSG_KEY_EXT = "variable.declaration.usage.distance.extend";

    /**

     * Default value of distance between declaration of variable and its first

     * usage.

     */

    private static final int DEFAULT_DISTANCE = 3;

    /** Allowed distance between declaration of variable and its first usage. */

    /**

     * RegExp pattern to ignore distance calculation for variables listed in

     * this pattern.

     */

    /**

     * Allows to calculate distance between declaration of variable and its

     * first usage in different scopes.

     */

    private boolean validateBetweenScopes;

    /** Allows to ignore variables with 'final' modifier. */

    /**

     * Sets an allowed distance between declaration of variable and its first

     * usage.

     * @param allowedDistance

     *        Allowed distance between declaration of variable and its first

     *        usage.

     */

    public void setAllowedDistance(int allowedDistance) {

    /**

     * Sets RegExp pattern to ignore distance calculation for variables listed in this pattern.

     * @param pattern a pattern.

     */

    public void setIgnoreVariablePattern(Pattern pattern) {

    /**

     * Sets option which allows to calculate distance between declaration of

     * variable and its first usage in different scopes.

     * @param validateBetweenScopes

     *        Defines if allow to calculate distance between declaration of

     *        variable and its first usage in different scopes or not.

     */

    public void setValidateBetweenScopes(boolean validateBetweenScopes) {

    /**

     * Sets ignore option for variables with 'final' modifier.

     * @param ignoreFinal

     *        Defines if ignore variables with 'final' modifier or not.

     */

    public void setIgnoreFinal(boolean ignoreFinal) {

    @Override

    public int[] getDefaultTokens() {

    }

    @Override

    public int[] getAcceptableTokens() {

    }

    @Override

    public int[] getRequiredTokens() {

    }

    @Override

    public void visitToken(DetailAST ast) {

                final Entry<DetailAST, Integer> entry;

                }

                else {

                }

                    }

                    else {

                    }

                }

            }

        }

    /**

     * Get name of instance whose method is called.

     * @param methodCallAst

     *        DetailAST of METHOD_CALL.

     * @return name of instance.

     */

    private static String getInstanceName(DetailAST methodCallAst) {

        }

    }

    /**

     * Processes statements until usage of variable to detect sequence of

     * initialization methods.

     * @param variableUsageAst

     *        DetailAST of expression that uses variable named variableName.

     * @param variableName

     *        name of considered variable.

     * @return true if statements between declaration and usage of variable are

     *         initialization methods.

     */

    private static boolean isInitializationSequence(

            DetailAST variableUsageAst, String variableName) {

                && !isUsedVariableDeclarationFound

                && currentSiblingAst != null) {

                case TokenTypes.EXPR:

                        // method is called without instance

                        }

                        // differs from previous instance

                            }

                            else {

                            }

                        }

                    else {

                        // is not method call

                    }

                case TokenTypes.VARIABLE_DEF:

                case TokenTypes.SEMI:

                default:

            }

        }

    }

    /**

     * Calculates distance between declaration of variable and its first usage

     * in single scope.

     * @param semicolonAst

     *        Regular node of Ast which is checked for content of checking

     *        variable.

     * @param variableIdentAst

     *        Variable which distance is calculated for.

     * @return entry which contains expression with variable usage and distance.

     */

    private static Entry<DetailAST, Integer> calculateDistanceInSingleScope(

            DetailAST semicolonAst, DetailAST variableIdentAst) {

                }

                }

            }

        }

        // If variable wasn't used after its declaration, distance is 0.

        }

    }

    /**

     * Returns the distance to variable usage for in the child node.

     * @param childNode child node.

     * @param varIdent variable variable identifier.

     * @param currentDistToVarUsage current distance to the variable usage.

     * @return the distance to variable usage for in the child node.

     */

    private static int getDistToVariableUsageInChildNode(DetailAST childNode, DetailAST varIdent,

                                                         int currentDistToVarUsage) {

        }

            case TokenTypes.VARIABLE_DEF:

            case TokenTypes.SLIST:

            case TokenTypes.LITERAL_FOR:

            case TokenTypes.LITERAL_WHILE:

            case TokenTypes.LITERAL_DO:

            case TokenTypes.LITERAL_IF:

            case TokenTypes.LITERAL_SWITCH:

                }

                else {

                    // variable usage is in inner scope

                    // reset counters, because we can't determine distance

                }

            default:

                }

                else {

                }

        }

    }

    /**

     * Calculates distance between declaration of variable and its first usage

     * in multiple scopes.

     * @param ast

     *        Regular node of Ast which is checked for content of checking

     *        variable.

     * @param variable

     *        Variable which distance is calculated for.

     * @return entry which contains expression with variable usage and distance.

     */

    private static Entry<DetailAST, Integer> calculateDistanceBetweenScopes(

            DetailAST ast, DetailAST variable) {

            // If variable usage exists in a single scope, then look into

            // this scope and count distance until variable usage.

                    case TokenTypes.VARIABLE_DEF:

                    case TokenTypes.EXPR:

                    case TokenTypes.LITERAL_FOR:

                    case TokenTypes.LITERAL_WHILE:

                    case TokenTypes.LITERAL_DO:

                            blockWithVariableUsage, variable);

                    case TokenTypes.LITERAL_IF:

                            blockWithVariableUsage, variable);

                    case TokenTypes.LITERAL_SWITCH:

                            blockWithVariableUsage, variable);

                    case TokenTypes.LITERAL_TRY:

                                variable);

                    default:

                }

                }

                else {

                }

            // If there's no any variable usage, then distance = 0.

            }

            // If variable usage exists in different scopes, then distance =

            // distance until variable first usage.

            else {

            }

    }

    /**

     * Searches variable usages starting from specified statement.

     * @param variableAst Variable that is used.

     * @param statementAst DetailAST to start searching from.

     * @return entry which contains list with found expressions that use the variable

     *     and distance from specified statement to first found expression.

     */

    private static Entry<List<DetailAST>, Integer>

        searchVariableUsageExpressions(final DetailAST variableAst, final DetailAST statementAst) {

                }

                // If expression doesn't contain variable and this variable

                // hasn't been met yet, than distance + 1.

                }

            }

        }

    }

    /**

     * Gets first Ast node inside FOR, WHILE or DO-WHILE blocks if variable

     * usage is met only inside the block (not in its declaration!).

     * @param block

     *        Ast node represents FOR, WHILE or DO-WHILE block.

     * @param variable

     *        Variable which is checked for content in block.

     * @return If variable usage is met only inside the block

     *         (not in its declaration!) than return the first Ast node

     *         of this block, otherwise - null.

     */

    private static DetailAST getFirstNodeInsideForWhileDoWhileBlocks(

            DetailAST block, DetailAST variable) {

            final DetailAST currentNode;

            // Find currentNode for DO-WHILE block.

            }

            // Find currentNode for FOR or WHILE block.

            else {

                // Looking for RPAREN ( ')' ) token to mark the end of operator

                // expression.

            }

            }

            }

        }

    }

    /**

     * Gets first Ast node inside IF block if variable usage is met

     * only inside the block (not in its declaration!).

     * @param block

     *        Ast node represents IF block.

     * @param variable

     *        Variable which is checked for content in block.

     * @return If variable usage is met only inside the block

     *         (not in its declaration!) than return the first Ast node

     *         of this block, otherwise - null.

     */

    private static DetailAST getFirstNodeInsideIfBlock(

            DetailAST block, DetailAST variable) {

                    new ArrayList<>();

                // Checking variable usage inside IF block.

                }

                // Looking into ELSE block, get its first child and analyze it.

                }

                }

            // If IF block doesn't include ELSE than analyze variable usage

            // only inside IF block.

            }

            // If variable usage exists in several related blocks, then

            // firstNodeInsideBlock = null, otherwise if variable usage exists

            // only inside one block, then get node from

            // variableUsageExpressions.

            }

        }

    }

    /**

     * Gets first Ast node inside SWITCH block if variable usage is met

     * only inside the block (not in its declaration!).

     * @param block

     *        Ast node represents SWITCH block.

     * @param variable

     *        Variable which is checked for content in block.

     * @return If variable usage is met only inside the block

     *         (not in its declaration!) than return the first Ast node

     *         of this block, otherwise - null.

     */

    private static DetailAST getFirstNodeInsideSwitchBlock(

            DetailAST block, DetailAST variable) {

                new ArrayList<>();

        // Checking variable usage inside all CASE blocks.

            }

        // If variable usage exists in several related blocks, then

        // firstNodeInsideBlock = null, otherwise if variable usage exists

        // only inside one block, then get node from

        // variableUsageExpressions.

        }

    }

    /**

     * Gets first Ast node inside TRY-CATCH-FINALLY blocks if variable usage is

     * met only inside the block (not in its declaration!).

     * @param block

     *        Ast node represents TRY-CATCH-FINALLY block.

     * @param variable

     *        Variable which is checked for content in block.

     * @return If variable usage is met only inside the block

     *         (not in its declaration!) than return the first Ast node

     *         of this block, otherwise - null.

     */

    private static DetailAST getFirstNodeInsideTryCatchFinallyBlocks(

            DetailAST block, DetailAST variable) {

                new ArrayList<>();

        // Checking variable usage inside TRY block.

        }

        // Switch on CATCH block.

        // Checking variable usage inside all CATCH blocks.

            }

        // Checking variable usage inside FINALLY block.

            }

        }

        // If variable usage exists in several related blocks, then

        // firstNodeInsideBlock = null, otherwise if variable usage exists

        // only inside one block, then get node from

        // variableUsageExpressions.

        }

    }

    /**

     * Checks if variable is in operator declaration. For instance:

     * <pre>

     * boolean b = true;

     * if (b) {...}

     * </pre>

     * Variable 'b' is in declaration of operator IF.

     * @param operator

     *        Ast node which represents operator.

     * @param variable

     *        Variable which is checked for content in operator.

     * @return true if operator contains variable in its declaration, otherwise

     *         - false.

     */

    private static boolean isVariableInOperatorExpr(

            DetailAST operator, DetailAST variable) {