Package diagram translation unit visitor. More...

Detailed Description

Package diagram translation unit visitor.

This class implements the clang::RecursiveASTVisitor interface for selected visitors relevant to generating package diagrams.

Definition at line 51 of file translation_unit_visitor.h.

#include <translation_unit_visitor.h>

Public Member Functions
	translation_unit_visitor (clang::SourceManager &sm, clanguml::package_diagram::model::diagram &diagram, const clanguml::config::package_diagram &config)
	Constructor.

	~translation_unit_visitor () override=default

virtual bool	VisitNamespaceDecl (clang::NamespaceDecl *ns)

virtual bool	VisitEnumDecl (clang::EnumDecl *decl)

virtual bool	VisitCXXRecordDecl (clang::CXXRecordDecl *cls)

virtual bool	VisitRecordDecl (clang::RecordDecl *cls)

virtual bool	VisitClassTemplateDecl (clang::ClassTemplateDecl *decl)

virtual bool	VisitFunctionDecl (clang::FunctionDecl *function_declaration)

virtual bool	VisitObjCCategoryDecl (clang::ObjCCategoryDecl *decl)

virtual bool	VisitObjCProtocolDecl (clang::ObjCProtocolDecl *decl)

virtual bool	VisitObjCInterfaceDecl (clang::ObjCInterfaceDecl *decl)

void	finalize ()
	Finalize diagram model.

Public Member Functions inherited from clanguml::common::visitor::translation_unit_visitor< ConfigT, DiagramT >
	translation_unit_visitor (clang::SourceManager &sm, DiagramT &diagram, const ConfigT &config)
	Constructor.

virtual	~translation_unit_visitor ()=default

void	set_tu_path (const std::string &translation_unit_path)

const std::filesystem::path &	tu_path () const
	Return relative path to current translation unit.

common::visitor::ast_id_mapper &	id_mapper () const
	Get reference to Clang AST to clang-uml id mapper.

clang::SourceManager &	source_manager () const
	Get clang::SourceManager.

void	set_source_location (const clang::Decl &decl, clanguml::common::model::source_location &element)
	Set source location in diagram element.

void	set_source_location (const clang::Expr &expr, clanguml::common::model::source_location &element)
	Set source location in diagram element.

void	set_source_location (const clang::Stmt &stmt, clanguml::common::model::source_location &element)

void	set_qualified_name (const clang::NamedDecl &decl, clanguml::common::model::element &element)

void	set_source_location (const clang::SourceLocation &location, clanguml::common::model::source_location &element)
	Set source location in diagram element.

void	set_owning_module (const clang::Decl &decl, clanguml::common::model::element &element)

virtual void	add_diagram_element (std::unique_ptr< common::model::template_element > element)

void	process_comment (const clang::NamedDecl &decl, clanguml::common::model::decorated_element &e)
	Process comment directives in comment attached to a declaration.

std::string	process_comment (const clang::RawComment *comment, clang::DiagnosticsEngine &de, clanguml::common::model::decorated_element &e)
	Process comment directives in raw comment.

bool	skip_system_header_decl (const clang::NamedDecl *decl) const

bool	should_include (const clang::NamedDecl *decl) const
	Check if the diagram should include a declaration.

DiagramT &	diagram ()
	Get diagram model reference.

const DiagramT &	diagram () const
	Get diagram model reference.

const ConfigT &	config () const
	Get diagram config instance.

Private Member Functions
eid_t	get_package_id (const clang::Decl *cls)
	Get global package id for declaration.

void	process_class_declaration (const clang::CXXRecordDecl &cls, found_relationships_t &relationships)
	Process class declaration.

void	process_class_children (const clang::CXXRecordDecl &cls, found_relationships_t &relationships)
	Process class children.

void	process_record_children (const clang::RecordDecl &cls, found_relationships_t &relationships)
	Process record children.

void	process_objc_container_children (const clang::ObjCContainerDecl &cls, found_relationships_t &relationships)
	Process ObjC container children.

void	process_class_bases (const clang::CXXRecordDecl &cls, found_relationships_t &relationships)
	Process record bases.

void	process_method (const clang::CXXMethodDecl &method, found_relationships_t &relationships)
	Process method declaration.

void	process_objc_method (const clang::ObjCMethodDecl &mf, found_relationships_t &relationships)
	Process ObjC method declaration.

void	process_template_method (const clang::FunctionTemplateDecl &method, found_relationships_t &relationships)
	Process template method declaration.

void	process_field (const clang::FieldDecl &field_declaration, found_relationships_t &relationships)
	Process member field.

void	process_objc_property (const clang::ObjCPropertyDecl &property_declaration, found_relationships_t &relationships)
	Process ObjC property.

void	process_interface_protocol (const clang::ObjCProtocolDecl &protocol_declaration, found_relationships_t &relationships)
	Process ObjC protocol implemented by certain interface.

void	process_static_field (const clang::VarDecl &field_declaration, found_relationships_t &relationships)
	Process static member field.

void	process_friend (const clang::FriendDecl &friend_declaration, found_relationships_t &relationships)
	Process friend declaration.

bool	find_relationships (const clang::Decl *decl, const clang::QualType &type, found_relationships_t &relationships, common::model::relationship_t relationship_hint=common::model::relationship_t::kDependency)
	Process type.

void	add_relationships (clang::Decl *cls, found_relationships_t &relationships)
	Add discovered relationships for `cls` to the diagram.

std::vector< eid_t >	get_parent_package_ids (eid_t id)

Additional Inherited Members
Public Types inherited from clanguml::common::visitor::translation_unit_visitor< ConfigT, DiagramT >
using	config_t = ConfigT

using	diagram_t = DiagramT

Protected Member Functions inherited from clanguml::common::visitor::translation_unit_visitor< ConfigT, DiagramT >
std::set< const clang::RawComment * > &	processed_comments ()

std::string	get_file_path (const std::string &file_location) const

Constructor & Destructor Documentation

◆ translation_unit_visitor()

clanguml::package_diagram::visitor::translation_unit_visitor::translation_unit_visitor	(	clang::SourceManager &	sm,
		clanguml::package_diagram::model::diagram &	diagram,
		const clanguml::config::package_diagram &	config
	)

Constructor.

Parameters

sm	Current source manager reference
diagram	Diagram model
config	Diagram configuration

Definition at line 38 of file translation_unit_visitor.cc.

    : visitor_specialization_t{sm, diagram, config}
{
}

◆ ~translation_unit_visitor()

clanguml::package_diagram::visitor::translation_unit_visitor::~translation_unit_visitor ( )

overridevirtualdefault

Reimplemented from clanguml::common::visitor::translation_unit_visitor< ConfigT, DiagramT >.

Member Function Documentation

◆ add_relationships()

void clanguml::package_diagram::visitor::translation_unit_visitor::add_relationships	(	clang::Decl *	cls,
		found_relationships_t &	relationships
	)

private

Add discovered relationships for cls to the diagram.

Parameters

cls	C/C++ entity declaration
relationships	List of discovered relationships

Definition at line 285 of file translation_unit_visitor.cc.

{
    // If this diagram has directory packages, first make sure that the
    // package for current directory is already in the model
    if (config().package_type() == config::package_type_t::kDirectory) {
        auto file = source_manager().getFilename(cls->getLocation()).str();
 
        if (file.empty())
            return;
 
        auto relative_file = config().make_path_relative(file);
        relative_file.make_preferred();
 
        common::model::path parent_path{
            relative_file.string(), common::model::path_type::kFilesystem};
        parent_path.pop_back();
        auto pkg_name = parent_path.name();
        parent_path.pop_back();
 
        auto pkg = std::make_unique<common::model::package>(
            config().using_namespace(), common::model::path_type::kFilesystem);
 
        pkg->set_name(pkg_name);
        pkg->set_namespace(parent_path);
        pkg->set_id(common::to_id(pkg->full_name(false)));
        set_source_location(*cls, *pkg);
 
        if (diagram().should_include(*pkg))
            diagram().add(parent_path, std::move(pkg));
    }
    else if (config().package_type() == config::package_type_t::kModule) {
        const auto *module = cls->getOwningModule();
 
        if (module == nullptr) {
            return;
        }
 
        std::string module_path_str = module->Name;
#if LLVM_VERSION_MAJOR < 15
        if (module->Kind == clang::Module::ModuleKind::PrivateModuleFragment) {
#else
        if (module->isPrivateModule()) {
#endif
            module_path_str = module->getTopLevelModule()->Name;
        }
 
        common::model::path module_path{
            module_path_str, common::model::path_type::kModule};
        module_path.pop_back();
 
        auto relative_module =
            config().make_module_relative(std::optional{module_path_str});
 
        common::model::path parent_path{
            relative_module, common::model::path_type::kModule};
        auto pkg_name = parent_path.name();
        parent_path.pop_back();
 
        auto pkg = std::make_unique<common::model::package>(
            config().using_module(), common::model::path_type::kModule);
 
        pkg->set_name(pkg_name);
        pkg->set_id(get_package_id(cls));
        // This is for diagram filters
        pkg->set_module(module_path.to_string());
        // This is for rendering nested package structure
        pkg->set_namespace(module_path);
        set_source_location(*cls, *pkg);
 
        if (diagram().should_include(*pkg))
            diagram().add(parent_path, std::move(pkg));
    }
 
    auto current_package_id = get_package_id(cls);
 
    if (current_package_id.value() == 0)
        // These are relationships to a global namespace, and we don't care
        // about those
        return;
 
    auto current_package = diagram().get(current_package_id);
 
    if (current_package) {
        std::vector<eid_t> parent_ids =
            get_parent_package_ids(current_package_id);
 
        for (auto &dependency : relationships) {
            const auto destination_id = std::get<0>(dependency);
 
            // Skip dependency relationships to parent packages
            if (util::contains(parent_ids, destination_id))
                continue;
 
            // Skip dependency relationship to child packages
            if (util::contains(
                    get_parent_package_ids(destination_id), current_package_id))
                continue;
 
            relationship r{relationship_t::kDependency, destination_id,
                common::model::access_t::kNone};
 
            if (std::get<2>(dependency) != nullptr)
                set_source_location(*std::get<2>(dependency), r);
 
            if (destination_id != current_package_id)
                current_package.value().add_relationship(std::move(r));
        }
    }
}

◆ finalize()

void clanguml::package_diagram::visitor::translation_unit_visitor::finalize ( )

Finalize diagram model.

Definition at line 850 of file translation_unit_visitor.cc.

850{ }

◆ find_relationships()

bool clanguml::package_diagram::visitor::translation_unit_visitor::find_relationships	(	const clang::Decl *	decl,
		const clang::QualType &	type,
		found_relationships_t &	relationships,
		common::model::relationship_t	relationship_hint = `common::model::relationship_t::kDependency`
	)

private

Process type.

Parameters

type	Reference to some C++ type
relationships	List of relationships discovered from this friend
relationship_hint	Default relationship type for discovered relationships

◆ get_package_id()

eid_t clanguml::package_diagram::visitor::translation_unit_visitor::get_package_id ( const clang::Decl * cls )

private

Get global package id for declaration.

This method calculates package diagram id based on either the namespace of the provided declaration or filesystem path of the source file where it was declared - depending on the diagram configuration.

This is necessary to infer dependency relationships between packages.

Parameters

cls	C++ entity declaration

Returns: Id of the package containing that declaration

Definition at line 396 of file translation_unit_visitor.cc.

{
    if (config().package_type() == config::package_type_t::kNamespace) {
        const auto *namespace_context =
            cls->getDeclContext()->getEnclosingNamespaceContext();
        if (namespace_context != nullptr && namespace_context->isNamespace()) {
            return common::to_id(
                *llvm::cast<clang::NamespaceDecl>(namespace_context));
        }
 
        return {};
    }
 
    if (config().package_type() == config::package_type_t::kModule) {
        const auto *module = cls->getOwningModule();
        if (module != nullptr) {
            std::string module_path = module->Name;
#if LLVM_VERSION_MAJOR < 15
            if (module->Kind ==
                clang::Module::ModuleKind::PrivateModuleFragment) {
#else
            if (module->isPrivateModule()) {
#endif
                module_path = module->getTopLevelModule()->Name;
            }
            return common::to_id(module_path);
        }
 
        return {};
    }
 
    auto file =
        source_manager().getFilename(cls->getSourceRange().getBegin()).str();
    auto relative_file = config().make_path_relative(file);
    relative_file.make_preferred();
    common::model::path parent_path{
        relative_file.string(), common::model::path_type::kFilesystem};
    parent_path.pop_back();
 
    return common::to_id(parent_path.to_string());
}

◆ get_parent_package_ids()

std::vector< eid_t > clanguml::package_diagram::visitor::translation_unit_visitor::get_parent_package_ids ( eid_t id )

private

Definition at line 852 of file translation_unit_visitor.cc.

{
    std::vector<eid_t> parent_ids;
    std::optional<eid_t> parent_id = id;
 
    while (parent_id.has_value()) {
        const auto pid = parent_id.value(); // NOLINT
        parent_ids.push_back(pid);
        auto parent = this->diagram().get(pid);
        if (parent)
            parent_id = parent.value().parent_element_id();
        else
            break;
    }
 
    return parent_ids;
}

◆ process_class_bases()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_class_bases	(	const clang::CXXRecordDecl &	cls,
		found_relationships_t &	relationships
	)

private

Process record bases.

Parameters

cls	Class declaration
relationships	List of relationships discovered from this class

Definition at line 499 of file translation_unit_visitor.cc.

{
    for (const auto &base : cls.bases()) {
        find_relationships(&cls, base.getType(), relationships);
    }
}

◆ process_class_children()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_class_children	(	const clang::CXXRecordDecl &	cls,
		found_relationships_t &	relationships
	)

private

Process class children.

Parameters

cls	Class declaration
relationships	List of relationships discovered from this class

Definition at line 448 of file translation_unit_visitor.cc.

{
    // Iterate over class methods (both regular and static)
    for (const auto *method : cls.methods()) {
        if (method != nullptr) {
            process_method(*method, relationships);
        }
    }
 
    if (const auto *decl_context =
            clang::dyn_cast_or_null<clang::DeclContext>(&cls);
        decl_context != nullptr) {
        // Iterate over class template methods
        for (auto const *decl_iterator : decl_context->decls()) {
            auto const *method_template =
                llvm::dyn_cast_or_null<clang::FunctionTemplateDecl>(
                    decl_iterator);
            if (method_template == nullptr)
                continue;
 
            process_template_method(*method_template, relationships);
        }
    }
 
    // Iterate over regular class fields
    for (const auto *field : cls.fields()) {
        if (field != nullptr)
            process_field(*field, relationships);
    }
 
    // Static fields have to be processed by iterating over variable
    // declarations
    for (const auto *decl : cls.decls()) {
        if (decl->getKind() == clang::Decl::Var) {
            const clang::VarDecl *variable_declaration{
                clang::dyn_cast_or_null<clang::VarDecl>(decl)};
            if ((variable_declaration != nullptr) &&
                variable_declaration->isStaticDataMember()) {
                process_static_field(*variable_declaration, relationships);
            }
        }
    }
 
    if (cls.isCompleteDefinition())
        for (const auto *friend_declaration : cls.friends()) {
            if (friend_declaration != nullptr)
                process_friend(*friend_declaration, relationships);
        }
}

◆ process_class_declaration()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_class_declaration	(	const clang::CXXRecordDecl &	cls,
		found_relationships_t &	relationships
	)

private

Process class declaration.

Parameters

cls	Class declaration
relationships	List of relationships discovered from this class

Definition at line 438 of file translation_unit_visitor.cc.

{
    // Look for dependency relationships in class children (fields, methods)
    process_class_children(cls, relationships);
 
    // Look for dependency relationships in class bases
    process_class_bases(cls, relationships);
}

◆ process_field()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_field	(	const clang::FieldDecl &	field_declaration,
		found_relationships_t &	relationships
	)

private

Process member field.

Parameters

field_declaration	Field declaration
relationships	List of relationships discovered from this field

Definition at line 625 of file translation_unit_visitor.cc.

{
    find_relationships(&field_declaration, field_declaration.getType(),
        relationships, relationship_t::kDependency);
}

◆ process_friend()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_friend	(	const clang::FriendDecl &	friend_declaration,
		found_relationships_t &	relationships
	)

private

Process friend declaration.

Parameters

friend_declaration	Field declaration
relationships	List of relationships discovered from this friend

Definition at line 670 of file translation_unit_visitor.cc.

{
    if (const auto *friend_type_declaration =
            friend_declaration.getFriendDecl()) {
        if (friend_type_declaration->isTemplateDecl()) {
            // TODO
        }
    }
    else if (const auto *friend_type = friend_declaration.getFriendType()) {
        find_relationships(
            &friend_declaration, friend_type->getType(), relationships);
    }
}

◆ process_interface_protocol()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_interface_protocol	(	const clang::ObjCProtocolDecl &	protocol_declaration,
		found_relationships_t &	relationships
	)

private

Process ObjC protocol implemented by certain interface.

Parameters

protocol_declaration	Protocol declaration
relationships	List of relationships discovered from this protocol

Definition at line 633 of file translation_unit_visitor.cc.

{
    const auto target_id = get_package_id(&protocol_declaration);
    relationships.emplace_back(
        target_id, relationship_t::kDependency, &protocol_declaration);
}

◆ process_method()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_method	(	const clang::CXXMethodDecl &	method,
		found_relationships_t &	relationships
	)

private

Process method declaration.

Parameters

method	Method declaration
relationships	List of relationships discovered from this method

Definition at line 507 of file translation_unit_visitor.cc.

{
    find_relationships(&method, method.getReturnType(), relationships);
 
    for (const auto *param : method.parameters()) {
        if (param != nullptr)
            find_relationships(&method, param->getType(), relationships);
    }
}

◆ process_objc_container_children()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_objc_container_children	(	const clang::ObjCContainerDecl &	cls,
		found_relationships_t &	relationships
	)

private

Process ObjC container children.

ObjC container in Clang is a base class for any object (e.g. interface, protocol or category) that can contain methods.

Parameters

cls	ObjC container declaration
relationships	List of relationships discovered from this objc container

Definition at line 567 of file translation_unit_visitor.cc.

{
    for (const auto *property : cls.properties()) {
        if (property != nullptr)
            process_objc_property(*property, relationships);
    }
 
    for (const auto *property : cls.class_properties()) {
        if (property != nullptr)
            process_objc_property(*property, relationships);
    }
 
    for (const auto *method : cls.methods()) {
        if (method != nullptr)
            process_objc_method(*method, relationships);
    }
 
    for (const auto *method : cls.class_methods()) {
        if (method != nullptr)
            process_objc_method(*method, relationships);
    }
 
    // Static fields have to be processed by iterating over variable
    // declarations
    for (const auto *decl : cls.decls()) {
        if (decl->getKind() == clang::Decl::Var) {
            const clang::VarDecl *variable_declaration{
                clang::dyn_cast_or_null<clang::VarDecl>(decl)};
            if ((variable_declaration != nullptr) &&
                variable_declaration->isStaticDataMember()) {
                process_static_field(*variable_declaration, relationships);
            }
        }
    }
}

◆ process_objc_method()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_objc_method	(	const clang::ObjCMethodDecl &	mf,
		found_relationships_t &	relationships
	)

private

Process ObjC method declaration.

Parameters

method	Method declaration
relationships	List of relationships discovered from this method

Definition at line 518 of file translation_unit_visitor.cc.

{
    find_relationships(&mf, mf.getReturnType(), relationships);
 
    for (const auto *param : mf.parameters()) {
        if (param != nullptr)
            find_relationships(&mf, param->getType(), relationships);
    }
}

◆ process_objc_property()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_objc_property	(	const clang::ObjCPropertyDecl &	property_declaration,
		found_relationships_t &	relationships
	)

private

Process ObjC property.

Parameters

property_declaration	Property declaration
relationships	List of relationships discovered from this property

Definition at line 642 of file translation_unit_visitor.cc.

{
    const auto *property_objc_id_type =
        property_declaration.getType()->getAsObjCQualifiedIdType();
    if (property_objc_id_type != nullptr) {
        const auto protocols_count = property_objc_id_type->getNumProtocols();
        for (auto i = 0U; i < protocols_count; i++) {
            const auto target_id =
                get_package_id(property_objc_id_type->getProtocol(i));
            relationships.emplace_back(
                target_id, relationship_t::kDependency, &property_declaration);
        }
    }
 
    find_relationships(&property_declaration, property_declaration.getType(),
        relationships, relationship_t::kDependency);
}

◆ process_record_children()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_record_children	(	const clang::RecordDecl &	cls,
		found_relationships_t &	relationships
	)

private

Process record children.

Parameters

cls	Record declaration
relationships	List of relationships discovered from this class

Definition at line 529 of file translation_unit_visitor.cc.

{
    if (const auto *decl_context =
            clang::dyn_cast_or_null<clang::DeclContext>(&cls);
        decl_context != nullptr) {
        // Iterate over class template methods
        for (auto const *decl_iterator : decl_context->decls()) {
            auto const *method_template =
                llvm::dyn_cast_or_null<clang::FunctionTemplateDecl>(
                    decl_iterator);
            if (method_template == nullptr)
                continue;
 
            process_template_method(*method_template, relationships);
        }
    }
 
    // Iterate over regular class fields
    for (const auto *field : cls.fields()) {
        if (field != nullptr)
            process_field(*field, relationships);
    }
 
    // Static fields have to be processed by iterating over variable
    // declarations
    for (const auto *decl : cls.decls()) {
        if (decl->getKind() == clang::Decl::Var) {
            const clang::VarDecl *variable_declaration{
                clang::dyn_cast_or_null<clang::VarDecl>(decl)};
            if ((variable_declaration != nullptr) &&
                variable_declaration->isStaticDataMember()) {
                process_static_field(*variable_declaration, relationships);
            }
        }
    }
}

◆ process_static_field()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_static_field	(	const clang::VarDecl &	field_declaration,
		found_relationships_t &	relationships
	)

private

Process static member field.

Parameters

field_declaration	Field declaration
relationships	List of relationships discovered from this field

Definition at line 662 of file translation_unit_visitor.cc.

{
    find_relationships(&field_declaration, field_declaration.getType(),
        relationships, relationship_t::kDependency);
}

◆ process_template_method()

void clanguml::package_diagram::visitor::translation_unit_visitor::process_template_method	(	const clang::FunctionTemplateDecl &	method,
		found_relationships_t &	relationships
	)

private

Process template method declaration.

Parameters

method	Method declaration
relationships	List of relationships discovered from this method

Definition at line 605 of file translation_unit_visitor.cc.

{
    // TODO: For now skip implicitly default methods
    //       in the future, add config option to choose
    if (method.getTemplatedDecl()->isDefaulted() &&
        !method.getTemplatedDecl()->isExplicitlyDefaulted())
        return;
 
    find_relationships(
        &method, method.getTemplatedDecl()->getReturnType(), relationships);
 
    for (const auto *param : method.getTemplatedDecl()->parameters()) {
        if (param != nullptr) {
            find_relationships(&method, param->getType(), relationships);
        }
    }
}

The documentation for this class was generated from the following files:

src/package_diagram/visitor/translation_unit_visitor.h
src/package_diagram/visitor/translation_unit_visitor.cc

Detailed Description

Public Member Functions

Private Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ translation_unit_visitor()

◆ ~translation_unit_visitor()

Member Function Documentation

◆ add_relationships()

◆ finalize()

◆ find_relationships()

◆ get_package_id()

◆ get_parent_package_ids()

◆ process_class_bases()

◆ process_class_children()

◆ process_class_declaration()

◆ process_field()

◆ process_friend()

◆ process_interface_protocol()

◆ process_method()

◆ process_objc_container_children()

◆ process_objc_method()

◆ process_objc_property()

◆ process_record_children()

◆ process_static_field()

◆ process_template_method()