3.2.11.5. dg/Printer.hpp

3.2.11.5.1. Class dg::PrintData

class dg::PrintData

This class is used to hold extra data about how a specific derivation graph is visualised.

The idea is that in the visualized network each vertex/hyperedge is specified by a pair \((id, dup)\) where \(id\) is the ID of the vertex/hyperedge and \(dup\) is an versioning integer that can be specified in objects of this class.

Initially, each vertex/hyperedge has only one version: duplicate number 0. The duplication is primarily specified via the hyperedges, with the duplication of vertices being induced afterwards. Thus hyperedge duplicates are managed by makeDuplicate() and removeDuplicate(), while the vertex duplicates are managed implicitly by reconnectSource() and reconnectTarget(). In the end, when the data is used for printing, it will be compiled to form the actual duplication data.

3.2.11.5.1.1. Synopsis

explicit PrintData(std::shared_ptr<DG> dg)
std::shared_ptr<DG> getDG() const
void makeDuplicate(DG::HyperEdge e, int eDup)
void removeDuplicate(DG::HyperEdge e, int eDup)
void reconnectSource(DG::HyperEdge e, int eDup, DG::Vertex v, int vDupTar)
void reconnectTarget(DG::HyperEdge e, int eDup, DG::Vertex v, int vDupTar)

3.2.11.5.1.2. Details

explicit PrintData(std::shared_ptr<DG> dg)

Construct a data object where all derivations have a single version, duplicate number 0, connected to version 0 of all heads and tails.

Throws:

LogicError if !dg->isLocked().

std::shared_ptr<DG> getDG() const
Returns:

the derivation graph the object holds data for.

void makeDuplicate(DG::HyperEdge e, int eDup)

Create another version of the given hyperedge and give it the given duplicate number. It will connect to duplicate 0 of all head and tail vertices.

Throws:

LogicError if !e.

Throws:

LogicError if e.getDG() != getDG().

Throws:

LogicError if duplicate eDup already exists for e.

void removeDuplicate(DG::HyperEdge e, int eDup)

Remove the version of the given hyperedge with the given duplicate number.

Throws:

LogicError if !e.

Throws:

LogicError if e.getDG() != getDG().

Throws:

LogicError if duplicate eDup does not exist for e.

void reconnectSource(DG::HyperEdge e, int eDup, DG::Vertex v, int vDupTar)

For the given hyperedge duplicate, reconnect the given source vertex to the given duplicate of that source. If the vertex is a source multiple times, then an arbitrary one of them is reconnected.

Throws:

LogicError if !e.

Throws:

LogicError if e.getDG() != getDG().

Throws:

LogicError if !v.

Throws:

LogicError if v.getDG() != getDG().

Throws:

LogicError if v is not a source vertex of e.

Throws:

LogicError if duplicate eDup does not exist for e.

void reconnectTarget(DG::HyperEdge e, int eDup, DG::Vertex v, int vDupTar)

For the given hyperedge duplicate, reconnect the given head to the given duplicate of that head. If the vertex is a head multiple times, then an arbitrary one of them is reconnected.

Throws:

LogicError if !e.

Throws:

LogicError if e.getDG() != getDG().

Throws:

LogicError if !v.

Throws:

LogicError if v.getDG() != getDG().

Throws:

LogicError if v is not a target vertex of e.

Throws:

LogicError if duplicate eDup does not exist for e.

3.2.11.5.2. Class dg::Printer

class dg::Printer

This class is used to configure how derivation graphs are visualised, how much is visualised and which extra properties are printed.

3.2.11.5.2.1. Synopsis

graph::Printer &getGraphPrinter()
const graph::Printer &getGraphPrinter() const
void setWithShortcutEdges(bool value)
bool getWithShortcutEdges() const
void setWithGraphImages(bool value)
bool getWithGraphImages() const
void setLabelsAsLatexMath(bool value)
bool getLabelsAsLatexMath() const
void pushVertexVisible(std::function<bool(DG::Vertex)> f)
void popVertexVisible()
void pushEdgeVisible(std::function<bool(DG::HyperEdge)> f)
void popEdgeVisible()
void setWithShortcutEdgesAfterVisibility(bool value)
bool getWithShortcutEdgesAfterVisibility() const
void setVertexLabelSep(std::string sep)
const std::string &getVertexLabelSep()
void setEdgeLabelSep(std::string sep)
const std::string &getEdgeLabelSep()
void pushVertexLabel(std::function<std::string(DG::Vertex)> f)
void popVertexLabel()
void pushEdgeLabel(std::function<std::string(DG::HyperEdge)> f)
void popEdgeLabel()
void setWithGraphName(bool value)
bool getWithGraphName() const
void setWithRuleName(bool value)
bool getWithRuleName() const
void setWithRuleId(bool value)
bool getWithRuleId() const
void setWithInlineGraphs(bool value)
bool getWithInlineGraphs() const
void pushVertexColour(std::function<std::string(DG::Vertex)> f, bool extendToEdges)
void popVertexColour()
void pushEdgeColour(std::function<std::string(DG::HyperEdge)> f)
void popEdgeColour()
void setRotationOverwrite(std::function<int(std::shared_ptr<graph::Graph>)> f)
void setMirrorOverwrite(std::function<bool(std::shared_ptr<graph::Graph>)> f)
void setImageOverwrite(std::function<std::pair<std::string, std::string>(DG::Vertex v, int dupNum)> f)
void setGraphvizPrefix(const std::string &prefix)
const std::string &getGraphvizPrefix() const
void setTikzpictureOption(const std::string &option)
const std::string &getTikzpictureOption() const

3.2.11.5.2.2. Details

graph::Printer &getGraphPrinter()
const graph::Printer &getGraphPrinter() const
Returns:

a reference to the graph::Printer used for graphs in vertices of the DG.

void setWithShortcutEdges(bool value)
bool getWithShortcutEdges() const

Control whether hyperedges \((T, H)\) with \(|T| = |H| = 1\) are printed as a simple arrow without the usual rectangle.

void setWithGraphImages(bool value)
bool getWithGraphImages() const

Control whether each vertex is printed with an image of its graph in it.

void setLabelsAsLatexMath(bool value)
bool getLabelsAsLatexMath() const

Control whether labels on vertices and hyperedges are put inline \(\LaTeX\) math. Specifically, a label label is written as $\mathrm{label'}$, with label' being label with all space characters escaped.

void pushVertexVisible(std::function<bool(DG::Vertex)> f)

Add another function controlling the visibility of vertices. All visibility functions must return true for a vertex to be visible.

Throws:

LogicError if !f.

void popVertexVisible()

Remove the last pushed vertex visibility function.

Throws:

LogicError if no callback is left to pop.

void pushEdgeVisible(std::function<bool(DG::HyperEdge)> f)

Add another function controlling the visibility of hyperedges. All visibility functions must return true for a hyperedge to be visible.

Throws:

LogicError if !f.

void popEdgeVisible()

Remove the last pushed hyperedge visibility function.

Throws:

LogicError if no callback is left to pop.

void setWithShortcutEdgesAfterVisibility(bool value)
bool getWithShortcutEdgesAfterVisibility() const

Control whether hyperedges are depicted as simple arrows when all but 1 head and tail are hidden.

void setVertexLabelSep(std::string sep)
const std::string &getVertexLabelSep()

Set/get the string used as separator between each part of each vertex label.

void setEdgeLabelSep(std::string sep)
const std::string &getEdgeLabelSep()

Set/get the string used as separator between each part of each edge label.

void pushVertexLabel(std::function<std::string(DG::Vertex)> f)

Add another function for vertex labelling. The result of this function is appended to each label.

Throws:

LogicError if !f.

void popVertexLabel()

Remove the last pushed vertex labelling function.

Throws:

LogicError if no callback is left to pop.

void pushEdgeLabel(std::function<std::string(DG::HyperEdge)> f)

Add another function for edge labelling. The result of this function is appended to each label.

Throws:

LogicError if !f.

void popEdgeLabel()

Remove the last pushed edge labelling function.

Throws:

LogicError if no callback is left to pop.

void setWithGraphName(bool value)
bool getWithGraphName() const

Control whether graph names are appended to the vertex labels (see also pushVertexLabel()).

void setWithRuleName(bool value)
bool getWithRuleName() const

Control whether rules names are appended to the edge labels (see also pushEdgeLabel()).

void setWithRuleId(bool value)
bool getWithRuleId() const

Control whether rules IDs are appended to the edge labels (see also pushEdgeLabel()).

void setWithInlineGraphs(bool value)
bool getWithInlineGraphs() const

Control whether graph depictions should be precompiled, or be included inline in the DG figure.

void pushVertexColour(std::function<std::string(DG::Vertex)> f, bool extendToEdges)

Add another function for colouring vertices. The final colour of a vertex is the result of the first colour function returning a non-empty string. The functions are evaluated in the order they are pushed and the resulting string is used directly as a colour in Tikz. A hyperedge is also coloured if at least one head and one tail can be coloured with a colour for which extendToEdges is true. In this case, the hyperedge (and a subset of the head and tail connectors) is coloured with the first applicable colour. The edge extension of vertex colour takes lower precedence than explicitly added hyperedge colouring functions.

Throws:

LogicError if !f.

void popVertexColour()

Remove the last pushed vertex colouring function.

Throws:

LogicError if no callback is left to pop.

void pushEdgeColour(std::function<std::string(DG::HyperEdge)> f)

Add another function for colouring hyperedges. The final colour of a hyperedge (and all of its head and tail connectors) is the result of the first colour function returning a non-empty string.

Throws:

LogicError if !f.

void popEdgeColour()

Remove the last pushed hyperedge colouring function.

Throws:

LogicError if no callback is left to pop.

void setRotationOverwrite(std::function<int(std::shared_ptr<graph::Graph>)> f)

Overwrite the rotation set in the nested graph::Printer. The given function will be used to set the rotation of each printed graph.

Throws:

LogicError if !f.

void setMirrorOverwrite(std::function<bool(std::shared_ptr<graph::Graph>)> f)

Overwrite the mirror set in the nested graph::Printer. The given function will be used to set the mirror of each printed graph.

Throws:

LogicError if !f.

void setImageOverwrite(std::function<std::pair<std::string, std::string>(DG::Vertex v, int dupNum)> f)

Overwrite the image generation for graphs depicted in the vertices of the printed derivation graph. For each duplicate of each vertex to be depicted, the given callback is called. It must then return two strings:

  1. Either

  • an empty string if the standard depiction should be used, in which case the second string is ignored, or

  • the filename of the PDF that should be included in the final compiled figure.

  1. Either

  • an empty string if no additional post-processing command is needed, or

  • a string of Bash code which will be inserted in the post-processing instructions. For example, one can write out source code in the callback, and then return a command that compiles that code into the PDF needed by inclusion.

The image overwrite can be removed by calling with nullptr.

void setGraphvizPrefix(const std::string &prefix)
const std::string &getGraphvizPrefix() const

Access the string that will be inserted into generated DOT files, just after the graph declaration.

void setTikzpictureOption(const std::string &option)
const std::string &getTikzpictureOption() const

Access the string that will be inserted into generated Tikz files, in the options for the \tikzpicture macro used for the DG.