Responsible: |
The KGraph Text (KGT) project provides a textual syntax and editor for specifying KGraphs. While editing the KGraph in the textual editor, we provide a visualization of the graph in a KLighD view. This project was started with two use cases in mind:
This page documents the basic syntax of the KGT format and how to use the editor together with the KLighD view.
Content
To quickly get you up to speed on how to write basic KGT files, we have a full-blown tutorial available for you learning pleasure. Once you've completed that, the rest of this page will provide a more comprehensive description of the KGT syntax.
In this section, we will take a closer look at the KGT syntax. We will start with the basic syntax. We will then take a look at the different kinds of objects available in KGT and at specifying parameters and properties of these objects.
If you prefer reading Xtext grammars, you will find it over here. |
In KGT, the KGraph is specified by listing the nodes in the graph, their ports, edges, and labels. The specification of each type of object follows the same basic syntax:
type [id] <details> |
An ID is only necessary if an object needs to be referenced later. For example, if you define a port that you want to connect an edge to, the port better have an ID or you won't be able to specify which port the edge should connect to. The details
field doesn't always contain information. In fact, it is only necessary for the text of labels and for the source and target points of edges (see the next section for more details).
With this basic syntax, the following text specifies a complete KGraph with three nodes with the IDs n1
, n2
, and n3
:
knode n1 knode n2 knode n3 |
The KGraph itself is simply a list of objects. Some objects can be (and are sometimes expected to be) nested in other objects. For instance, a port must always belong to a node. To be able to add objects to other objects, we extend the basic syntax a little:
type [id] <details> { <declarations> } |
If nodes n2
and n3
should be nested inside n1
, the previous example must be changed a little:
knode n1 { knode n2 knode n3 } |
Now that we know the basic way of specifying objects, it's time to see what types of objects there are, which other objects they can appear in, and whether they require any details.
Type | Keyword | Details | To appear in | Remarks |
---|---|---|---|---|
Node | knode | Empty | Top level, nodes | |
Port | kport | Empty | Nodes | |
Label | klabel | String (label text):"My gigantically useful label text" | Nodes, ports, edges | |
Edge | kedge | Source and target:(:sourcePortId -> targetNodeId:targetPortId) | Nodes | Edges must always be defined in their source node. That is why the source node is not defined in the details. |
When specifying edges, each port ID and the colon preceding it is optional. After all, edges don't have to connect ports, but can also connect nodes directly.
So far, we have learned how the objects in a KGraph can be specified in the KGT format. However, this doesn't help us much since we don't know yet how to add basic parameters to the objects. This includes, for instance, the size of nodes.
Parameters are the first thing inside a block (the curly braces) of an object. There are three basic parameters that can be attached to a nodes, ports, and labels:
pos: x=<xPosition> y=<yPosition> size: width=<width> height=<height> insets: top=<top> bottom=<bottom> left=<left> right=<right> |
A node with a predefined size could be written like this:
knode n1 { size: width=100 height=50 } |
Edges are somewhat different. Position, size, and insets aren't meaningful to edges, so edges have a different parameter that defines their list of bend points:
points: <source>;<bend>*;<target> |
Each of the points is defined by their x and y coordinate as such:
<x>,<y> |
If you have already used a layout algorithm through KIML, you will know that layout algorithms are configured through properties attached to the different graph objects. In KGT, this is done through the properties
section that follows the parameters:
properties: <propertyId> = <propertyValue> |
The properties
section can of course contain an arbitrary number of lines, each specifying the value of one property. For example, if we want to add ports and a label to a node, we will often have to set certain properties on it as well to tell the layout algorithm what to do:
knode n1 { properties: de.cau.cs.kieler.sizeConstraint="PORTS NODE_LABELS" de.cau.cs.kieler.nodeLabelPlacement="INSIDE V_TOP H_CENTER" de.cau.cs.kieler.portConstraints=FIXED_SIDE klabel "Node 1" kport p1 { size: width=5 height=5 properties: de.cau.cs.kieler.portSide=WEST klabel "West port 1" } kport p2 { size: width=5 height=5 properties: de.cau.cs.kieler.portSide=WEST klabel "West port 2" } kport p3 { size: width=5 height=5 properties: de.cau.cs.kieler.portSide=EAST klabel "East port 1" } } |
Often enough, we also have to set properties on the graph itself (for instance, which layout algorithm to use). In that case, simply include a properties
section at the top of the file:
properties: de.cau.cs.kieler.algorithm="de.cau.cs.kieler.klay.tree" knode n1 { size: width=50 height=50 kedge (-> n2) kedge (-> n3) } knode n2 { size: width=50 height=50 } knode n3 { size: width=50 height=50 } |
We finish with a more complex example that highlights some of the features of the KIELER graph layout technology and how to use it through the KGT format.
|