Plug-In Tutorial: Python Version

• Part One
• Part Two

Part One

The plug-in for Part One implements a check for variable names containing upper case characters. There are three important elements in the plug-in:

• Creating a new warning class for the warnings that will be issued when variables contain upper case characters.
• Defining a function that takes a symbol (ABS_LOC) and, if it corresponds to a user-defined variable, checks the case of the characters in the variable name.
• Attaching that function to the visitor list for variable symbols.

• UCvar_plugin.py
• Install
• Exercise
• Clean Up

UCvar_plugin.py

Parts of file UCvar_plugin.py are reproduced below.

  #
#      Copyright (c) 2023, an unpublished work by CodeSecure, Inc.
#                      ALL RIGHTS RESERVED
#
#      Copyright (c) 2017-2023, an unpublished work by GrammaTech, Inc.
#                      ALL RIGHTS RESERVED
# 
#      This software is furnished under a license and may be used and
#      copied only in accordance with the terms of such license and the
#      inclusion of the above copyright notice.  This software or any
#      other copies thereof may not be provided or otherwise made
#      available to any other person.  Title to and ownership of the
#      software is retained by CodeSecure, Inc.
# 

# UCvar_plugin.py
# 
#  a small example plugin that reports declarations for variables
#  whose names contain upper case characters

import cs

# The plug-in defines a new warning class to go with its new check. We
# do not associate any CodeSonar mnemonics or CWE identifiers with the
# new class, as none are appropriate.  The new warning class must be
# created in the top level scope.

upvar_wc = cs.analysis.create_warningclass(
    'Variable name has upper case characters',
    '',
    1.0,
    cs.warningclass_flags.PADDING,
    cs.warning_significance.STYLE
    )


# Visitors should be at the finest granularity that is appropriate
# for the check. This plug-in is checking a property of variable
# names, so we define a visitor that operates on symbols.

@cs.symbol_visitor        # \visitor decorator \
def check_var_case(sym):
    nm = sym.name()       # cs.symbol.name()

    # If there are one or more upper case characters and the variable
    # is declared in user code, issue a warning and return.
    if nm != nm.lower():        
        try:
            (symfi,symline) = sym.file_line()   # cs.symbol.file_line()
        except cs.result as r:
            # If no position, do not report warning. Raise any other errors.
            if r != cs.result.NO_POSITION:
                raise     
        else:
            if not symfi.is_system_include():   # cs.sfileinst.is_system_include()
                upvar_wc.report(symfi,          # cs.warningclass.report()
                                symline,
                                'Variable name %s has upper case character'%nm)

  

Install

Install the plug-in:

• Copy or move your plug-in ( UCvar_plugin.py) to directory
  $CSONAR/codesonar/plugins/
  (If you don't have access to this directory, use the PLUGINS configuration file option to specify the file path for your compiled plug-in.)

Exercise

We have provided an extremely short example program to exercise the plug-in. You can also try building other programs into CodeSonar projects to see how many variables they contain whose names include upper case letters.

• Build testvar.c into a CodeSonar project. Your exact build command will, as always, depend on your local build tools and on the hub location (host:port). In many cases, one of the following will suffice:

  with cl:	codesonar analyze testvar host:port cl /c testvar.c
  with gcc:	codesonar analyze testvar host:port gcc -c testvar.c

  See Building Projects (Command Line) or Building Projects (Windows Build Wizard) for more information about building a CodeSonar project.
• Look at the analysis results to see where the warnings are issued and what the warning reports look like.

  Note that procedure names are not associated with the warnings. This is because we issued the warnings with the warningclass.report() form for reporting a warning with a location, which does not report a procedure name (because, among other reasons, a line may contain multiple procedures).

Clean Up

If you don't want to be warned in future about variable names containing upper case letters:

• Remove the plug-in (UCvar_plugin.py) from $CSONAR/codesonar/plugins/

  (If you used an alternative location, remove the associated PLUGINS configuration file setting).

Part Two

The plug-in for Part Two implements a check for mismatched parentheses in the output of a program. This involves setting up a step visitor to ensure that the control-flow paths in the program involve properly balanced calls to the procedures that write opening and closing parentheses.

• callseq_plugin.py
• Install
• Exercise
• Clean Up

callseq_plugin.py

callseq_plugin.py contains comments describing the various elements of the plug-in. See these comments for details.

Install

Install the plug-in:

• Copy or move your plug-in ( callseq_plugin.py ) to directory
  $CSONAR/codesonar/plugins/
  (If you don't have access to this directory, use the PLUGINS configuration file option to specify the file path to your compiled plug-in.)

Exercise

We have provided an extremely short example program to exercise the plug-in.

• Build callseq_sample.c into a CodeSonar project. Your exact build command will, as always, depend on your local build tools and on the hub location (host:port). In many cases, one of the following will suffice:

  with cl:	codesonar analyze callseq host:port cl /c callseq_sample.c
  with gcc:	codesonar analyze callseq host:port gcc -c callseq_sample.c

  See Building Projects (Command Line) or Building Projects (Windows Build Wizard) for more information about building a CodeSonar project.
• Look at the analysis results to see where the warning is issued, where the warning name appears in the results, and where the warning message appears.

Clean Up

If you don't want to use this plug-in in future:

• Remove the plug-in (callseq_plugin.py) from $CSONAR/codesonar/plugins/

  (If you used an alternative location, remove the associated PLUGINS configuration file setting).

More on Plug-Ins

General Information:

Additional sample plugins can be found at $CSONAR/codesonar/plugins/*.py where $CSONAR is your CodeSonar installation directory.

Specific API Language: