Configuration file related classes. More...

Detailed Description

Configuration file related classes.

Classes
struct	class_diagram
	Class diagram configuration. More...

struct	config
	Represents entire configuration file. More...

struct	context_config

struct	diagram
	Common diagram configuration type. More...

struct	diagram_template
	Definition of diagram template. More...

struct	filter

struct	generate_links_config

struct	git_config

struct	include_diagram
	Include diagram configuration. More...

struct	inheritable_diagram_options
	Represents subset of inheritable configuration options. More...

struct	layout_hint

struct	mermaid
	MermaidJS diagram config section. More...

struct	option
	Generic configuration option type. More...

struct	option_with_alt_names_tag

struct	package_diagram
	Package diagram configuration. More...

struct	plantuml
	PlantUML diagram config section. More...

struct	plantuml_keyword_mapping_t

struct	relationship_hint_t

struct	sequence_diagram
	Sequence diagram configuration. More...

struct	source_location

struct	type_aliases_longer_first_comparator

Typedefs
using	layout_hints = std::map< std::string, std::vector< layout_hint > >

using	relationship_hints_t = std::map< std::string, relationship_hint_t >

using	type_aliases_t = std::map< std::string, std::string >

using	type_aliases_longer_first_t = std::map< std::string, std::string, type_aliases_longer_first_comparator >

using	config_ptr = std::unique_ptr< config >

Enumerations
enum class	method_arguments { full , abbreviated , none }

enum class	method_type { constructor , destructor , assignment , operator_ , defaulted , deleted , static_ }

enum class	callee_type { constructor , assignment , operator_ , defaulted , static_ , method , function , function_template , lambda , cuda_kernel , cuda_device }

enum class	package_type_t { kNamespace , kDirectory , kModule }

enum class	member_order_t { lexical , as_is }

enum class	comment_parser_t { plain , clang }

enum class	filter_mode_t { basic , advanced }

enum class	context_direction_t { inward , outward , any }

enum class	hint_t { up , down , left , right , together , row , column }

enum class	location_t { marker , fileline , function }

enum class	option_inherit_mode { kOverride , kAppend }

Functions
std::string	to_string (const hint_t t)

std::string	to_string (const method_arguments ma)

std::string	to_string (method_type mt)

std::string	to_string (callee_type mt)

std::string	to_string (const comment_parser_t cp)

std::string	to_string (location_t cp)

std::string	to_string (package_type_t pt)

std::string	to_string (member_order_t mo)

std::string	to_string (context_direction_t cd)

std::string	to_string (filter_mode_t fm)

template<>
void	append_value< plantuml > (plantuml &l, const plantuml &r)

config	load (const std::string &config_file, bool inherit=true, std::optional< bool > paths_relative_to_pwd={}, std::optional< bool > no_metadata={}, bool validate=true)
	Load and parse `.clang-uml` configuration file.

YAML::Emitter &	operator<< (YAML::Emitter &out, const config &c)

YAML::Emitter &	operator<< (YAML::Emitter &out, const inheritable_diagram_options &c)

YAML::Emitter &	operator<< (YAML::Emitter &out, const filter &f)

YAML::Emitter &	operator<< (YAML::Emitter &out, const plantuml &p)

YAML::Emitter &	operator<< (YAML::Emitter &out, const method_arguments &ma)

YAML::Emitter &	operator<< (YAML::Emitter &out, const generate_links_config &glc)

YAML::Emitter &	operator<< (YAML::Emitter &out, const git_config &gc)

YAML::Emitter &	operator<< (YAML::Emitter &out, const relationship_hint_t &rh)

YAML::Emitter &	operator<< (YAML::Emitter &out, const comment_parser_t &cp)

YAML::Emitter &	operator<< (YAML::Emitter &out, const hint_t &h)

YAML::Emitter &	operator<< (YAML::Emitter &out, const class_diagram &c)

YAML::Emitter &	operator<< (YAML::Emitter &out, const sequence_diagram &c)

YAML::Emitter &	operator<< (YAML::Emitter &out, const include_diagram &c)

YAML::Emitter &	operator<< (YAML::Emitter &out, const package_diagram &c)

YAML::Emitter &	operator<< (YAML::Emitter &out, const layout_hint &c)

YAML::Emitter &	operator<< (YAML::Emitter &out, const source_location &sc)

template<typename T >
YAML::Emitter &	operator<< (YAML::Emitter &out, const option< T > &o)

const std::string &	get_predefined_diagram_templates ()
	Return YAML with predefined diagram templates.

template<typename T >
void	append_value (T &l, const T &r)

template<typename T >
void	append_value (std::vector< T > &l, const std::vector< T > &r)

template<typename K , typename V >
void	append_value (std::map< K, V > &l, const std::map< K, V > &r)

YAML::Emitter &	operator<< (YAML::Emitter &out, const method_type &m)

YAML::Emitter &	operator<< (YAML::Emitter &out, const callee_type &m)

YAML::Emitter &	operator<< (YAML::Emitter &out, const member_order_t &r)

YAML::Emitter &	operator<< (YAML::Emitter &out, const package_type_t &r)

YAML::Emitter &	operator<< (YAML::Emitter &out, const context_config &c)

Variables
const std::string	schema_str

Typedef Documentation

◆ config_ptr

using clanguml::config::config_ptr = typedef std::unique_ptr<config>

Definition at line 790 of file config.h.

◆ layout_hints

using clanguml::config::layout_hints = typedef std::map<std::string, std::vector<layout_hint> >

Definition at line 455 of file config.h.

◆ relationship_hints_t

using clanguml::config::relationship_hints_t = typedef std::map<std::string, relationship_hint_t>

Definition at line 500 of file config.h.

◆ type_aliases_longer_first_t

using clanguml::config::type_aliases_longer_first_t = typedef std::map<std::string, std::string, type_aliases_longer_first_comparator>

Definition at line 513 of file config.h.

◆ type_aliases_t

using clanguml::config::type_aliases_t = typedef std::map<std::string, std::string>

Definition at line 502 of file config.h.

Enumeration Type Documentation

◆ callee_type

enum class clanguml::config::callee_type

strong

Types of call expressions, which can be used in sequence diagram filters

Enumerator
constructor
assignment
operator_
defaulted
static_
method
function
function_template
lambda
cuda_kernel
cuda_device

Definition at line 72 of file config.h.

                       {
    constructor,
    assignment,
    operator_,
    defaulted,
    static_,
    method,
    function,
    function_template,
    lambda,
    cuda_kernel,
    cuda_device
};

◆ comment_parser_t

enum class clanguml::config::comment_parser_t

strong

Which comment parser should be used

Enumerator
plain	Basic string parser
clang	Clang's internal comment parser with structured output

Definition at line 107 of file config.h.

                            {
    plain, /*!< Basic string parser */
    clang  /*!< Clang's internal comment parser with structured output */
};

◆ context_direction_t

enum class clanguml::config::context_direction_t

strong

Enumerator
inward
outward
any

Definition at line 169 of file config.h.

169{ inward, outward, any };

◆ filter_mode_t

enum class clanguml::config::filter_mode_t

strong

Enumerator
basic	Default filter structure without logical operators
advanced	Advanced filter config with logical operators

Definition at line 119 of file config.h.

                         {
    basic,   /*!< Default filter structure without logical operators */
    advanced /*!< Advanced filter config with logical operators */
};

◆ hint_t

enum class clanguml::config::hint_t

strong

Enumerator
up
down
left
right
together
row
column

Definition at line 446 of file config.h.

446{ up, down, left, right, together, row, column };

◆ location_t

enum class clanguml::config::location_t

strong

Enumerator
marker
fileline
function

Definition at line 516 of file config.h.

516{ marker, fileline, function };

◆ member_order_t

enum class clanguml::config::member_order_t

strong

How class methods and members should be ordered in diagrams

Enumerator

lexical

as_is

Lexical order based on entire method or member signature without type

As written in source code

Definition at line 98 of file config.h.

                          {
    lexical, /*! Lexical order based on entire method or member signature
                without type */
    as_is    /*! As written in source code */
};

◆ method_arguments

enum class clanguml::config::method_arguments

strong

Select how the method arguments should be rendered

Enumerator

full

abbreviated

Full

none

Abrreviate, string between '(' and ')' is cropped

Empty string between '(' and ')'

Definition at line 50 of file config.h.

                            {
    full,        /*! Full */
    abbreviated, /*! Abrreviate, string between '(' and ')' is cropped */
    none         /*! Empty string between '(' and ')' */
};

◆ method_type

enum class clanguml::config::method_type

strong

Types of methods, which can be used in diagram filters

Enumerator
constructor
destructor
assignment
operator_
defaulted
deleted
static_

Definition at line 59 of file config.h.

                       {
    constructor,
    destructor,
    assignment,
    operator_,
    defaulted,
    deleted,
    static_
};

◆ option_inherit_mode

enum class clanguml::config::option_inherit_mode

strong

Possible option inheritance methods from top level to diagram level.

Enumerator
kOverride	Override entire options
kAppend	Append to list options

Definition at line 45 of file option.h.

                               {
    kOverride, /*!< Override entire options */
    kAppend    /*!< Append to list options */
};

◆ package_type_t

enum class clanguml::config::package_type_t

strong

How packages in diagrams should be generated

Enumerator
kNamespace	From namespaces
kDirectory	From directories
kModule	From modules

Definition at line 89 of file config.h.

                          {
    kNamespace, /*!< From namespaces */
    kDirectory, /*!< From directories */
    kModule     /*!< From modules */
};

Function Documentation

◆ append_value() [1/3]

template<typename K , typename V >

void clanguml::config::append_value	(	std::map< K, V > &	l,
		const std::map< K, V > &	r
	)

Definition at line 37 of file option.h.

{
    l.insert(r.begin(), r.end());
}

◆ append_value() [2/3]

template<typename T >

void clanguml::config::append_value	(	std::vector< T > &	l,
		const std::vector< T > &	r
	)

Definition at line 31 of file option.h.

{
    l.insert(std::end(l), r.begin(), r.end());
}

◆ append_value() [3/3]

template<typename T >

void clanguml::config::append_value	(	T &	l,
		const T &	r
	)

Definition at line 28 of file option.h.

28{ l = r; }

◆ append_value< plantuml >()

template<>

void clanguml::config::append_value< plantuml >	(	plantuml &	l,
		const plantuml &	r
	)

Definition at line 503 of file config.cc.

{
    l.append(r);
}

◆ get_predefined_diagram_templates()

const std::string & clanguml::config::get_predefined_diagram_templates ( )

Return YAML with predefined diagram templates.

Returns: YAML definition of predefined diagram templates

Definition at line 24 of file diagram_templates.cc.

{
    static const std::string predefined_diagram_templates =
        R"(# Predefined diagram templates
parents_hierarchy_tmpl:
  description: Generate class parents inheritance diagram
  type: class

◆ load()

config clanguml::config::load	(	const std::string &	config_file,
		bool	inherit = `true`,
		std::optional< bool >	paths_relative_to_pwd = `{}`,
		std::optional< bool >	no_metadata = `{}`,
		bool	validate = `true`
	)

Load and parse .clang-uml configuration file.

This function takes the path to the configuration file and some options, parses the YAML file and creates a

See also: clanguml::config::config instance.

Parameters

config_file	Path to the configuration file
inherit	If true, common options will be propagated to diagram configs
paths_relative_to_pwd	Whether the paths in the configuration file should be relative to the parent directory of the configuration file or to the current directory (`$PWD`)
no_metadata	Whether the diagram should skip metadata at the end
validate	If true, perform schema validation

Returns: Configuration instance

Definition at line 989 of file yaml_decoders.cc.

{
    try {
        auto schema = YAML::Load(clanguml::config::schema_str);
        auto schema_validator = miroir::Validator<YAML::Node>(schema);
 
        YAML::Node doc;
        std::filesystem::path config_file_path{};
 
        if (config_file == "-") {
            std::istreambuf_iterator<char> stdin_stream_begin{std::cin};
            std::istreambuf_iterator<char> stdin_stream_end{};
            std::string stdin_stream_str{stdin_stream_begin, stdin_stream_end};
 
            doc = YAML::Load(stdin_stream_str);
        }
        else {
            doc = YAML::LoadFile(config_file);
        }
 
        // Store the parent path of the config_file to properly resolve
        // relative paths in config file
        if (has_key(doc, "__parent_path"))
            doc.remove("__parent_path");
        if (config_file == "-") {
            config_file_path = std::filesystem::current_path();
            doc.force_insert("__parent_path", config_file_path.string());
        }
        else {
            config_file_path =
                canonical(absolute(std::filesystem::path{config_file}));
            doc.force_insert(
                "__parent_path", config_file_path.parent_path().string());
        }
 
        LOG_DBG("Effective config file path is {}", config_file_path.string());
 
        //
        // If no relative_to path is specified in the config, make all paths
        // resolvable against the parent directory of the .clang-uml config
        // file, or against the $PWD if it was specified so in the command
        // line
        //
        if (!doc["relative_to"]) {
            bool paths_relative_to_config_file = true;
 
            if (doc["paths_relative_to_config_file"] &&
                !doc["paths_relative_to_config_file"].as<bool>())
                paths_relative_to_config_file = false;
 
            if (paths_relative_to_pwd && *paths_relative_to_pwd)
                paths_relative_to_config_file = false;
 
            if (paths_relative_to_config_file)
                doc["relative_to"] = config_file_path.parent_path().string();
            else
                doc["relative_to"] = std::filesystem::current_path().string();
        }
 
        if (no_metadata.has_value()) {
            doc["generate_metadata"] = !no_metadata.value();
        }
 
        //
        // Resolve common path-like config options relative to `relative_to`
        //
        if (!doc["output_directory"]) {
            doc["output_directory"] = ".";
        }
        resolve_option_path(doc, "output_directory");
 
        if (!doc["compilation_database_dir"]) {
            doc["compilation_database_dir"] = ".";
        }
        resolve_option_path(doc, "compilation_database_dir");
 
        // If the current directory is also a git repository,
        // load some config values, which can be included in the
        // generated diagrams
        if (util::is_git_repository() && !doc["git"]) {
            YAML::Node git_config{YAML::NodeType::Map};
            git_config["branch"] = util::get_git_branch();
            git_config["revision"] = util::get_git_revision();
            git_config["commit"] = util::get_git_commit();
            git_config["toplevel"] = util::get_git_toplevel_dir();
 
            doc["git"] = git_config;
        }
 
        // Resolve diagram includes
        auto diagrams = doc["diagrams"];
 
        assert(diagrams.Type() == YAML::NodeType::Map);
 
        for (auto d : diagrams) {
            auto name = d.first.as<std::string>();
            std::shared_ptr<clanguml::config::diagram> diagram_config{};
            auto parent_path = doc["__parent_path"].as<std::string>();
 
            if (has_key(d.second, "include!")) {
                auto include_path = std::filesystem::path{parent_path};
                include_path /= d.second["include!"].as<std::string>();
 
                YAML::Node included_node =
                    YAML::LoadFile(include_path.string());
 
                diagrams[name] = included_node;
            }
        }
 
        if (validate) {
            auto schema_errors = schema_validator.validate(doc);
 
            if (!schema_errors.empty()) {
                // print validation errors
                for (const auto &err : schema_errors) {
                    LOG_ERROR("Schema error: {}", err.description());
                }
 
                throw YAML::Exception({}, "Invalid configuration schema");
            }
        }
 
        auto d = doc.as<config>();
 
        if (inherit)
            d.inherit();
 
        d.initialize_diagram_templates();
 
        return d;
    }
    catch (YAML::BadFile &e) {
        throw std::runtime_error(fmt::format(
            "Could not open config file {}: {}", config_file, e.what()));
    }
    catch (YAML::Exception &e) {
        throw std::runtime_error(fmt::format(
            "Cannot parse YAML file {}: {}", config_file, e.what()));
    }
}

◆ operator<<() [1/5]

YAML::Emitter & clanguml::config::operator<<	(	YAML::Emitter &	out,
		const callee_type &	m
	)

Definition at line 95 of file yaml_emitters.cc.

{
    out << to_string(m);
    return out;
}

◆ operator<<() [2/5]

YAML::Emitter & clanguml::config::operator<<	(	YAML::Emitter &	out,
		const context_config &	c
	)

Definition at line 113 of file yaml_emitters.cc.

{
    out << YAML::BeginMap;
    out << YAML::Key << "match";
    out << YAML::BeginMap;
    out << YAML::Key << "radius" << YAML::Value << c.radius;
    out << YAML::Key << "pattern" << YAML::Value << c.pattern;
    out << YAML::EndMap;
    out << YAML::EndMap;
 
    return out;
}

◆ operator<<() [3/5]

YAML::Emitter & clanguml::config::operator<<	(	YAML::Emitter &	out,
		const member_order_t &	r
	)

Definition at line 101 of file yaml_emitters.cc.

{
    out << to_string(r);
    return out;
}

◆ operator<<() [4/5]

YAML::Emitter & clanguml::config::operator<<	(	YAML::Emitter &	out,
		const method_type &	m
	)

Definition at line 89 of file yaml_emitters.cc.

{
    out << to_string(m);
    return out;
}

◆ operator<<() [5/5]

YAML::Emitter & clanguml::config::operator<<	(	YAML::Emitter &	out,
		const package_type_t &	r
	)

Definition at line 107 of file yaml_emitters.cc.

{
    out << to_string(r);
    return out;
}

◆ to_string() [1/10]

std::string clanguml::config::to_string ( callee_type mt )

Definition at line 88 of file config.cc.

{
    switch (mt) {
    case callee_type::constructor:
        return "constructor";
    case callee_type::assignment:
        return "assignment";
    case callee_type::operator_:
        return "operator";
    case callee_type::defaulted:
        return "defaulted";
    case callee_type::static_:
        return "static";
    case callee_type::method:
        return "method";
    case callee_type::function:
        return "function";
    case callee_type::function_template:
        return "function_template";
    case callee_type::lambda:
        return "lambda";
    case callee_type::cuda_kernel:
        return "cuda_kernel";
    case callee_type::cuda_device:
        return "cuda_device";
    }
 
    assert(false);
    return "";
}

◆ to_string() [2/10]

std::string clanguml::config::to_string ( const comment_parser_t cp )

Definition at line 119 of file config.cc.

{
    switch (cp) {
    case comment_parser_t::clang:
        return "clang";
    case comment_parser_t::plain:
        return "plain";
    default:
        assert(false);
        return "";
    }
}

◆ to_string() [3/10]

std::string clanguml::config::to_string ( const hint_t t )

Definition at line 27 of file config.cc.

{
    switch (t) {
    case hint_t::up:
        return "up";
    case hint_t::down:
        return "down";
    case hint_t::left:
        return "left";
    case hint_t::right:
        return "right";
    case hint_t::together:
        return "together";
    case hint_t::row:
        return "row";
    case hint_t::column:
        return "column";
    default:
        assert(false);
        return "";
    }
}

◆ to_string() [4/10]

std::string clanguml::config::to_string ( const method_arguments ma )

Definition at line 50 of file config.cc.

{
    switch (ma) {
    case method_arguments::full:
        return "full";
    case method_arguments::abbreviated:
        return "abbreviated";
    case method_arguments::none:
        return "none";
    default:
        assert(false);
        return "";
    }
}

◆ to_string() [5/10]

std::string clanguml::config::to_string ( context_direction_t cd )

Definition at line 174 of file config.cc.

{
    switch (cd) {
    case context_direction_t::inward:
        return "inward";
    case context_direction_t::outward:
        return "outward";
    case context_direction_t::any:
        return "any";
    default:
        assert(false);
        return "";
    }
}

◆ to_string() [6/10]

std::string clanguml::config::to_string ( filter_mode_t fm )

Definition at line 189 of file config.cc.

{
    switch (fm) {
    case filter_mode_t::basic:
        return "basic";
    case filter_mode_t::advanced:
        return "advanced";
    default:
        assert(false);
        return "";
    }
}

◆ to_string() [7/10]

std::string clanguml::config::to_string ( location_t cp )

Definition at line 132 of file config.cc.

{
    switch (cp) {
    case location_t::fileline:
        return "fileline";
    case location_t::function:
        return "function";
    case location_t::marker:
        return "marker";
    default:
        assert(false);
        return "";
    }
}

◆ to_string() [8/10]

std::string clanguml::config::to_string ( member_order_t mo )

Definition at line 162 of file config.cc.

{
    switch (mo) {
    case member_order_t::lexical:
        return "lexical";
    case member_order_t::as_is:
        return "as_is";
    default:
        assert(false);
        return "";
    }
}

◆ to_string() [9/10]

std::string clanguml::config::to_string ( method_type mt )

Definition at line 65 of file config.cc.

{
    switch (mt) {
    case method_type::constructor:
        return "constructor";
    case method_type::destructor:
        return "destructor";
    case method_type::assignment:
        return "assignment";
    case method_type::operator_:
        return "operator";
    case method_type::defaulted:
        return "defaulted";
    case method_type::deleted:
        return "deleted";
    case method_type::static_:
        return "static";
    }
 
    assert(false);
    return "";
}

◆ to_string() [10/10]

std::string clanguml::config::to_string ( package_type_t pt )

Definition at line 147 of file config.cc.

{
    switch (pt) {
    case package_type_t::kNamespace:
        return "namespace";
    case package_type_t::kDirectory:
        return "directory";
    case package_type_t::kModule:
        return "module";
    default:
        assert(false);
        return "";
    }
}

Variable Documentation

◆ schema_str

const std::string clanguml::config::schema_str

Definition at line 24 of file schema.h.

Detailed Description

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ config_ptr

◆ layout_hints

◆ relationship_hints_t

◆ type_aliases_longer_first_t

◆ type_aliases_t

Enumeration Type Documentation

◆ callee_type

◆ comment_parser_t

◆ context_direction_t

◆ filter_mode_t

◆ hint_t

◆ location_t

◆ member_order_t

◆ method_arguments

◆ method_type

◆ option_inherit_mode

◆ package_type_t

Function Documentation

◆ append_value() [1/3]

◆ append_value() [2/3]

◆ append_value() [3/3]

◆ append_value< plantuml >()

◆ get_predefined_diagram_templates()

◆ load()

◆ operator<<() [1/5]

◆ operator<<() [2/5]

◆ operator<<() [3/5]

◆ operator<<() [4/5]

◆ operator<<() [5/5]

◆ to_string() [1/10]

◆ to_string() [2/10]

◆ to_string() [3/10]

◆ to_string() [4/10]

◆ to_string() [5/10]

◆ to_string() [6/10]

◆ to_string() [7/10]

◆ to_string() [8/10]

◆ to_string() [9/10]

◆ to_string() [10/10]

Variable Documentation

◆ schema_str