aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
gum::dot::DotWriter Class Reference

Writes a graph in the dot language, statement after statement, in the order of the calls. More...

#include <agrum/base/core/dot/dotWriter.h>

Collaboration diagram for gum::dot::DotWriter:
[legend]

Public Member Functions

 DotWriter (bool directed=true, std::string_view name="")
 Starts a graph.
std::string str () const
 The graph written so far, closed. It can be called at any moment, and the writer can be used after.
Statements
void graphAttributes (const DotAttributes &attributes)
 graph [attributes];, the attributes of the graph (does nothing if there is none).
void nodeDefaults (const DotAttributes &attributes)
 node [attributes];, the default attributes of the nodes that follow (none : does nothing).
void edgeDefaults (const DotAttributes &attributes)
 edge [attributes];, the default attributes of the edges that follow (none : does nothing).
void graphAttribute (const DotAttribute &attribute)
 key="value";, an attribute of the graph or of the subgraph being written.
void node (std::string_view id, const DotAttributes &attributes={})
 a node, whose identifier is id (quoted).
void node (Size id, const DotAttributes &attributes={})
 a node designated by a number, written without quotes (graphviz reads it as an identifier).
void edge (std::string_view from, std::string_view to, const DotAttributes &attributes={})
 an edge from from to to (-> in a directed graph, -- in an undirected one).
void edge (Size from, Size to, const DotAttributes &attributes={})
 an edge between two nodes designated by numbers, written without quotes.
void beginSubgraph (std::string_view name, const DotAttributes &attributes={})
 Opens a subgraph : subgraph "name" { key="value"; ... .
void endSubgraph ()
 Closes the last subgraph that is open.

Static Public Member Functions

Formatting
static std::string quote (std::string_view text)
 text between double quotes, in which ", \, line feed and carriage return are escaped.
static std::string number (double value)
 The shortest text that reads back as value (0.5, 1, 1e-05).

Private Member Functions

std::string _indent_ () const
void _defaults_ (const char *keyword, const DotAttributes &attributes)
void _node_ (const std::string &id, const DotAttributes &attributes)
void _edge_ (const std::string &from, const std::string &to, const DotAttributes &attributes)

Static Private Member Functions

static std::string _attributes_ (const DotAttributes &attributes)
static std::string _attribute_ (const DotAttribute &attribute)

Private Attributes

std::string _buffer_
bool _directed_
int _depth_ {0}

Detailed Description

Writes a graph in the dot language, statement after statement, in the order of the calls.

The names of the nodes, the labels and the values of the attributes are quoted and escaped, so that any text gives a well formed graph. The keys of the attributes are checked (letters, digits and underscores, not starting with a digit).

gum::dot::DotWriter w(true, "bn");
w.graphAttributes({{"bgcolor", "transparent"}, {"size", "5"}});
w.node("A", {{"fillcolor", "#404040"}, {"tooltip", "(0) A"}});
w.edge("A", "B", {{"penwidth", gum::dot::DotWriter::number(1.5)}});
std::string dot = w.str();
Writes a graph in the dot language, statement after statement, in the order of the calls.
Definition dotWriter.h:100
static std::string number(double value)
The shortest text that reads back as value (0.5, 1, 1e-05).
Definition dotWriter.cpp:93

Errors :

Definition at line 100 of file dotWriter.h.

Constructor & Destructor Documentation

◆ DotWriter()

gum::dot::DotWriter::DotWriter ( bool directed = true,
std::string_view name = "" )
explicit

Starts a graph.

Parameters
directedtrue for a digraph (edges ->), false for a graph (edges --).
namethe name of the graph, written quoted ; none if empty.

Definition at line 67 of file dotWriter.cpp.

67 : _directed_(directed) {
68 _buffer_ = directed ? "digraph" : "graph";
69 if (!name.empty()) {
70 _buffer_ += ' ';
71 _buffer_ += quote(name);
72 }
73 _buffer_ += " {\n";
74 }
std::string _buffer_
Definition dotWriter.h:163
static std::string quote(std::string_view text)
text between double quotes, in which ", \, line feed and carriage return are escaped.
Definition dotWriter.cpp:76

References _buffer_, and _directed_.

Member Function Documentation

◆ _attribute_()

std::string gum::dot::DotWriter::_attribute_ ( const DotAttribute & attribute)
staticprivate

Definition at line 101 of file dotWriter.cpp.

101 {
102 if (!_isIdentifier_(attribute.key)) {
103 GUM_ERROR(InvalidArgument, "'" << attribute.key << "' is not a valid key of dot attribute.")
104 }
105 return attribute.key + '=' + (attribute.verbatim ? attribute.value : quote(attribute.value));
106 }
#define GUM_ERROR(type, msg)
Definition exceptions.h:76

References GUM_ERROR, gum::dot::DotAttribute::key, quote(), gum::dot::DotAttribute::value, and gum::dot::DotAttribute::verbatim.

Referenced by _attributes_(), beginSubgraph(), and graphAttribute().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _attributes_()

std::string gum::dot::DotWriter::_attributes_ ( const DotAttributes & attributes)
staticprivate

Definition at line 108 of file dotWriter.cpp.

108 {
109 std::string result = "[";
110 for (std::size_t i = 0; i < attributes.size(); ++i) {
111 if (i > 0) result += ", ";
112 result += _attribute_(attributes[i]);
113 }
114 return result + ']';
115 }
static std::string _attribute_(const DotAttribute &attribute)

References _attribute_().

Referenced by _defaults_(), _edge_(), and _node_().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _defaults_()

void gum::dot::DotWriter::_defaults_ ( const char * keyword,
const DotAttributes & attributes )
private

Definition at line 117 of file dotWriter.cpp.

117 {
118 if (attributes.empty()) return;
119 _buffer_ += _indent_() + keyword + ' ' + _attributes_(attributes) + ";\n";
120 }
static std::string _attributes_(const DotAttributes &attributes)
std::string _indent_() const
Definition dotWriter.cpp:99

References _attributes_(), _buffer_, and _indent_().

Referenced by edgeDefaults(), graphAttributes(), and nodeDefaults().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _edge_()

void gum::dot::DotWriter::_edge_ ( const std::string & from,
const std::string & to,
const DotAttributes & attributes )
private

Definition at line 140 of file dotWriter.cpp.

142 {
143 std::string statement = _indent_() + from + (_directed_ ? " -> " : " -- ") + to;
144 if (!attributes.empty()) statement += ' ' + _attributes_(attributes);
145 _buffer_ += statement + ";\n";
146 }

References _attributes_(), _buffer_, _directed_, and _indent_().

Referenced by edge(), and edge().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _indent_()

std::string gum::dot::DotWriter::_indent_ ( ) const
private

Definition at line 99 of file dotWriter.cpp.

99{ return std::string(2 * (_depth_ + 1), ' '); }

References _depth_.

Referenced by _defaults_(), _edge_(), _node_(), beginSubgraph(), endSubgraph(), and graphAttribute().

Here is the caller graph for this function:

◆ _node_()

void gum::dot::DotWriter::_node_ ( const std::string & id,
const DotAttributes & attributes )
private

Definition at line 134 of file dotWriter.cpp.

134 {
135 std::string statement = _indent_() + id;
136 if (!attributes.empty()) statement += ' ' + _attributes_(attributes);
137 _buffer_ += statement + ";\n";
138 }

References _attributes_(), _buffer_, and _indent_().

Referenced by node(), and node().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ beginSubgraph()

void gum::dot::DotWriter::beginSubgraph ( std::string_view name,
const DotAttributes & attributes = {} )

Opens a subgraph : subgraph "name" { key="value"; ... .

Its statements are the ones written until endSubgraph(). Graphviz draws it as a cluster if the name starts with cluster.

Parameters
namethe name of the subgraph (quoted), anonymous if empty.
attributesthe attributes of the subgraph.

Definition at line 165 of file dotWriter.cpp.

165 {
166 // nothing is written if an attribute is refused
167 std::string statement = _indent_() + "subgraph ";
168 if (!name.empty()) statement += quote(name) + ' ';
169 statement += "{\n";
170 const std::string inner(2 * (_depth_ + 2), ' ');
171 for (const auto& attribute: attributes)
172 statement += inner + _attribute_(attribute) + ";\n";
173 _buffer_ += statement;
174 ++_depth_;
175 }

References _attribute_(), _buffer_, _depth_, _indent_(), and quote().

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), and gum::PDAG::toDot().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ edge() [1/2]

void gum::dot::DotWriter::edge ( Size from,
Size to,
const DotAttributes & attributes = {} )

an edge between two nodes designated by numbers, written without quotes.

Definition at line 161 of file dotWriter.cpp.

161 {
162 _edge_(std::to_string(from), std::to_string(to), attributes);
163 }
void _edge_(const std::string &from, const std::string &to, const DotAttributes &attributes)

References _edge_().

Here is the call graph for this function:

◆ edge() [2/2]

void gum::dot::DotWriter::edge ( std::string_view from,
std::string_view to,
const DotAttributes & attributes = {} )

an edge from from to to (-> in a directed graph, -- in an undirected one).

Definition at line 157 of file dotWriter.cpp.

157 {
158 _edge_(quote(from), quote(to), attributes);
159 }

References _edge_(), and quote().

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), gum::CausalModel< GUM_SCALAR >::_toDot_(), gum::BayesNetFragment< GUM_SCALAR >::toDot(), gum::credal::CredalNet< GUM_SCALAR >::toDot(), gum::DiGraph::toDot(), gum::EssentialGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDot(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), gum::MarkovBlanket::toDot(), gum::MixedGraph::toDot(), gum::PAG::toDot(), gum::PDAG::toDot(), gum::UndiGraph::toDot(), and gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ edgeDefaults()

void gum::dot::DotWriter::edgeDefaults ( const DotAttributes & attributes)

edge [attributes];, the default attributes of the edges that follow (none : does nothing).

Definition at line 128 of file dotWriter.cpp.

128{ _defaults_("edge", attributes); }
void _defaults_(const char *keyword, const DotAttributes &attributes)

References _defaults_().

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph(), and gum::dot::writePreamble().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ endSubgraph()

void gum::dot::DotWriter::endSubgraph ( )

Closes the last subgraph that is open.

Definition at line 177 of file dotWriter.cpp.

177 {
178 if (_depth_ == 0) { GUM_ERROR(OperationNotAllowed, "No subgraph to close.") }
179 --_depth_;
180 _buffer_ += _indent_() + "}\n";
181 }

References _buffer_, _depth_, _indent_(), and GUM_ERROR.

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), and gum::PDAG::toDot().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ graphAttribute()

void gum::dot::DotWriter::graphAttribute ( const DotAttribute & attribute)

key="value";, an attribute of the graph or of the subgraph being written.

Definition at line 130 of file dotWriter.cpp.

130 {
131 _buffer_ += _indent_() + _attribute_(attribute) + ";\n";
132 }

References _attribute_(), _buffer_, and _indent_().

Here is the call graph for this function:

◆ graphAttributes()

void gum::dot::DotWriter::graphAttributes ( const DotAttributes & attributes)

graph [attributes];, the attributes of the graph (does nothing if there is none).

Definition at line 122 of file dotWriter.cpp.

122 {
123 _defaults_("graph", attributes);
124 }

References _defaults_().

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), and gum::dot::writePreamble().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ node() [1/2]

void gum::dot::DotWriter::node ( Size id,
const DotAttributes & attributes = {} )

a node designated by a number, written without quotes (graphviz reads it as an identifier).

Definition at line 152 of file dotWriter.cpp.

152 {
153 _node_(std::to_string(id), attributes);
154 }
void _node_(const std::string &id, const DotAttributes &attributes)

References _node_().

Here is the call graph for this function:

◆ node() [2/2]

void gum::dot::DotWriter::node ( std::string_view id,
const DotAttributes & attributes = {} )

a node, whose identifier is id (quoted).

Definition at line 148 of file dotWriter.cpp.

148 {
149 _node_(quote(id), attributes);
150 }

References _node_(), and quote().

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), gum::CausalModel< GUM_SCALAR >::_toDot_(), gum::BayesNetFragment< GUM_SCALAR >::toDot(), gum::credal::CredalNet< GUM_SCALAR >::toDot(), gum::EssentialGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDot(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), gum::MarkovBlanket::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph(), and gum::NodeGraphPart::writeDotNode().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ nodeDefaults()

void gum::dot::DotWriter::nodeDefaults ( const DotAttributes & attributes)

node [attributes];, the default attributes of the nodes that follow (none : does nothing).

Definition at line 126 of file dotWriter.cpp.

126{ _defaults_("node", attributes); }

References _defaults_().

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), and gum::dot::writePreamble().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ number()

std::string gum::dot::DotWriter::number ( double value)
static

The shortest text that reads back as value (0.5, 1, 1e-05).

Definition at line 93 of file dotWriter.cpp.

93 {
94 char buffer[40];
95 const auto [end, error] = std::to_chars(buffer, buffer + sizeof(buffer), value);
96 return std::string(buffer, error == std::errc() ? end : buffer);
97 }

Referenced by gum::dot::arcAttributes(), and gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph().

Here is the caller graph for this function:

◆ quote()

std::string gum::dot::DotWriter::quote ( std::string_view text)
static

text between double quotes, in which ", \, line feed and carriage return are escaped.

Definition at line 76 of file dotWriter.cpp.

76 {
77 std::string result;
78 result.reserve(text.size() + 2);
79 result += '"';
80 for (const char c: text) {
81 switch (c) {
82 case '"' : result += "\\\""; break;
83 case '\\' : result += "\\\\"; break;
84 case '\n' : result += "\\n"; break;
85 case '\r' : result += "\\r"; break;
86 default : result += c;
87 }
88 }
89 result += '"';
90 return result;
91 }

Referenced by _attribute_(), beginSubgraph(), edge(), and node().

Here is the caller graph for this function:

◆ str()

std::string gum::dot::DotWriter::str ( ) const

The graph written so far, closed. It can be called at any moment, and the writer can be used after.

Definition at line 183 of file dotWriter.cpp.

183 {
184 if (_depth_ != 0) {
185 GUM_ERROR(OperationNotAllowed, "The graph is not complete : a subgraph is still open.")
186 }
187 return _buffer_ + "}\n";
188 }

References _buffer_, _depth_, and GUM_ERROR.

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), gum::CausalModel< GUM_SCALAR >::_toDot_(), gum::BayesNetFragment< GUM_SCALAR >::toDot(), gum::credal::CredalNet< GUM_SCALAR >::toDot(), gum::DiGraph::toDot(), gum::EssentialGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDot(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), gum::MarkovBlanket::toDot(), gum::MixedGraph::toDot(), gum::PDAG::toDot(), gum::UndiGraph::toDot(), and gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph().

Here is the caller graph for this function:

Member Data Documentation

◆ _buffer_

std::string gum::dot::DotWriter::_buffer_
private

◆ _depth_

int gum::dot::DotWriter::_depth_ {0}
private

Definition at line 165 of file dotWriter.h.

Referenced by _indent_(), beginSubgraph(), endSubgraph(), and str().

◆ _directed_

bool gum::dot::DotWriter::_directed_
private

Definition at line 164 of file dotWriter.h.

Referenced by DotWriter(), and _edge_().


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