Package: excal
EXCAL - Extendable Clang AST based Linter.WARNING: This project is still in an early stage. Currently working Plugins may not be supported in future versions.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)InstallationIn order to use excal you need to haveclanginstalled on your system.This tool is available on PyPI so you can install it via pip:pip install excalUsageTo 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:CommandargumentsDescription-aList of compiler argumentsprovide compiler arguments for Clang, may improve the AST–argfileFileCompiler arguments may be provided in a File, seperated by newlines-iList of files/directoriesInclude Files used by the compiler to build the AST-f (required)List of files/directoriesFiles/Directories to analyze.-eList of files/directoriesFiles/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.-extList of file extensionsIf provided only files with the given extensions will be parsed.-cCache AST files.AST files will be saved in a .excal directory of the project base. If the file content did not change, they will be reloaded. This will save time when reanalyzing Big projects with only a few files changing or If new rules are added.Config filesIf 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 = TruePluginsThe 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.