hpp2plantuml package

Submodules

hpp2plantuml.hpp2plantuml module

class hpp2plantuml.hpp2plantuml.Class(header_class)

Bases: hpp2plantuml.hpp2plantuml.Container

Representation of C++ class

This class derived from Container specializes the base class to handle class definition in C++ headers.

It supports:

• abstract and template classes
• member variables and methods (abstract and static)
• public, private, protected members (static)

Constructor

Extract the class name and properties (template, abstract) and inheritance. Then, extract the class members from the header using the parse_members() method.

Parameters:

header_class : tuple(str, CppClass)

Parsed header for class object (two-element list where the first element is the class name and the second element is a CppClass object)

_do_parse_members(self, header_class)

Initialize class object from header

This method extracts class member variables and methods from header.

Parameters:

header_class : CppClass

Parsed header for class

_render_container_def(self)

Create the string representation of the class

Return the class name with template and abstract properties if present. The output string follows the PlantUML syntax. Note that struct and union types are rendered as classes.

Returns:

str

String representation of class

build_inheritance_list(self)

Get inheritance list

Returns:

list(str)

List of class names the current class inherits from

build_variable_type_list(self)

Get type of member variables

This function extracts the type of each member variable. This is used to list aggregation relationships between classes.

Returns:

list(str)

List of types (as string) for each member variable

class hpp2plantuml.hpp2plantuml.ClassAggregationRelationship(c_object, c_container, c_count=1, rel_type='aggregation', **kwargs)

Bases: hpp2plantuml.hpp2plantuml.ClassRelationship

Representation of aggregation relationships

This module extends the base ClassRelationship class by setting the link type to aggregation. It also keeps a count of aggregation, which is displayed near the arrow when using PlantUML.

Aggregation relationships are simplified to represent the presence of a variable type (possibly within a container such as a list) in a class definition.

Constructor

Parameters:

c_object : str

Class corresponding to the type of the member variable in the aggregation relationship

c_container : str

Child (or client) class of the aggregation relationship

c_count : int

The number of members of c_container that are of type (possibly through containers) c_object

rel_type : str

Relationship type: aggregation or composition

kwargs : dict

Additional parameters passed to parent class

_render_link_type(self)

Internal link rendering

This method overrides the default link rendering defined in ClassRelationship._render_link_type() to include a count near the end of the arrow.

class hpp2plantuml.hpp2plantuml.ClassDependencyRelationship(c_parent, c_child, **kwargs)

Bases: hpp2plantuml.hpp2plantuml.ClassRelationship

Dependency relationship

Dependencies occur when member methods depend on an object of another class in the diagram.

Constructor

Parameters:

c_parent : str

Class corresponding to the type of the member variable in the dependency relationship

c_child : str

Child (or client) class of the dependency relationship

kwargs : dict

Additional parameters passed to parent class

class hpp2plantuml.hpp2plantuml.ClassInheritanceRelationship(c_parent, c_child, **kwargs)

Bases: hpp2plantuml.hpp2plantuml.ClassRelationship

Representation of inheritance relationships

This module extends the base ClassRelationship class by setting the link type to inherit.

Constructor

Parameters:

c_parent : str

Parent class

c_child : str

Derived class

kwargs : dict

Additional parameters passed to parent class

class hpp2plantuml.hpp2plantuml.ClassMember(class_member, member_scope='private')

Bases: hpp2plantuml.hpp2plantuml.ContainerMember

Class member (variable and method) representation

This class is the base class for class members. The representation includes the member type (variable or method), name, scope (public, private or protected) and a static flag.

Constructor

Parameters:

class_member : CppVariable or CppMethod

Parsed member object (variable or method)

member_scope : str

Member scope property: public, private or protected

_render_name(self)

Get member name

By default (for member variables), this returns the member name. Derived classes can override this to control the name rendering (e.g. add the function prototype for member functions)

render(self)

Get string representation of member

The string representation is with the scope indicator and a static keyword when the member is static. It is postfixed by the type (return type for class methods) and additional properties (e.g. const methods are flagged with the query property). The inner part of the returned string contains the variable name and signature for methods. This is obtained using the _render_name() method.

Returns:

str

String representation of member

class hpp2plantuml.hpp2plantuml.ClassMethod(class_method, member_scope)

Bases: hpp2plantuml.hpp2plantuml.ClassMember

Class member method representation

This class extends ClassMember for member methods. It stores additional method properties (abstract, destructor flag, input parameter types).

Constructor

The method name and additional properties are extracted from the parsed header.

• A list of parameter types is stored to retain the function signature.
• The ~ character is appended to destructor methods.
• const methods are flagged with the query property.

Parameters:

class_method : CppMethod

Parsed class member method

member_scope : str

Scope of the member method

_render_name(self)

Internal rendering of method name

This method extends the base ClassMember._render_name() method by adding the method signature to the returned string.

Returns:

str

The method name (prefixed with the abstract keyword when appropriate) and signature

class hpp2plantuml.hpp2plantuml.ClassNestingRelationship(c_parent, c_child, **kwargs)

Bases: hpp2plantuml.hpp2plantuml.ClassRelationship

Nesting relationship

Dependencies occur when member methods depend on an object of another class in the diagram.

Constructor

Parameters:

c_parent : str

Class corresponding to the type of the member variable in the nesting relationship

c_child : str

Child (or client) class of the dependency relationship

kwargs : dict

Additional parameters passed to parent class

class hpp2plantuml.hpp2plantuml.ClassRelationship(link_type, c_parent, c_child)

Bases: object

Base object for class relationships

This class defines the common structure of class relationship objects. This includes a parent/child pair and a relationship type (e.g. inheritance or aggregation).

Constructor

Parameters:

link_type : str

Relationship type: inherit or aggregation

c_parent : Container

Parent container

c_child : Container

Child container

_render_link_type(self)

Internal representation of link

The string representation is obtained from the LINK_TYPE_MAP constant.

Returns:

str

The link between parent and child following the PlantUML syntax

_render_name(self, class_name, class_namespace)

Render class name with namespace prefix if necessary

Parameters:

class_name : str

Name of the class

class_namespace : str

Namespace or None if the class is defined in the default namespace

Returns:

str

Class name with appropriate prefix for use with link rendering

comparison_keys(self)

Order comparison key between ClassRelationship objects

Compare alphabetically based on the parent name, the child name then the link type.

Returns:

list

operator.attrgetter objects for successive fields used as keys

render(self)

Render class relationship to string

This method generically appends the parent name, a rendering of the link type (obtained from the _render_link_type() method) and the child object name.

Returns:

str

The string representation of the class relationship following the PlantUML syntax

class hpp2plantuml.hpp2plantuml.ClassVariable(class_variable, member_scope='private')

Bases: hpp2plantuml.hpp2plantuml.ClassMember

Object representation of class member variables

This class specializes the ClassMember object for member variables. Additionally to the base class, it stores variable types as strings. This is used to establish aggregation relationships between objects.

Constructor

Parameters:

class_variable : CppVariable

Parsed class variable object

member_scope : str

Scope property to member variable

get_type(self)

Variable type accessor

Returns:

str

Variable type as string

class hpp2plantuml.hpp2plantuml.Container(container_type, name)

Bases: object

Base class for C++ objects

This class defines the basic interface for parsed objects (e.g. class).

Class constructor

Parameters:

container_type : str

String representation of container type (class, struct or enum)

name : str

Object name (with <, > characters removed)

_do_parse_members(self, header_container)

Initialize object from header (abstract method)

Extract object from CppHeaderParser dictionary representing a class, a struct or an enum object.

Parameters:

header_container : CppClass or CppEnum

Parsed header for container

_render_container_def(self)

String representation of object definition

Return the definition line of an object (e.g. “class MyClass”).

Returns:

str

Container type and name as string

comparison_keys(self)

Order comparison key between ClassRelationship objects

Use the parent name, the child name then the link type as successive keys.

Returns:

list

operator.attrgetter objects for successive fields used as keys

name

Name property accessor

Returns:

str

Object name

parse_members(self, header_container)

Initialize object from header

Extract object from CppHeaderParser dictionary representing a class, a struct or an enum object. This extracts the namespace. Use the parent field to determine is the namespace description from CppHeaderParser is a parent object (e.g. class) or a proper namespace.

Parameters:

header_container : CppClass or CppEnum

Parsed header for container

render(self)

Render object to string

Returns:

str

String representation of object following the PlantUML syntax

sort_members(self)

Sort container members

sort the list of members by type and name

class hpp2plantuml.hpp2plantuml.ContainerMember(header_member, **kwargs)

Bases: object

Base class for members of Container object

This class defines the basic interface for object members (e.g. class variables, etc.)

Constructor

Parameters:

header_member : str

Member name

comparison_keys(self)

Order comparison key between ClassRelationship objects

Use the parent name, the child name then the link type as successive keys.

Returns:

list

operator.attrgetter objects for successive fields used as keys

render(self)

Render object to string (abstract method)

Returns:

str

String representation of object member following the PlantUML syntax

hpp2plantuml.hpp2plantuml.CreatePlantUMLFile(file_list, output_file=None, **diagram_kwargs)

Create PlantUML file from list of header files

This function parses a list of C++ header files and generates a file for use with PlantUML.

Parameters:

file_list : list(str)

List of filenames (possibly, with wildcards resolved with the expand_file_list() function)

output_file : str

Name of the output file

diagram_kwargs : dict

Additional parameters passed to Diagram constructor

class hpp2plantuml.hpp2plantuml.Diagram(template_file=None, flag_dep=False)

Bases: object

UML diagram object

This class lists the objects in the set of files considered, and the relationships between object.

The main interface to the Diagram object is via the create_* and add_* methods. The former parses objects and builds relationship lists between the different parsed objects. The latter only parses objects and does not builds relationship lists.

Each method has versions for file and string inputs and folder string lists and file lists inputs.

Constructor

The Diagram class constructor simply initializes object lists. It does not create objects or relationships.

_augment_comp(self, c_dict, c_parent, c_child, rel_type='aggregation')

Increment the aggregation reference count

If the aggregation relationship is not in the list (c_dict), then add a new entry with count 1. If the relationship is already in the list, then increment the count.

Parameters:

c_dict : dict

List of aggregation relationships. For each dictionary key, a pair of (str, int) elements: string and number of occurrences

c_parent : str

Parent class name

c_child : str

Child class name

rel_type : str

Relationship type: aggregation or composition

_build_helper(self, data_in, build_from='string', flag_build_lists=True, flag_reset=False)

Helper function to initialize a Diagram object from parsed headers

Parameters:

data_in : CppHeader or str or list(CppHeader) or list(str)

Input of arbitrary type. The processing depends on the build_from parameter

build_from : str

Determines the type of the data_in variable:

• string: data_in is a string containing C++ header code
• file: data_in is a filename to parse
• string_list: data_in is a list of strings containing C++ header code
• file_list: data_in is a list of filenames to parse

flag_build_lists : bool

When True, relationships lists are built and the objects in the diagram are sorted, otherwise, only object parsing is performed

flag_reset : bool

If True, the object is initialized (objects and relationship lists are cleared) prior to parsing objects, otherwise, new objects are appended to the list of existing ones

_get_class_list(self)

Build list of classes in diagram

Returns:

list

Class object list (returned by _make_class_list())

list

Class names

bool

True when at least one container is a namespace

_make_class_list(self)

Build list of classes

Returns:

list(dict)

Each entry is a dictionary with keys name (class name) and obj the instance of the Class class

_sort_list(input_list)

Sort list using ClassRelationship comparison

Parameters:

input_list : list(ClassRelationship)

Sort list using the ClassRelationship.comparison_keys() comparison function

add_from_file(self, header_file)

Augment Diagram object from header file

Wrapper around the _build_helper() function, with file input, skipping building of the relationship lists and without object reset (new objects are added to the object).

add_from_file_list(self, file_list)

Augment Diagram object from list of header files

Wrapper around the _build_helper() function, with file_list input, skipping building of the relationship lists and without object reset (new objects are added to the object).

add_from_string(self, header_string)

Augment Diagram object from header string

Wrapper around the _build_helper() function, with string input, skipping building of the relationship lists and without object reset (new objects are added to the object).

add_from_string_list(self, string_list)

Augment Diagram object from list of header strings

Wrapper around the _build_helper() function, with string_list input, building the relationship lists and without object reset (new objects are added to the object).

build_aggregation_list(self)

Build list of aggregation relationships

This method loops over objects and finds members with type corresponding to other classes defined in the Diagram object (keeping a count of occurrences).

The procedure first builds an internal dictionary of relationships found, augmenting the count using the _augment_comp() function. In a second phase, ClassAggregationRelationship objects are created for each relationships, using the calculated count.

build_dependency_list(self)

Build list of dependency between objects

This method lists all the dependency relationships between objects contained in the Diagram object (external relationships are ignored).

The implementation establishes a list of available classes and loops over objects, list their methods adds a dependency relationship when a method takes an object as input.

build_inheritance_list(self)

Build list of inheritance between objects

This method lists all the inheritance relationships between objects contained in the Diagram object (external relationships are ignored).

The implementation establishes a list of available classes and loops over objects to obtain their inheritance. When parent classes are in the list of available classes, a ClassInheritanceRelationship object is added to the list.

build_nesting_list(self)

Build list of nested objects

build_relationship_lists(self)

Build inheritance and aggregation lists from parsed objects

This method successively calls the build_inheritance_list() and build_aggregation_list() methods.

clear(self)

Reinitialize object

create_from_file(self, header_file)

Initialize Diagram object from header file

Wrapper around the _build_helper() function, with file input, building the relationship lists and with object reset.

create_from_file_list(self, file_list)

Initialize Diagram object from list of header files

Wrapper around the _build_helper() function, with file_list input, building the relationship lists and with object reset.

create_from_string(self, header_string)

Initialize Diagram object from header string

Wrapper around the _build_helper() function, with string input, building the relationship lists and with object reset.

create_from_string_list(self, string_list)

Initialize Diagram object from list of header strings

Wrapper around the _build_helper() function, with string_list input, skipping building of the relationship lists and with object reset.

parse_objects(self, header_file, arg_type='string')

Parse objects

This method parses file of string inputs using the CppHeaderParser module and extracts internal objects for rendering.

Parameters:

header_file : str

A string containing C++ header code or a filename with C++ header code

arg_type : str

If set to string, header_file is considered to be a string, otherwise, it is assumed to be a filename

render(self)

Render full UML diagram

The string returned by this function should be ready to use with the PlantUML program. It includes all the parsed objects with their members, and the inheritance and aggregation relationships extracted from the list of objects.

Returns:

str

String containing the full string representation of the Diagram object, including objects and object relationships

sort_elements(self)

Sort elements in diagram

Sort the objects and relationship links. Objects are sorted using the Container.comparison_keys() comparison function and list are sorted using the _sort_list helper function.

class hpp2plantuml.hpp2plantuml.Enum(header_enum, parent=None)

Bases: hpp2plantuml.hpp2plantuml.Container

Class representing enum objects

This class defines a simple object inherited from the base Container class. It simply lists enumerated values.

Constructor

Parameters:

header_enum : CppEnum

Parsed CppEnum object

_do_parse_members(self, header_enum)

Extract enum values from header

Parameters:

header_enum : CppEnum

Parsed CppEnum object

class hpp2plantuml.hpp2plantuml.EnumValue(header_value, **kwargs)

Bases: hpp2plantuml.hpp2plantuml.ContainerMember

Class representing values in enum object

This class only contains the name of the enum value (the actual integer value is ignored).

Constructor

Parameters:

header_value : str

Name of enum member

render(self)

Rendering to string

This method simply returns the variable name

Returns:

str

The enumeration element name

class hpp2plantuml.hpp2plantuml.Namespace(name, *args)

Bases: list

Representation of C++ namespace

This class lists other containers or namespaces and wraps the rendered output in a namespace block.

Constructor

Parameters:

name : str

Namespace name

render(self)

Render namespace content

Render the elements and wrap the result in a namespace block

Returns:

str

String representation of namespace in PlantUML syntax

hpp2plantuml.hpp2plantuml._cleanup_namespace(ns_str)

Cleanup string representing a C++ namespace

Cleanup simply consists in removing <> blocks and trailing : characters.

Parameters:

ns_str : str

A string representing a C++ namespace

Returns:

str

The namespace string after cleanup

hpp2plantuml.hpp2plantuml._cleanup_single_line(input_str)

Cleanup string representing a C++ type

Remove line returns

Parameters:

input_str : str

A string possibly spreading multiple lines

Returns:

str

The type string in a single line

hpp2plantuml.hpp2plantuml._cleanup_type(type_str)

Cleanup string representing a C++ type

Cleanup simply consists in removing spaces before a * character and preventing multiple successive spaces in the string.

Parameters:

type_str : str

A string representing a C++ type definition

Returns:

str

The type string after cleanup

hpp2plantuml.hpp2plantuml.expand_file_list(input_files)

Find all files in list (expanding wildcards)

This function uses glob to find files matching each string in the input list.

Parameters:

input_files : list(str)

List of strings representing file names and possibly including wildcards

Returns:

list(str)

List of filenames (with wildcards expanded). Each element contains the name of an existing file

hpp2plantuml.hpp2plantuml.get_namespace_link_name(namespace)

Generate namespace string for link

Parameters:

namespace : str

Namespace name (in the form nested::ns)

Returns:

str

The namespace name formatted for use in links (e.g. nested.nested::ns)

hpp2plantuml.hpp2plantuml.main()

Command line interface

This function is a command-line interface to the hpp2plantuml.CreatePlantUMLFile() function.

Arguments are read from the command-line, run with --help for help.

hpp2plantuml.hpp2plantuml.wrap_namespace(input_str, namespace)

Wrap string in namespace

Parameters:

input_str : str

String containing PlantUML code

namespace : str

Namespace name

Returns:

str

input_str wrapped in namespace block

Module contents

Convert C++ header files to PlantUML <https://github.com/thibaultmarin/hpp2plantuml>

hpp2plantuml.CreatePlantUMLFile(file_list, output_file=None, **diagram_kwargs)

Create PlantUML file from list of header files

This function parses a list of C++ header files and generates a file for use with PlantUML.

Parameters:

file_list : list(str)

List of filenames (possibly, with wildcards resolved with the expand_file_list() function)

output_file : str

Name of the output file

diagram_kwargs : dict

Additional parameters passed to Diagram constructor

class hpp2plantuml.Diagram(template_file=None, flag_dep=False)

Bases: object

UML diagram object

This class lists the objects in the set of files considered, and the relationships between object.

The main interface to the Diagram object is via the create_* and add_* methods. The former parses objects and builds relationship lists between the different parsed objects. The latter only parses objects and does not builds relationship lists.

Each method has versions for file and string inputs and folder string lists and file lists inputs.

Constructor

The Diagram class constructor simply initializes object lists. It does not create objects or relationships.

_augment_comp(self, c_dict, c_parent, c_child, rel_type='aggregation')

Increment the aggregation reference count

If the aggregation relationship is not in the list (c_dict), then add a new entry with count 1. If the relationship is already in the list, then increment the count.

Parameters:

c_dict : dict

List of aggregation relationships. For each dictionary key, a pair of (str, int) elements: string and number of occurrences

c_parent : str

Parent class name

c_child : str

Child class name

rel_type : str

Relationship type: aggregation or composition

_build_helper(self, data_in, build_from='string', flag_build_lists=True, flag_reset=False)

Helper function to initialize a Diagram object from parsed headers

Parameters:

data_in : CppHeader or str or list(CppHeader) or list(str)

Input of arbitrary type. The processing depends on the build_from parameter

build_from : str

Determines the type of the data_in variable:

• string: data_in is a string containing C++ header code
• file: data_in is a filename to parse
• string_list: data_in is a list of strings containing C++ header code
• file_list: data_in is a list of filenames to parse

flag_build_lists : bool

When True, relationships lists are built and the objects in the diagram are sorted, otherwise, only object parsing is performed

flag_reset : bool

If True, the object is initialized (objects and relationship lists are cleared) prior to parsing objects, otherwise, new objects are appended to the list of existing ones

_get_class_list(self)

Build list of classes in diagram

Returns:

list

Class object list (returned by _make_class_list())

list

Class names

bool

True when at least one container is a namespace

_make_class_list(self)

Build list of classes

Returns:

list(dict)

Each entry is a dictionary with keys name (class name) and obj the instance of the Class class

_sort_list(input_list)

Sort list using ClassRelationship comparison

Parameters:

input_list : list(ClassRelationship)

Sort list using the ClassRelationship.comparison_keys() comparison function

add_from_file(self, header_file)

Augment Diagram object from header file

Wrapper around the _build_helper() function, with file input, skipping building of the relationship lists and without object reset (new objects are added to the object).

add_from_file_list(self, file_list)

Augment Diagram object from list of header files

Wrapper around the _build_helper() function, with file_list input, skipping building of the relationship lists and without object reset (new objects are added to the object).

add_from_string(self, header_string)

Augment Diagram object from header string

Wrapper around the _build_helper() function, with string input, skipping building of the relationship lists and without object reset (new objects are added to the object).

add_from_string_list(self, string_list)

Augment Diagram object from list of header strings

Wrapper around the _build_helper() function, with string_list input, building the relationship lists and without object reset (new objects are added to the object).

build_aggregation_list(self)

Build list of aggregation relationships

This method loops over objects and finds members with type corresponding to other classes defined in the Diagram object (keeping a count of occurrences).

The procedure first builds an internal dictionary of relationships found, augmenting the count using the _augment_comp() function. In a second phase, ClassAggregationRelationship objects are created for each relationships, using the calculated count.

build_dependency_list(self)

Build list of dependency between objects

This method lists all the dependency relationships between objects contained in the Diagram object (external relationships are ignored).

The implementation establishes a list of available classes and loops over objects, list their methods adds a dependency relationship when a method takes an object as input.

build_inheritance_list(self)

Build list of inheritance between objects

This method lists all the inheritance relationships between objects contained in the Diagram object (external relationships are ignored).

The implementation establishes a list of available classes and loops over objects to obtain their inheritance. When parent classes are in the list of available classes, a ClassInheritanceRelationship object is added to the list.

build_nesting_list(self)

Build list of nested objects

build_relationship_lists(self)

Build inheritance and aggregation lists from parsed objects

This method successively calls the build_inheritance_list() and build_aggregation_list() methods.

clear(self)

Reinitialize object

create_from_file(self, header_file)

Initialize Diagram object from header file

Wrapper around the _build_helper() function, with file input, building the relationship lists and with object reset.

create_from_file_list(self, file_list)

Initialize Diagram object from list of header files

Wrapper around the _build_helper() function, with file_list input, building the relationship lists and with object reset.

create_from_string(self, header_string)

Initialize Diagram object from header string

Wrapper around the _build_helper() function, with string input, building the relationship lists and with object reset.

create_from_string_list(self, string_list)

Initialize Diagram object from list of header strings

Wrapper around the _build_helper() function, with string_list input, skipping building of the relationship lists and with object reset.

parse_objects(self, header_file, arg_type='string')

Parse objects

This method parses file of string inputs using the CppHeaderParser module and extracts internal objects for rendering.

Parameters:

header_file : str

A string containing C++ header code or a filename with C++ header code

arg_type : str

If set to string, header_file is considered to be a string, otherwise, it is assumed to be a filename

render(self)

Render full UML diagram

The string returned by this function should be ready to use with the PlantUML program. It includes all the parsed objects with their members, and the inheritance and aggregation relationships extracted from the list of objects.

Returns:

str

String containing the full string representation of the Diagram object, including objects and object relationships

sort_elements(self)

Sort elements in diagram

Sort the objects and relationship links. Objects are sorted using the Container.comparison_keys() comparison function and list are sorted using the _sort_list helper function.