/hpp2plantuml

Convert C++ header files to PlantUML

Primary LanguagePythonMIT LicenseMIT

hpp2plantuml - Convert C++ header files to PlantUML

Motivation

The purpose of this tool is to convert C++ header files to a UML representation in PlantUML syntax that can be used to generate diagrams with PlantUML.

PlantUML is a program rendering UML diagrams from plain text inputs using an expressive language.

This package generates the text input to PlantUML from C++ header files. Its ambition is limited but it should produce reasonable conversion for simple class hierarchies. It aims at supporting:

  • class members with properties (private, method, protected), methods with basic qualifiers (static, abstract),
  • inheritance relationships,
  • aggregation relationships (very basic support).
  • dependency relationships

The package relies on the CppHeaderParser package for parsing of C++ header files.

Usage

The hpp2plantuml package can be used from the command line or as a module in other applications.

Command line

The command line usage is (hpp2plantuml --help):

usage: hpp2plantuml [-h] -i HEADER-FILE [-o FILE] [-d] [-t JINJA-FILE]
                    [--version]

hpp2plantuml tool.

optional arguments:
  -h, --help            show this help message and exit
  -i HEADER-FILE, --input-file HEADER-FILE
                        input file (must be quoted when using wildcards)
  -r, --recursive       Allow to searching recursively for files in subdirectories (double asterisk should be in filepath)
  -o FILE, --output-file FILE
                        output file
  -d, --enable-dependency
                        Extract dependency relationships from method arguments
  -t JINJA-FILE, --template-file JINJA-FILE
                        path to jinja2 template file
  --version             show program's version number and exit

Input files are added using the -i option. Inputs can be full file paths or include wildcards. Note that double quotes are required when using wildcards. The output file is selected with the -o option. The output is a text file following the PlantUML syntax.

For instance, the following command will generate an input file for PlantUML (output.puml) from several header files.

hpp2plantuml -i File_1.hpp -i "include/Helper_*.hpp" -o output.puml

To allow taking files from subfolders, pass -r option with suitable filepath (double asterisk required):

hpp2plantuml -r -i "include/**/Helper_*.hpp" -o output.puml

To customize the output PlantUML file, templates can be used (using the -t parameter):

hpp2plantuml -i File_1.hpp -i "include/Helper_*.hpp" -o output.puml -t template.puml

This will use the template.puml file as template. Templates follow the jinja syntax. For instance, to add a preamble to the PlantUML output, the template file may contain:

{% extends 'default.puml' %}

{% block preamble %}
title "This is a title"
skinparam backgroundColor #EEEBDC
skinparam handwritten true
{% endblock %}

This will inherit from the default template and override the preamble only.

Module

To use as a module, simply import hpp2plantuml. The CreatePlantUMLFile function can then be used to create a PlantUML file from a set of input files. Alternatively, the Diagram object can be used directly to build internal objects (from files or strings). The Diagram.render() method can be used to produce a string output instead of writing to a text file. See the API documentation for more details.

Installation

Using pip

The package is available on PyPi and can be installed using pip:

pip install hpp2plantuml

From source

The code uses setuptools, so it can be built using:

python setup.py install

To build the documentation, run:

python setup.py sphinx

To run the tests, run:

python setup.py test

The full documentation is available via: