NumericLiteralNeedsUnderscoreCheck.java

package com.github.sevntu.checkstyle.checks.coding;

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

/**
 * <p>
 * This check verifies that large numeric literals are spaced by underscores.
 * </p>
 * <p>
 * Java 7 allows for underscores to delimit numeric literals to enhance readability because very
 * large numeric literals are hard to read. For example:
 * </p>
 * <code>
 * long creditCardNumber = 1234_5678_1234_5678L;
 * </code>
 * <p>
 * is much easier to read than
 * </p>
 * <code>
 * long creditCardNumber = 1234567812345678L;
 * </code>
 * <p>
 * This check comes with the following parameters:
 * </p>
 * <p>
 * "minDecimalSymbolLength" - The minimum number of symbols in a decimal literal before the check
 * begins to look for underscores. For example, if this is set to 7, then the following code will
 * pass because it is not yet of length 7 and will be ignored:
 * </p>
 * <p>
 * <code>
 * int i = 123456;
 * </code>
 * </p>
 * <p>
 * "maxDecimalSymbolsUntilUnderscore" - The maximum number of symbols in a decimal literal allowed
 * before the check demands an underscore. For example, if this is set to 3 and
 * minDecimalSymbolLength is set to 7, then the first line will fail and the second will pass:
 * </p>
 * <p>
 * <code>
 * int failing = 1234567;<br/>
 * int passing = 1_234_567;
 * </code>
 * </p>
 * <p>
 * "minHexSymbolLength" - The minimum number of symbols in a hex literal before the check begins to
 * look for underscores. For example, if this is set to 5, then the following code will pass because
 * it is not yet of length 5 and will be ignored:
 * </p>
 * <p>
 * <code>
 * int i = 0xFFFF;
 * </code>
 * </p>
 * <p>
 * "maxHexSymbolsUntilUnderscore" - The maximum number of symbols in a hex literal allowed before
 * the check demands an underscore. For example, if this is set to 4 and minHexSymbolLength is set
 * to 5, then the first line will fail and the second will pass:
 * </p>
 * <p>
 * <code>
 * int failing = 0xFFFFFFFF;<br/>
 * int passing = 0xFFFF_FFFF;
 * </code>
 * </p>
 * <p>
 * "minBinarySymbolLength" - The minimum number of symbols in a binary literal before the check
 * begins to look for underscores. For example, if this is set to 9, then the following code will
 * pass because it is not yet of length 9 and will be ignored:
 * </p>
 * <p>
 * <code>
 * int i = 0b01010101;
 * </code>
 * </p>
 * <p>
 * "maxBinarySymbolsUntilUnderscore" - The maximum number of symbols in a decimal literal allowed
 * before the check demands an underscore. For example, if this is set to 8 and
 * minBinarySymbolLength is set to 9, then the first line will fail and the second will pass:
 * </p>
 * <p>
 * <code>
 * int failing = 0b0000000000000000;<br/>
 * int passing = 0b00000000_00000000;
 * </code>
 * </p>
 * <p>
 * An example of how to configure parameters:
 * </p>
 *
 * <pre>
 * &lt;module name="NumericLiteralNeedsUnderscoreCheck"&gt;
 *    &lt;property name="minDecimalSymbolLength" value="7"/&gt;
 *    &lt;property name="maxDecimalSymbolsUntilUnderscore" value="3"/&gt;
 *    &lt;property name="minHexSymbolLength" value="5"/&gt;
 *    &lt;property name="maxHexSymbolsUntilUnderscore" value="4"/&gt;
 *    &lt;property name="minBinarySymbolLength" value="9"/&gt;
 *    &lt;property name="maxBinarySymbolsUntilUnderscore" value="8"/&gt;
 * &lt;/module&gt;
 * </pre>
 * @author Cheng-Yu Pai
 */

public class NumericLiteralNeedsUnderscoreCheck extends Check
{

    /**
     * Key for error message.
     */
    public static final String MSG_KEY = "numeric.literal.need.underscore";

    private static enum Type
    {
        DECIMAL, HEX, BINARY;
    }

    private static final int DEFAULT_MIN_DECIMAL_SYMBOL_LEN = 7;
    private static final int DEFAULT_MAX_DECIMAL_SYMBOLS_UNTIL_UNDERSCORE = 3;

    private static final int DEFAULT_MIN_HEX_SYMBOL_LEN = 5;
    private static final int DEFAULT_MAX_HEX_SYMBOLS_UNTIL_UNDERSCORE = 4;

    private static final int DEFAULT_MIN_BINARY_SYMBOL_LEN = 9;
    private static final int DEFAULT_MAX_BINARY_SYMBOLS_UNTIL_UNDERSCORE = 8;

    private int minDecimalSymbolLength = DEFAULT_MIN_DECIMAL_SYMBOL_LEN;
    private int maxDecimalSymbolsUntilUnderscore = DEFAULT_MAX_DECIMAL_SYMBOLS_UNTIL_UNDERSCORE;

    private int minHexSymbolLength = DEFAULT_MIN_HEX_SYMBOL_LEN;
    private int maxHexSymbolsUntilUnderscore = DEFAULT_MAX_HEX_SYMBOLS_UNTIL_UNDERSCORE;

    private int minBinarySymbolLength = DEFAULT_MIN_BINARY_SYMBOL_LEN;
    private int maxBinarySymbolsUntilUnderscore = DEFAULT_MAX_BINARY_SYMBOLS_UNTIL_UNDERSCORE;

    /**
     * Sets how many characters in a literal there must be before it checks for an underscore
     */
    public void setMinDecimalSymbolLen(int len)
    {
        minDecimalSymbolLength = len;
    }

    /**
     * Sets how many characters there can be until there must be an underscore (for numeric
     * literals)
     */
    public void setMaxDecimalSymbolsUntilUnderscore(int amount)
    {
        maxDecimalSymbolsUntilUnderscore = amount;
    }

    /**
     * Sets how many characters in a hex literal there must be before it checks for an underscore
     */
    public void setMinHexSymbolLen(int len)
    {
        minHexSymbolLength = len;
    }

    /**
     * Sets how many characters there can be until there must be an underscore (for hex literals)
     */
    public void setMaxHexSymbolsUntilUnderscore(int amount)
    {
        maxHexSymbolsUntilUnderscore = amount;
    }

    /**
     * Sets how many characters in a byte literal there must be before it checks for an underscore
     */
    public void setMinBinarySymbolLen(int len)
    {
        minBinarySymbolLength = len;
    }

    /**
     * Sets how many characters there can be until there must be an underscore (for byte literals)
     */
    public void setMaxBinarySymbolsUntilUnderscore(int amount)
    {
        maxBinarySymbolsUntilUnderscore = amount;
    }

    @Override
    public int[] getDefaultTokens()
    {
        return new int[] {
                TokenTypes.NUM_INT,
                TokenTypes.NUM_LONG,
                TokenTypes.NUM_FLOAT,
                TokenTypes.NUM_DOUBLE
        };
    }

    @Override
    public void visitToken(final DetailAST ast)
    {
        if (!passesCheck(ast.getText())) {
            log(ast.getLineNo(), MSG_KEY);
        }
    }

    /**
     * Returns true if the numeric literal passes the check
     */
    private boolean passesCheck(String rawLiteral)
    {
        int minCheckingLength = minSymbolsBeforeChecking(rawLiteral);
        int symbolsUntilUnderscore = maxSymbolsUntilUnderscore(rawLiteral);
        String[] tokens = generateStrippedTokens(rawLiteral);
        boolean passing = true;
        for (String token : tokens) {
            if (!tokenPassesRequirement(token, minCheckingLength, symbolsUntilUnderscore)) {
                passing = false;
                break;
            }
        }
        return passing;
    }

    /**
     * <p>
     * Returns the type of numeric literal given the raw text.
     * </p>
     * <p>
     * Decimal literals are normal numbers. Example: 1, 1.0, 1.0e0f, 1L
     * </p>
     * <p>
     * Hex literals are preceded by 0x. Example: 0xDEADBEEF, 0xA.Bp1d
     * </p>
     * <p>
     * Binary literals are preceded by 0b. Example: 0b00001111
     * </p>
     */
    private Type getNumericType(String rawLiteral)
    {
        Type type;
        if (rawLiteral.length() < 2) {
            type = Type.DECIMAL;
        }
        else {
            String prefix = rawLiteral.substring(0, 2);
            if (prefix.equals("0x")) {
                type = Type.HEX;
            }
            else if (prefix.equals("0b")) {
                type = Type.BINARY;
            }
            else {
                type = Type.DECIMAL;
            }
        }
        return type;
    }

    /**
     * <p>
     * Generates easily checkable tokens from the raw literal text.
     * </p>
     * <p>
     * For example: 123.4567 passes because each section itself is not too long and is perfectly
     * readable.
     * </p>
     * Additionally, Java will not compile underscores next to decimal points etc.
     * @param rawLiteral
     * @return easily checkable tokens
     */
    private String[] generateStrippedTokens(String rawLiteral)
    {
        Type type = getNumericType(rawLiteral);
        String strippedLiteral = removePrePostfixByType(rawLiteral, type);
        String[] tokens;
        switch (type) {
        case DECIMAL:
            tokens = strippedLiteral.split("[\\.eE]");
            break;
        case HEX:
            tokens = strippedLiteral.split("[\\.pP]");
            break;
        case BINARY:
            // Binary literals do not need splitting, fall through to default
        default:
            tokens = new String[1];
            tokens[0] = strippedLiteral;
            break;
        }
        return tokens;
    }

    private int minSymbolsBeforeChecking(String rawLiteral)
    {
        Type type = getNumericType(rawLiteral);
        int minLength;
        switch (type) {
        case DECIMAL:
            minLength = minDecimalSymbolLength;
            break;
        case HEX:
            minLength = minHexSymbolLength;
            break;
        case BINARY:
            minLength = minBinarySymbolLength;
            break;
        default:
            throw new IllegalStateException("Unexpected numeric type " + type.toString());
        }
        return minLength;
    }

    private int maxSymbolsUntilUnderscore(String rawLiteral)
    {
        Type type = getNumericType(rawLiteral);
        int maxSymbols;
        switch (type) {
        case DECIMAL:
            maxSymbols = maxDecimalSymbolsUntilUnderscore;
            break;
        case HEX:
            maxSymbols = maxHexSymbolsUntilUnderscore;
            break;
        case BINARY:
            maxSymbols = maxBinarySymbolsUntilUnderscore;
            break;
        default:
            throw new IllegalStateException("Unexpected numeric type " + type.toString());
        }
        return maxSymbols;
    }

    /**
     * Returns whether or not the text passes the underscore requirement given the text and minimum
     * length
     */
    private boolean tokenPassesRequirement(String token, int minLength, int symbolsUntilUnderscore)
    {
        if (token.length() < minLength) {
            return true;
        }
        final char underscore = '_';
        int symbolCount = 0;
        boolean passes = true;
        for (int i = 0; i < token.length(); i++) {
            char current = token.charAt(i);
            if (symbolCount >= symbolsUntilUnderscore && current != underscore) {
                passes = false;
                break;
            }
            if (current == underscore) {
                symbolCount = 0;
            }
            else {
                symbolCount++;
            }
        }
        return passes;
    }

    /**
     * Removes 0x, 0b prefixes, and l, L, f, F, d, D postfixes from numeric literals
     */
    private String removePrePostfixByType(String rawLiteral, Type literalType)
    {
        String processedLiteral;
        switch (literalType) {
        case DECIMAL:
            processedLiteral = removeLetterPostfix(rawLiteral);
            break;
        case HEX:
            processedLiteral = removePrefix(rawLiteral);
            processedLiteral = removePostfixHex(processedLiteral);
            break;
        case BINARY:
            processedLiteral = removePrefix(rawLiteral);
            processedLiteral = removeLetterPostfix(processedLiteral);
            break;
        default:
            processedLiteral = rawLiteral;
            break;
        }
        return processedLiteral;
    }

    private String removePrefix(String text)
    {
        return text.substring(2);
    }

    private String removeLetterPostfix(String text)
    {
        char lastchar = text.charAt(text.length() - 1);
        String noPostfixText;
        if (Character.isDigit(lastchar)) {
            noPostfixText = text;
        }
        else {
            noPostfixText = text.substring(0, text.length() - 1);
        }
        return noPostfixText;
    }

    /**
     * Removes postfixes from hex literals
     */
    private String removePostfixHex(String text)
    {
        char lastchar = Character.toUpperCase(text.charAt(text.length() - 1));
        boolean hasPostfix = false;
        if (lastchar == 'L') {
            // Example: 0x00FFL
            hasPostfix = true;
        }
        else if (lastchar == 'F' && (text.contains("p") || text.contains("P"))) {
            // Example: 0x1.0p1f (Hex Float)
            hasPostfix = true;
        }
        String noPostfixText;
        if (hasPostfix) {
            noPostfixText = text.substring(0, text.length() - 1);
        }
        else {
            noPostfixText = text;
        }
        return noPostfixText;
    }

}