Lizard Cyclomatic Complexity Analyzer

Using a Whitelist

To ignore specific functions, create a file named whitelizard.txt in the current folder (or specify it with -W). The file format allows specifying function names or file-specific functions:

#whitelizard.txt
function_name1, function_name2
file/path/name:function1, function2

Using 'GENERATED CODE' comments

Lizard will completely ignore any code in a source file that follows a comment containing GENERATED CODE. This code will not generate data, though the file will still be counted in the total file count.

Lizard's approach to Cyclomatic Complexity for nested constructs (like functions, closures, or structs) depends on the language:

• Python: Nested complexity is considered separately.
• C++ and C++-like languages: The complexity of nested constructs is ignored by default to focus on the root function's complexity.

There are theoretical alternatives (adding inner complexity to the outer construct or ignoring it entirely), but Lizard follows these language-specific defaults.

Lizard calculates Cyclomatic Complexity (CCN) by starting at a base of 1 and adding +1 for every token found in the following four categories. You must define these as sets in your CodeReader subclass:

1. _control_flow_keywords: Keywords that create new execution paths or decision points (e.g., if, for, while, catch, match).
2. _logical_operators: Operators that combine boolean conditions and add decision points (e.g., &&, ||, and, or).
3. _case_keywords: Keywords used for individual branches in switch/case expressions (e.g., case, when).
4. _ternary_operators: Operators for inline conditional expressions (e.g., ?, ??, ?:).

Note: Use set() for categories your language does not use to avoid errors.

The Nested Control Structures metric measures the depth of the deepest nested control structures (like if, while, for, and switch) within a function block. This is distinct from CCN, which measures the total number of control paths.

Lizard's default maximum depth for nested structures is 3, a threshold inspired by the Linux kernel coding style. High nesting depth often indicates code that should be refactored through function extraction.

int foo()
{
        while (expr1) {

                for (; expr2;) {

                        for (; expr3;) {

                                if (expr4)
                                    return 42;

                        }

                }
        }
        return -42;
}

In defensive programming, assertions (e.g., assert(expression)) are used to check invariants and are not intended to be part of the actual functional flow. Including them in CCN calculations can artificially inflate a function's complexity.

Lizard provides an IgnoreAssert extension for C-like languages to discount the CCN added by assertions. This allows you to calculate the 'true' inherent complexity of a function.

Note: Lizard only discounts the CCN added by simple operators within assertions; it does not ignore arbitrary complexity if complex logic is placed inside an assertion.

Cyclomatic Complexity Number (CCN) is calculated by iterating through tokens and checking if they exist in the reader.conditions set. Every token found in this set increments the complexity count by +1 via reader.context.add_condition().

To influence the CCN, an extension can modify the reader.conditions set or the individual category sets (like reader.logical_operators) which are used to build the combined set.

def condition_counter(tokens, reader):
    conditions = reader.conditions  # Combined set of all categories
    for token in tokens:
        if token in conditions:
            reader.context.add_condition()  # Adds +1 to CCN
        yield token

To support a new language, create a class that inherits from CodeReader (located in lizard_languages/code_reader.py) and overrides the four condition category class attributes. The base class automatically combines these into a single self.conditions set used for CCN calculation.

Categories to define:

• _control_flow_keywords: Core decision points (e.g., if, while).
• _logical_operators: Compound condition operators (e.g., &&, ||).
• _case_keywords: Switch/case branch keywords.
• _ternary_operators: Inline conditional operators (e.g., ?).

class LanguageReader(CodeReader):
    _control_flow_keywords = {'if', 'for', 'while'}
    _logical_operators = {'&&', '||'}
    _case_keywords = {'case'}
    _ternary_operators = {'?'}

You can use Lizard as a standalone Python script without installation, or perform a proper installation to access all functionalities. Lizard requires Python 3.8 or above.

To install via pip:

[sudo] pip install lizard

To install from source:

[sudo] python setup.py install --prefix=/path/to/installation/directory/