Home

Graphlib-dot is a DOT language parser and writer for graphlib.

Table of Contents

• Installing
  • npm Install
  • Bower Install
  • Browser Scripts
  • Source Build
• Example
• API Reference
  • graphlibDot.read
  • graphlibDot.readMany
  • graphlibDot.write
  • graphlibDot.graphlib
• Limitations
• Bug Tracking
• Contributing
• License

Installing

npm Install

Before installing this library you need to install the npm package manager.

To get graphlib-dot from npm, use:

$ npm install @dagrejs/graphlib-dot

Browser Scripts

You can get the latest browser-ready scripts:

• graphlib-dot.js
• graphlib-dot.min.js

You can also get the scripts for a particular version. For example, to get v0.6.3:

• graphlib-dot.js
• graphlib-dot.min.js

Look at the releases page to find a list of versions.

Source Build

Before building this library you need to install the npm package manager.

Check out this project and run this command from the root of the project:

$ make dist

This will generate graphlib-dot.js and graphlib-dot.min.js in the dist directory of the project.

Example

var fs = require('fs')
var dot = require('graphlib-dot')

var graph = dot.read(fs.readFileSync('your-dot-file.dot', 'UTF-8'));
// You can pass `graph` to dagre or some other graphlib compatible
// graph library.

// You can also write a graph to a graphviz string.
console.log(dot.write(graph))

API

# graphlibDot.read(str)

Reads a single DOT graph from the str and returns it a Graph representation. By default the Graph will be a compound multigraph. Using the strict keyword changes the Graph to a compound graph without multi-edges. Use the digraph keyword to create a directed graph and the graph keyword to create an undirected graph.

var dot = require("graphlib-dot");

var digraph = dot.read("digraph { 1; 2; 1 -> 2 [label=\"label\"] }");
digraph.nodes();
// => [ "1", "2" ]

digraph.edges();
// => [ { v: "1", w: "2" } ]

digraph.edge("1", "2");
// => { label: "label" }

This function treats subgraphs in the input as nodes in the final DOT graph, which will have one or more children. Empty subgraphs in the input are not included in the final graph.

var dot = require("graphlib-dot");

var digraph = dot.read("digraph { 1; 2; subgraph X { 3; 4 }; subgraph Y {} }");
digraph.nodes();
// => [ "1", "2", "3", "4", "X" ]
// Note in particular that "Y" was not included because it was empty

digraph.children();
// => [ "1", "2", "X" ]
// Note that calling children without any arguments returns children without
// a parent.

digraph.children("X");
// => [ "3", "4" ]

Defaults in the input graph are applied to objects (node, edge, graph) as described by the rules of the DOT language. However, the default information itself is not preserved during the parsing process. Graphviz's DOT also loses default information under most circumstances; however we've opted to make it consistently always the case.

# graphlibDot.readMany(str)

Parses one or more DOT graphs from str in a manner similar to that used by parse for individual graphs.

var dot = require("graphlib-dot");

var digraphs = dot.readMany("digraph { 1; 2; 1 -> 2 [label=\"label\"] }\n" +
                            "digraph { A; B; }");
digraphs.length;
// => 2

# graphlibDot.write(graph)

Writes a String representation of the given graph in the DOT language.

var Graph = require("graphlib").Graph,
    dot = require("graphlib-dot");

var digraph = new Graph();
digraph.setNode(1);
digraph.setNode(2);
digraph.setEdge(1, 2, { label: "A label" });
console.log(dot.write(digraph));
// Prints:
//
//  strict digraph {
//      "1"
//      "2"
//      1 -> 2 [label="A label"]
//  }

Note that the graph was "strict" because we did not construct it with the multigraph property. To get a non-strict graph:

var Graph = require("graphlib").Graph,
    dot = require("graphlib-dot");

var digraph = new Graph({ multigraph: true });
digraph.setNode(1);
digraph.setNode(2);
digraph.setEdge(1, 2, { label: "A label" });
console.log(dot.write(digraph));
// Prints:
//
//  digraph {
//      "1"
//      "2"
//      1 -> 2 [label="A label"]
//  }

# graphlibDot.graphlib

When used as a browser bundle graphlib-dot exports the version of graphlib it uses. The graphlib API is documented on the graphlib wiki.

Limitations

• The parser does not work for HTML strings.
• The parser ignores port and compass statements when handling node statements. For example, a node a:port:nw [attr1=val] will be treated as though it were defined a [attr1=val].
• Defaults are expanded during parsing and are otherwise not preserved. This is similar to the behavior exhibited by dot.

License

Graphlib-dot is licensed under the terms of the MIT License. See LICENSE for details.