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 :class:`Check <understand.Check>`
parameter. Use the :class:`Check <understand.Check>` object to retrieve
arguments such as the :meth:`files <understand.Check.files>` to run on, the
:meth:`database <understand.Check.db>` or the
:meth:`id <understand.Check.id>` being run (a single script can contain multiple
check ids).

Use the :meth:`violation <understand.Check.violation>` method to report a violation. The
returned :class:`CheckViolation <understand.CheckViolation>` object can be used to add fix it hints
(see :meth:`add_fixit_hint <understand.CheckViolation.add_fixit_hint>`).

Custom options can be defined and retrieved using the :class:`Options <understand.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')