CodeCheck Plugins

A CodeCheck runs from Understand and reports coding violations. You can define your own checks using the Python API. A sample check template is below.

The define_options and check functions have an Check parameter. Use the Check object to retrieve arguments such as the files to run on, the database or the id being run (a single script can contain multiple check ids).

Use the violation method to report a violation. The returned CheckViolation object can be used to add fix it hints (see add_fixit_hint).

Custom options can be defined and retrieved using the Options object stored in the check.

#
# These functions describe the check
#

def id():
    """
    Required, return a unique identifier for this check.
    """
    return 'TEST_01'

def name():
    """
    Required, return the short name of the check.

    This should be a phrase or word that reminds you what the check does.
    """
    return 'Python Options Test'

def description():
    """
    Required, return a detailed description of the check.

    This string appears in the 'checks selection' interface within CodeCheck.
    Here you can provide a more in-depth explanation of what your check does,
    any notes or exceptions to the check, and even simple code examples that
    show how the check should behave.
    """
    return """
    <p><b>Rationale</b></p>
    <p>
    This is a template check showing available options.
    </p>
    """

#
# These functions determine when the check will run
#

def test_entity(file):
    """
    Required, return True if the check should run on the file.

    This is only called for non-project level checks (checks whose
    test_global function was ommitted or returned False).
    """
    return file.kind().check('code file')

def test_language(language):
    """
    Optional, return True if this check works for the given language.
    """
    return language == "C++"

def test_global():
    """
    Optional, return True if this check is a project level check.

    Project level checks are run on the entire project regardless of which
    files are selected. For example, a check that counted the total member
    function declarations.

    This function should only be set to True for project-level checks,
    otherwise it can be set to False or omitted from the script entirely.
    """
    return True

#
# This method is called when a check is created
#
def define_options(check):
    """
    Optional, initialize check options.

    Options defined here are configurable from Understand. The check
    function below has examples retrieving the options.
    """
    check.options().checkbox('checkbox', 'This is a checkbox')
    check.options().integer('integer', 'This is an integer', 2)
    check.options().text('text', 'This is text', 'Default Text')
    check.options().choice('choice', 'This is a choice', ['A', 'B', 'C'], 'B');

#
# The check method runs the actual check. Project level checks use the
# first signature. Other checks use the second signature. A codecheck
# is either project level or it is not. These check methods are shown
# together in this template only for demonstration.
#

def check(check):
    """
    The check overload for a project level check.
    """
    # Use the check object to get the database
    ent = check.db().ents('code file')[0]

    # The check also contains the values for the defined options
    checkbox = check.options().lookup('checkbox')
    integer = check.options().lookup('integer')
    text = check.options().lookup('text')
    choice = check.options().lookup('choice');

    # submit a violation by calling violation on the check object.
    check.violation(ent, ent, 0, 0,
                    'checkbox: %1, integer: %2, text: %3, choice: %4',
                    checkbox, integer, text, choice)

def check(check, file):
    """
    The check overload for a non-project level check.
    """
    for ref in file.filerefs('define', 'function'):
        # Use is_aborted to see if an abort was requested
        if check.is_aborted():
            return

        ent = ref.ent()
        if ent.name() == 'main':
            # Store the violation returned from check.violation to add
            # more details
            violation = check.violation(ent, file, ref.line(), ref.column(),
                                        'definition of %1 function', ent)
            # You can add fix it hints to violations
            violation.add_fixit_hint(ref.line(), ref.column(), ref.line(),
                                     ref.column() + len(ent.name()), 'foo')