Base class for diagram generators. More...

Detailed Description

template<typename ConfigType, typename DiagramType>
class clanguml::common::generators::plantuml::generator< ConfigType, DiagramType >

Base class for diagram generators.

Template Parameters

ConfigType	Configuration type
DiagramType	Diagram model type

Definition at line 52 of file generator.h.

#include <generator.h>

Public Member Functions
	generator (ConfigType &config, DiagramType &model)
	Constructor.

	~generator () override=default

void	generate (std::ostream &ostr) const override
	Generate diagram.

virtual void	generate_diagram (std::ostream &ostr) const =0
	Generate diagram specific part.

void	generate_config_layout_hints (std::ostream &ostr) const
	Generate diagram layout hints.

void	generate_plantuml_directives (std::ostream &ostr, const std::vector< std::string > &directives) const
	Generate PlantUML directives from config file.

void	generate_notes (std::ostream &ostr, const model::element &element) const
	Generate diagram notes.

void	generate_style (std::ostream &ostr, const std::string &element_type, const model::stylable_element &el) const
	Generate diagram element PlantUML style.

void	generate_metadata (std::ostream &ostr) const
	Generate comment with diagram metadata.

void	generate_title (std::ostream &ostr) const
	Generate diagram title.

template<typename E >
void	generate_link (std::ostream &ostr, const E &e) const
	Generate hyper link to element.

void	print_debug (const common::model::source_location &e, std::ostream &ostr) const
	Print debug information in diagram comments.

Public Member Functions inherited from clanguml::common::generators::generator< ConfigType, DiagramType >
	generator (ConfigType &config, DiagramType &model)
	Constructor.

virtual	~generator ()=default

virtual void	generate (std::ostream &ostr) const =0
	Generate diagram.

const ConfigType &	config () const
	Get reference to diagram config.

const DiagramType &	model () const
	Get reference to diagram model.

template<typename E >
inja::json	element_context (const E &e) const

std::optional< std::pair< std::string, std::string > >	get_link_pattern (const common::model::source_location &sl) const

std::optional< std::pair< std::string, std::string > >	get_tooltip_pattern (const common::model::source_location &sl) const

void	init_context ()
	Initialize diagram Jinja context.

void	update_context () const
	Update diagram Jinja context.

void	init_env ()

const inja::json &	context () const

inja::Environment &	env () const

Protected Attributes
std::set< std::string >	m_generated_aliases

Protected Attributes inherited from clanguml::common::generators::generator< ConfigType, DiagramType >
inja::json	m_context

inja::Environment	m_env

Private Member Functions
void	generate_row_column_hints (std::ostream &ostr, const std::string &entity_name, const config::layout_hint &hint) const

void	generate_position_hints (std::ostream &ostr, const std::string &entity_name, const config::layout_hint &hint) const

Constructor & Destructor Documentation

◆ generator()

template<typename ConfigType , typename DiagramType >

clanguml::common::generators::plantuml::generator< ConfigType, DiagramType >::generator	(	ConfigType &	config,
		DiagramType &	model
	)

inline

Constructor.

Parameters

config Reference to instance of model Reference to instance of clanguml::model::diagram

Definition at line 61 of file generator.h.

        : clanguml::common::generators::generator<ConfigType, DiagramType>{
              config, model}
    {
    }

◆ ~generator()

template<typename ConfigType , typename DiagramType >

clanguml::common::generators::plantuml::generator< ConfigType, DiagramType >::~generator ( )

overridevirtualdefault

Reimplemented from clanguml::common::generators::generator< ConfigType, DiagramType >.

Member Function Documentation

◆ generate()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate ( std::ostream & ostr ) const

overridevirtual

Generate diagram.

This is the main diagram generation entrypoint. It is responsible for calling other methods in appropriate order to generate the diagram into the output stream. It generates diagram elements, that are common to all types of diagrams in a given generator.

Parameters

ostr	Output stream

Implements clanguml::common::generators::generator< ConfigType, DiagramType >.

Definition at line 190 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
    const auto &model = generators::generator<C, D>::model();
 
    generators::generator<C, D>::update_context();
 
    if (!config.allow_empty_diagrams() && model.is_empty() &&
        config.puml().before.empty() && config.puml().after.empty()) {
        throw clanguml::error::empty_diagram_error{
            "Diagram configuration resulted in empty diagram."};
    }
 
    ostr << "@startuml" << '\n';
 
    generate_title(ostr);
 
    // Generate PlantUML directives before auto generated content
    generate_plantuml_directives(ostr, config.puml().before);
 
    generate_diagram(ostr);
 
    // Generate PlantUML directives after auto generated content
    generate_plantuml_directives(ostr, config.puml().after);
 
    generate_metadata(ostr);
 
    ostr << "@enduml" << '\n';
}

◆ generate_config_layout_hints()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_config_layout_hints ( std::ostream & ostr ) const

Generate diagram layout hints.

This method adds to the diagram any layout hints that were provided in the configuration file.

Parameters

ostr	Output stream

Definition at line 221 of file generator.h.

{
    using namespace clanguml::util;
 
    const auto &config = generators::generator<C, D>::config();
 
    // Generate layout hints
    for (const auto &[entity_name, hints] : config.layout()) {
        for (const auto &hint : hints) {
            try {
                if (hint.hint == config::hint_t::together) {
                    // 'together' layout hint is handled separately
                }
                else if (hint.hint == config::hint_t::row ||
                    hint.hint == config::hint_t::column) {
                    generate_row_column_hints(ostr, entity_name, hint);
                }
                else {
                    generate_position_hints(ostr, entity_name, hint);
                }
            }
            catch (clanguml::error::uml_alias_missing &e) {
                LOG_DBG("=== Skipping layout hint '{}' from {} due "
                        "to: {}",
                    to_string(hint.hint), entity_name, e.what());
            }
        }
    }
}

◆ generate_diagram()

template<typename ConfigType , typename DiagramType >

virtual void clanguml::common::generators::plantuml::generator< ConfigType, DiagramType >::generate_diagram ( std::ostream & ostr ) const

pure virtual

Generate diagram specific part.

This method must be implemented in subclasses for specific diagram types.

Parameters

ostr	Output stream

Implemented in clanguml::class_diagram::generators::plantuml::generator, clanguml::include_diagram::generators::plantuml::generator, clanguml::package_diagram::generators::plantuml::generator, and clanguml::sequence_diagram::generators::plantuml::generator.

◆ generate_link()

template<typename C , typename D >

template<typename E >

void clanguml::common::generators::plantuml::generator< C, D >::generate_link	(	std::ostream &	ostr,
		const E &	e
	)		const

Generate hyper link to element.

This method renders links to URL's based on templates provided in the configuration file (e.g. Git browser with specific line and column offset)

Parameters

ostr	Output stream
e	Reference to diagram element

Template Parameters

E	Diagram element type

Definition at line 446 of file generator.h.

{
    if (e.file().empty() && e.file_relative().empty())
        return;
 
    auto maybe_link_pattern = generators::generator<C, D>::get_link_pattern(e);
 
    if (!maybe_link_pattern) {
        return;
    }
 
    const auto &[link_prefix, link_pattern] = *maybe_link_pattern;
 
    ostr << " [[";
    try {
        if (!link_pattern.empty()) {
            auto ec = generators::generator<C, D>::element_context(e);
            common::generators::make_context_source_relative(ec, link_prefix);
            ostr << generators::generator<C, D>::env().render(
                std::string_view{link_pattern}, ec);
        }
    }
    catch (const inja::json::parse_error &e) {
        LOG_ERROR("Failed to parse Jinja template: {}", link_pattern);
    }
    catch (const std::exception &e) {
        LOG_ERROR("Failed to render PlantUML directive: \n{}\n due to: {}",
            link_pattern, e.what());
    }
 
    auto maybe_tooltip_pattern =
        generators::generator<C, D>::get_tooltip_pattern(e);
 
    if (maybe_tooltip_pattern) {
        const auto &[tooltip_prefix, tooltip_pattern] = *maybe_tooltip_pattern;
 
        ostr << "{";
        try {
            auto ec = generators::generator<C, D>::element_context(e);
            common::generators::make_context_source_relative(
                ec, tooltip_prefix);
            if (!tooltip_pattern.empty()) {
                ostr << generators::generator<C, D>::env().render(
                    std::string_view{tooltip_pattern}, ec);
            }
        }
        catch (const inja::json::parse_error &e) {
            LOG_ERROR("Failed to parse Jinja template: {}", tooltip_pattern);
        }
        catch (const std::exception &e) {
            LOG_ERROR("Failed to render PlantUML directive: \n{}\n due to: {}",
                tooltip_pattern, e.what());
        }
        ostr << "}";
    }
    ostr << "]]";
}

◆ generate_metadata()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_metadata ( std::ostream & ostr ) const

Generate comment with diagram metadata.

Parameters

ostr	Output stream

Definition at line 422 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
 
    if (config.generate_metadata()) {
        ostr << '\n'
             << "'Generated with clang-uml, version "
             << clanguml::version::CLANG_UML_VERSION << '\n'
             << "'LLVM version " << clang::getClangFullVersion() << '\n';
    }
}

◆ generate_notes()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_notes	(	std::ostream &	ostr,
		const model::element &	element
	)		const

Generate diagram notes.

This method adds any notes in the diagram, which were declared in the code using inline directives

Parameters

ostr	Output stream
element	Element to which the note should be attached

Definition at line 406 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
 
    for (const auto &decorator : e.decorators()) {
        auto note = std::dynamic_pointer_cast<decorators::note>(decorator);
        if (note && note->applies_to_diagram(config.name)) {
            ostr << "note " << note->position << " of " << e.alias() << '\n'
                 << note->text << '\n'
                 << "end note\n";
        }
    }
}

◆ generate_plantuml_directives()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_plantuml_directives	(	std::ostream &	ostr,
		const std::vector< std::string > &	directives
	)		const

Generate PlantUML directives from config file.

This method renders the PlantUML directives provided in the configuration file, including resolving any element aliases and Jinja templates.

Parameters

ostr	Output stream
directives	List of directives from the configuration file

Definition at line 330 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
    const auto &model = generators::generator<C, D>::model();
 
    using common::model::namespace_;
 
    for (const auto &d : directives) {
        try {
            // Render the directive with template engine first
            std::string directive{generators::generator<C, D>::env().render(
                std::string_view{d}, generators::generator<C, D>::context())};
 
            // Now search for alias `@A()` directives in the text
            // (this is deprecated)
            std::tuple<std::string, size_t, size_t> alias_match;
            while (util::find_element_alias(directive, alias_match)) {
                const auto full_name =
                    config.using_namespace() | std::get<0>(alias_match);
                auto element_opt = model.get(full_name.to_string());
 
                if (element_opt)
                    directive.replace(std::get<1>(alias_match),
                        std::get<2>(alias_match), element_opt.value().alias());
                else {
                    LOG_WARN("Cannot find clang-uml alias for element {}",
                        full_name.to_string());
                    directive.replace(std::get<1>(alias_match),
                        std::get<2>(alias_match), "UNKNOWN_ALIAS");
                }
            }
 
            ostr << directive << '\n';
        }
        catch (const clanguml::error::uml_alias_missing &e) {
            LOG_WARN("Failed to render PlantUML directive due to unresolvable "
                     "alias: {}",
                e.what());
        }
        catch (const inja::json::parse_error &e) {
            LOG_WARN("Failed to parse Jinja template: {}", d);
        }
        catch (const inja::json::exception &e) {
            LOG_WARN("Failed to render PlantUML directive: \n{}\n due to: {}",
                d, e.what());
        }
        catch (const std::regex_error &e) {
            LOG_WARN("Failed to render PlantUML directive: \n{}\n due to "
                     "std::regex_error: {}",
                d, e.what());
        }
        catch (const std::exception &e) {
            LOG_WARN("Failed to render PlantUML directive: \n{}\n due to: {}",
                d, e.what());
        }
    }
}

◆ generate_position_hints()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_position_hints	(	std::ostream &	ostr,
		const std::string &	entity_name,
		const config::layout_hint &	hint
	)		const

private

Definition at line 299 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
    const auto &model = generators::generator<C, D>::model();
 
    const auto &uns = config.using_namespace();
 
    const auto &hint_entity = std::get<std::string>(hint.entity);
 
    auto element_opt = model.get(entity_name);
    if (!element_opt)
        element_opt = model.get((uns | entity_name).to_string());
 
    auto hint_element_opt = model.get(hint_entity);
    if (!hint_element_opt)
        hint_element_opt = model.get((uns | hint_entity).to_string());
 
    if (!element_opt || !hint_element_opt)
        return;
 
    std::stringstream hint_str;
 
    hint_str << element_opt.value().alias() << " -[hidden]"
             << clanguml::config::to_string(hint.hint) << "- "
             << hint_element_opt.value().alias() << '\n';
 
    ostr << hint_str.str();
}

◆ generate_row_column_hints()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_row_column_hints	(	std::ostream &	ostr,
		const std::string &	entity_name,
		const config::layout_hint &	hint
	)		const

private

Definition at line 252 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
    const auto &model = generators::generator<C, D>::model();
 
    const auto &uns = config.using_namespace();
 
    std::vector<std::string> group_elements;
    std::vector<std::pair<std::string, std::string>> element_aliases_pairs;
 
    group_elements.push_back(entity_name);
    const auto &group_tail = std::get<std::vector<std::string>>(hint.entity);
    std::copy(group_tail.begin(), group_tail.end(),
        std::back_inserter(group_elements));
 
    auto element_opt = model.get(entity_name);
    if (!element_opt)
        element_opt = model.get((uns | entity_name).to_string());
 
    for (auto it = cbegin(group_elements);
         it != cend(group_elements) && std::next(it) != cend(group_elements);
         ++it) {
        const auto &first = *it;
        const auto &second = *std::next(it);
 
        auto first_opt = model.get(first);
        if (!first_opt)
            first_opt = model.get((uns | first).to_string());
 
        auto second_opt = model.get(second);
        if (!second_opt)
            second_opt = model.get((uns | second).to_string());
 
        element_aliases_pairs.emplace_back(
            first_opt.value().alias(), second_opt.value().alias());
    }
 
    std::string hint_direction =
        hint.hint == clanguml::config::hint_t::row ? "right" : "down";
 
    for (const auto &[f, s] : element_aliases_pairs) {
        ostr << f << " -[hidden]" << hint_direction << "- " << s << '\n';
    }
}

◆ generate_style()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_style	(	std::ostream &	ostr,
		const std::string &	element_type,
		const model::stylable_element &	el
	)		const

Generate diagram element PlantUML style.

This method renders a style for a specific el element if specified in the config file or inline comment directive.

Parameters

ostr	Output stream
element_type	Name of the element type (e.g. "class")
el	Reference to a stylable diagram element

Definition at line 390 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
 
    if (el.style() && !el.style().value().empty()) // NOLINT
        ostr << " " << *el.style();                // NOLINT
    else if (config.puml) {
        if (const auto config_style = config.puml().get_style(element_type);
            config_style) {
            ostr << " " << *config_style;
        }
    }
}

◆ generate_title()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::generate_title ( std::ostream & ostr ) const

Generate diagram title.

Generates a PlantUML diagram title directive if diagram title is provided in the diagram configuration.

Parameters

ostr	Output stream

Definition at line 435 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
 
    if (config.title) {
        ostr << "title " << config.title() << '\n';
    }
}

◆ print_debug()

template<typename C , typename D >

void clanguml::common::generators::plantuml::generator< C, D >::print_debug	(	const common::model::source_location &	e,
		std::ostream &	ostr
	)		const

Print debug information in diagram comments.

Parameters

m	Diagram element to describe
ostr	Output stream

Definition at line 505 of file generator.h.

{
    const auto &config = generators::generator<C, D>::config();
 
    if (config.debug_mode())
        ostr << "' " << e.file() << ":" << e.line() << '\n';
}

Member Data Documentation

◆ m_generated_aliases

template<typename ConfigType , typename DiagramType >

std::set<std::string> clanguml::common::generators::plantuml::generator< ConfigType, DiagramType >::m_generated_aliases

mutableprotected

Definition at line 186 of file generator.h.

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

src/common/generators/plantuml/generator.h

Detailed Description

Public Member Functions

Protected Attributes

Private Member Functions

Constructor & Destructor Documentation

◆ generator()

◆ ~generator()

Member Function Documentation

◆ generate()

◆ generate_config_layout_hints()

◆ generate_diagram()

◆ generate_link()

◆ generate_metadata()

◆ generate_notes()

◆ generate_plantuml_directives()

◆ generate_position_hints()

◆ generate_row_column_hints()

◆ generate_style()

◆ generate_title()

◆ print_debug()

Member Data Documentation

◆ m_generated_aliases