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
Copy

Parser Options

The parse function accepts an optional second argument for configuration:

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

// Parse with custom HTML nesting depth limit
const ast = parse(dotString, {
  startRule: 'Dot',  // Specify the starting rule (default: 'Dot')
  maxHtmlNestingDepth: 200  // Set maximum HTML nesting depth (default: 100)
});
Copy

Security Note:

• The maxHtmlNestingDepth option limits the depth of nested HTML-like structures in DOT files to prevent stack overflow attacks
• The default limit of 100 is sufficient for normal use cases (typically <10 levels)
• HTML-like labels are GraphViz DOT syntax, not browser HTML
• For processing untrusted DOT files, see the validation guide in @ts-graphviz/adapter documentation

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; }"
Copy

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.