excal 0.0.4

Extendable Clang AST based c/c++ linter

EXCAL - Extendable Clang AST based Linter.

This is a simple project implementing a C/C++ linter based on the clang AST. The main porpoise is to create a tool which is easily extendable via plugins.

The focus of this project is to provide a tool for the implementation of custom C/C++ coding guidelines. There are no rules provided by the linter itself, rather a toolset to implement your own. (see Plugins)

Installation

This tool is available on PyPI so you can install it via pip:

pip install excal

Usage

To Analyze a file or project the tool expects input files/directories. Additionally you should provide all includes. If no Includes are given Clang will still create an AST, however it will be incomplete and may cause false positives/negatives from the linter.

    excal -f path/to/file_to_analyze.c -i path/to/includes/

A list of all supported options:

Command	arguments	Description
-a	List of compiler arguments	provide compiler arguments for Clang, may improve the AST
–argfile	File	Compiler arguments may be provided in a File, seperated by newlines
-i	List of files/directories	Include Files used by the compiler to build the AST
-f (required)	List of files/directories	Files/Directories to analyze.
-e	List of files/directories	Files/Directories within given directories, which should be ignored.
-p	-	If this flag is provided the Linter will print the AST of all included files. This is useful for creating Plugins.
-cpp	-	Libclang will analyze files based on their extension. If the extension is not cpp specific (eg. .h instead .hpp) this flag will force all files to be analyzed as c++ code.
-ext	List of file extensions	If provided only files with the given extensions will be parsed.

Config files

If a single directory is given as input, excal will scan said directory for a setup.cfg file. Here some project parameters may be provided. At the moment only the options given in belows example are being used, additional ones will be added.

[EXCAL]
includes = 
  /opt/ros/foxy/include/
exclude_files =
  file/to/exclude.c
  files/to/exclude/
  **/venv
force_cpp = True

Plugins

The Goal of this project is to provide an interface that allows it to easily implement linter rules based on an AST.

A Plugin will need to provide a register method in which it will register itself within the Project by calling the register method of the given PluginManager. The Plugin then can provide a class which inherits from the NodeVisitor class. Here the visit_X (X is the coresponding part of the AST. When printing the Ast wit hthe -p flag, each node Will have a name like: CursorKind.NODE_NAME the coresponding visit function would be visit_node_name) functions can be overwritten. When parsing the AST, these functions will be called whenever a desired Node is reached. From there further operations may be done on the provided AstNode.

See the following example:

    from visitor import NodeVisitor
    from pluginManager import PluginManager
    from astNode import AstNode
    
    PLUGIN_NAME = "AutonomusReply"
    
    class customVisitor(NodeVisitor):
        def __init__(self) -> None:
            super().__init__()
    
        def visit_class_base(self, node: AstNode) -> None:
            return
    
    def register(pm: PluginManager):
        pm.register(PLUGIN_NAME, customVisitor)

There are two ways to provide Plugins. The preferred one is to Create as a standalone python Package. See this example.

The other way is to put the Plugin in the plugins folder and register it in the plugins.json file.

    {
      "plugins": ["plugins.myPlugin"]
    }

All possible functions can be seen in src/visitor.py. To see which function may be needed for your use-cases run the excal project using the -p flag. This will print an AST of the desired file.