@ts-graphviz/ast

What is @ts-graphviz/ast?

@ts-graphviz/ast is an npm package that provides an Abstract Syntax Tree (AST) for Graphviz's DOT language. It allows you to parse, manipulate, and generate DOT files programmatically using TypeScript.

What are @ts-graphviz/ast's main functionalities?

Parsing DOT Files

This feature allows you to parse a DOT string into an AST. The code sample demonstrates how to parse a simple DOT string and output the resulting AST.

const { parse } = require('@ts-graphviz/ast');
const dot = 'digraph G { a -> b; }';
const ast = parse(dot);
console.log(JSON.stringify(ast, null, 2));

Generating DOT Files

This feature allows you to generate a DOT string from an AST. The code sample demonstrates how to create a simple AST and convert it back to a DOT string.

const { print } = require('@ts-graphviz/ast');
const ast = {
  type: 'Graph',
  id: 'G',
  body: [
    { type: 'EdgeStatement', edge_list: [{ id: 'a' }, { id: 'b' }] }
  ]
};
const dot = print(ast);
console.log(dot);

Manipulating AST

This feature allows you to manipulate the AST before converting it back to a DOT string. The code sample demonstrates how to add a new edge to the graph.

const { parse, print } = require('@ts-graphviz/ast');
let dot = 'digraph G { a -> b; }';
let ast = parse(dot);
ast.body.push({ type: 'EdgeStatement', edge_list: [{ id: 'b' }, { id: 'c' }] });
dot = print(ast);
console.log(dot);

Other packages similar to @ts-graphviz/ast

graphlib

Graphlib is a JavaScript library for creating and manipulating directed graphs. It provides a more general-purpose graph manipulation API compared to @ts-graphviz/ast, which is specifically focused on the DOT language.

viz.js

Viz.js is a library that allows you to render DOT files using Graphviz in the browser. While @ts-graphviz/ast focuses on parsing and generating DOT files, Viz.js is more about rendering them.

d3-graphviz

d3-graphviz is a library that integrates Graphviz with D3.js for rendering graphs in the browser. It provides higher-level visualization capabilities compared to the AST manipulation provided by @ts-graphviz/ast.

README

@ts-graphviz/ast

This package contains the module for processing the DOT language at the Abstract Syntax Tree (AST) level for the ts-graphviz library.

🔗

It is part of the ts-graphviz library, which is split into modular packages to improve maintainability, flexibility, and ease of use.

Overview

This package is a foundational component of the ts-graphviz library that enables low-level manipulation of DOT language structures. It provides a parser that converts DOT language strings into AST nodes and a stringifier that converts AST nodes back to DOT language.

Main Functions

The AST package provides several key functions:

• parse(input: string, options?): Parses a DOT language string into an AST structure
• stringify(ast: ASTNode): Converts an AST structure to a DOT language string
• fromModel(model): Converts a Graph Model to an AST structure
• toModel(ast): Converts an AST structure to a Graph Model

Usage Examples

Parsing DOT Language

import { parse } from "@ts-graphviz/ast";

const dotString = "digraph G { A -> B; }";
const ast = parse(dotString);
console.log(ast);
// Output: A DotASTNode representing the DOT structure

Generating DOT Language

import { parse, stringify } from "@ts-graphviz/ast";

const dotString = "digraph G { A -> B; }";
const ast = parse(dotString);
// Modify the AST if needed
const outputDotString = stringify(ast);
console.log(outputDotString);
// Output: "digraph G { A -> B; }"

Error Handling

The package provides a specialized error class for handling syntax errors during parsing.

When a parsing error occurs, the parser throws a DotSyntaxError with detailed information about the issue, which helps in debugging DOT language syntax problems.

Contributors 👥

Thanks goes to these wonderful people (emoji key):

Yuki Yamazaki 💻 ⚠️ 📖 🤔	LaySent 🐛 ⚠️	elasticdotventures 📖	Christian Murphy 💻 🤔 📖	Artem 🐛	fredericohpandolfo 🐛	diegoquinteiro 🐛
robross0606 🤔	Blake Regalia 🐛	bigbug 💬	mrwk 💬	svdvonde 💬	Adam 💬	Trevor Scheer ️️️️♿️
Prem Pillai 🐛	nagasawaryoya 💻 ⚠️	YukiSasaki 💻 ⚠️	Madd0g 🐛	j4k0xb 🐛	HKrogstie 🐛	Nils K 🐛
hao2013 🚧 👀	Walter Rafelsberger 💬	grsjst 🐛	Steve 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog 📜

See CHANGELOG.md for more details.

License ⚖️

This software is released under the MIT License, see LICENSE.