excal 0.0.8

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

In order to use excal you need to have clang installed on your system.

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.
-ptt	-	Same as above, but will also Print all Tokens under their corresponding AST Nodes. (will produce long output)
-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 its root 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. The Plugin then can provide a class inherits from the NodeVisitor class. Here the visit_X 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.