ts-graphviz 1.1.0 → 1.2.1

package/README.ja.md

@@ -101,6 +101,8 @@ const dot = toDot(G);
 <details>
 <summary>高度な使い方</summary>
 
+##### カスタム・クラス 🤖
+
 クラスを継承することで独自の実装を加えることもできます。
 
 ```typescript
@@ -114,9 +116,9 @@ class MyCustomDigraph extends Digraph {
   }
 }
 class MyCustomNode extends Node {
-  constructor(id: number) {
-    super(`node${id}`, {
-      [_.label]: `This is Custom Node ${id}`
+  constructor(id: string) {
+    super(`node_${id}`, {
+      [_.label]: `This is Custom Node ${id}`,
     });
   }
 }
@@ -124,33 +126,92 @@ class MyCustomNode extends Node {
 class MyCustomEdge extends Edge {
   constructor(targets: EdgeTargetTuple) {
     super(targets, {
-      [_.label]: 'This is Custom Edge'
+      [_.label]: 'This is Custom Edge',
     });
   }
 }
 
 const digraph = new MyCustomDigraph();
-const node1 = new MyCustomNode(1);
-const node2 = new MyCustomNode(2);
+const node1 = new MyCustomNode('A');
+const node2 = new MyCustomNode('B');
 const edge = new MyCustomEdge([node1, node2]);
 digraph.addNode(node1);
 digraph.addNode(node2);
 digraph.addEdge(edge);
-const dot = toDot(g);
+const dot = toDot(digraph);
 // digraph "G" {
 //   label = "This is Custom Digraph";
-//   "node1" [
-//     label = "This is Custom Node 1",
+//   "node_A" [
+//     label = "This is Custom Node A";
 //   ];
-//   "node2" [
-//     label = "This is Custom Node 2",
+//   "node_B" [
+//     label = "This is Custom Node B";
 //   ];
-//   "node1" -> "node2" [
-//     label = "This is Custom Edge",
+//   "node_A" -> "node_B" [
+//     label = "This is Custom Edge";
 //   ];
 // }
 ```
 
+##### Models Context API ( `with` メソッド) 🧅
+
+あなたは _Models Context API_ をつかうことで、Graphの内部で生成されるオブジェクトもカスタムクラスにすることができます。
+
+
+`GraphBaseModel` の実装である `Digraph`, `Graph`, `Subgraph` が持つ `with` メソッドは、 カスタムモデルを事前定義するために提供されています。
+
+```typescript
+const g = new Digraph();
+g.with({
+  Node: MyCustomNode,
+  Edge: MyCustomEdge,
+});
+const a = g.createNode('A'); // MyCustomNode
+const b = g.createNode('B'); // MyCustomNode
+g.createEdge([a, b]); // MyCustomEdge
+const dot = toDot(g);
+// digraph {
+//   "node_A" [
+//     label = "This is Custom Node A";
+//   ];
+//   "node_B" [
+//     label = "This is Custom Node B";
+//   ];
+//   "node_A" -> "node_B" [
+//     label = "This is Custom Edge";
+//   ];
+// }
+```
+
+##### `fromDot` 関数 ⏪
+
+> この関数のステータスは ![beta](https://img.shields.io/badge/-beta-orange) です。
+
+このライブラリを使用するメインシナリオは `toDot` 関数を使用することにありますが、逆方向の変換もサポートしています。
+
+**DOT** を **Model** に変換により、コードの一部をDOT言語で記述することができます。
+
+
+```typescript
+const G = fromDot(
+  `digraph {
+    node_A [
+      label = "This is a Label of Node A";
+    ];
+  }`,
+);
+
+G.edge(['node_A', 'node_B']);
+
+const dot = toDot(G)
+// digraph {
+//   "node_A" [
+//     label = "This is a Label of Node A";
+//   ];
+//   "node_A" -> "node_B";
+// }
+```
+
 </details>
 
 
@@ -219,6 +280,48 @@ const dot = toDot(G);
 > // }
 > ```
 
+
+<details>
+<summary>高度な使い方</summary>
+
+##### Models Context API ( `withContext` 関数 ) 💈
+
+
+`withContext` 関数は、 _Model Factory_ 関数を返します。
+
+この _Model Factory_ は、 `Digraph` や `Graph` など、 `RootGraphModel` をカスタムクラスに置き換える手段を提供します。
+
+これのAPIにより、宣言的APIとカスタムクラスを統合する手段を提供します。
+
+```typescript
+const { digraph } = withContext({
+  Digraph: MyCustomDigraph,
+  Node: MyCustomNode,
+  Edge: MyCustomEdge,
+});
+
+const G = digraph((g) => {
+  const a = g.node('A'); // MyCustomNode
+  const b = g.node('B'); // MyCustomNode
+  g.edge([a, b]); // MyCustomEdge
+});
+const dot = toDot(g);
+// digraph "G" {
+//   label = "This is Custom Digraph";
+//   "node_A" [
+//     label = "This is Custom Node A";
+//   ];
+//   "node_B" [
+//     label = "This is Custom Node B";
+//   ];
+//   "node_A" -> "node_B" [
+//     label = "This is Custom Edge";
+//   ];
+// }
+```
+
+</details>
+
 ### `ts-graphviz/ast` モジュール 🔢
 
 > このパッケージのステータスは ![beta](https://img.shields.io/badge/-beta-orange) です。
@@ -230,10 +333,11 @@ const dot = toDot(G);
 状態遷移図で記載している通り、下記の関数を提供しています。
 
 - **Model** から **AST** に変換する `fromModel` 関数
+- **AST** から **Model** に変換する `toModel` 関数
 - **AST** から **DOT** に変換する `stringify` 関数
 - **DOT** から **AST** に変換する `parse` 関数
 
-> **Note** 上記の図からわかるように、`ts-graphviz` パッケージで提供している `toDot` 関数は、 `fromModel` と `stringify` の合成関数です。
+> **Note** 上記の図からわかるように、`ts-graphviz` パッケージで提供している `toDot` 関数は、 `fromModel` と `stringify` の合成関数です。また、`fromDot` 関数は、 `parse` と `toModel` の合成関数です。
 
 詳しい利用方法は整備中です。
 TypeScriptの型定義を参考にしてください。

package/README.md

@@ -1,3 +1,4 @@
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/d6485f9858ed4b3e8ef76611a2896bc4)](https://app.codacy.com/gh/ts-graphviz/ts-graphviz?utm_source=github.com&utm_medium=referral&utm_content=ts-graphviz/ts-graphviz&utm_campaign=Badge_Grade_Settings)
 [![GitHub Action](https://github.com/kamiazya/ts-graphviz/workflows/NodeCI/badge.svg)](https://github.com/kamiazya/ts-graphviz/actions?workflow=NodeCI)
 [![npm version](https://badge.fury.io/js/ts-graphviz.svg)](https://badge.fury.io/js/ts-graphviz)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -101,6 +102,8 @@ const dot = toDot(G);
 <details>
 <summary>Advanced Usage</summary>
 
+##### Custom Class 🤖
+
 You can also add your own implementation by inheriting from the class.
 
 ```typescript
@@ -114,9 +117,9 @@ class MyCustomDigraph extends Digraph {
   }
 }
 class MyCustomNode extends Node {
-  constructor(id: number) {
-    super(`node${id}`, {
-      [_.label]: `This is Custom Node ${id}`
+  constructor(id: string) {
+    super(`node_${id}`, {
+      [_.label]: `This is Custom Node ${id}`,
     });
   }
 }
@@ -124,30 +127,88 @@ class MyCustomNode extends Node {
 class MyCustomEdge extends Edge {
   constructor(targets: EdgeTargetTuple) {
     super(targets, {
-      [_.label]: 'This is Custom Edge'
+      [_.label]: 'This is Custom Edge',
     });
   }
 }
 
 const digraph = new MyCustomDigraph();
-const node1 = new MyCustomNode(1);
-const node2 = new MyCustomNode(2);
+const node1 = new MyCustomNode('A');
+const node2 = new MyCustomNode('B');
 const edge = new MyCustomEdge([node1, node2]);
 digraph.addNode(node1);
 digraph.addNode(node2);
 digraph.addEdge(edge);
-const dot = toDot(g);
+const dot = toDot(digraph);
 // digraph "G" {
 //   label = "This is Custom Digraph";
-//   "node1" [
-//     label = "This is Custom Node 1",
+//   "node_A" [
+//     label = "This is Custom Node A";
+//   ];
+//   "node_B" [
+//     label = "This is Custom Node B";
+//   ];
+//   "node_A" -> "node_B" [
+//     label = "This is Custom Edge";
+//   ];
+// }
+```
+
+##### Models Context API ( `with` method) 🧅
+
+You can also use the _Models Context API_ to create custom classes for objects generated inside of Graph.
+
+
+The `with` methods of `Digraph`, `Graph`, and `Subgraph`, which are implementations of `GraphBaseModel`, are provided to predefine custom models.
+
+```typescript
+const g = new Digraph();
+g.with({
+  Node: MyCustomNode,
+  Edge: MyCustomEdge,
+});
+const a = g.createNode('A'); // MyCustomNode
+const b = g.createNode('B'); // MyCustomNode
+g.createEdge([a, b]); // MyCustomEdge
+const dot = toDot(g);
+// digraph {
+//   "node_A" [
+//     label = "This is Custom Node A";
+//   ];
+//   "node_B" [
+//     label = "This is Custom Node B";
 //   ];
-//   "node2" [
-//     label = "This is Custom Node 2",
+//   "node_A" -> "node_B" [
+//     label = "This is Custom Edge";
 //   ];
-//   "node1" -> "node2" [
-//     label = "This is Custom Edge",
+// }
+```
+
+##### `fromDot` function ⏪
+
+> The status of this function is ! [beta](https://img.shields.io/badge/-beta-orange).
+
+The main scenario for using this library is to use the `toDot` function, but it also supports conversions in the reverse direction.
+
+By converting **DOT** to **Model**, a portion of the code can be written in the DOT language.
+
+```typescript
+const G = fromDot(
+  `digraph {
+    node_A [
+      label = "This is a Label of Node A";
+    ];
+  }`,
+);
+
+G.edge(['node_A', 'node_B']);
+
+const dot = toDot(G)
+// digraph {
+//   "node_A" [
+//     label = "This is a Label of Node A";
 //   ];
+//   "node_A" -> "node_B";
 // }
 ```
 
@@ -219,6 +280,48 @@ const dot = toDot(G);
 > // }
 > ```
 
+
+<details>
+<summary>Advanced Usage</summary>
+
+##### Models Context API ( `withContext` function ) 💈
+
+
+The `withContext` function returns a _Model Factory_ function.
+
+This _Model Factory_ provides a means to replace `RootGraphModel` with a custom class, such as `Digraph` or `Graph`.
+
+This API provides a way to integrate declarative APIs and custom classes.
+
+```typescript
+const { digraph } = withContext({
+  Digraph: MyCustomDigraph,
+  Node: MyCustomNode,
+  Edge: MyCustomEdge,
+});
+
+const G = digraph((g) => {
+  const a = g.node('A'); // MyCustomNode
+  const b = g.node('B'); // MyCustomNode
+  g.edge([a, b]); // MyCustomEdge
+});
+const dot = toDot(g);
+// digraph "G" {
+//   label = "This is Custom Digraph";
+//   "node_A" [
+//     label = "This is Custom Node A";
+//   ];
+//   "node_B" [
+//     label = "This is Custom Node B";
+//   ];
+//   "node_A" -> "node_B" [
+//     label = "This is Custom Edge";
+//   ];
+// }
+```
+
+</details>
+
 ### `ts-graphviz/ast` Module 🔢
 
 > This module status is ![beta](https://img.shields.io/badge/-beta-orange).
@@ -230,10 +333,11 @@ An API is provided to handle ASTs for advanced use.
 The following functions are provided as described in the state transition diagram.
 
 - The `fromModel` function converts **Model** to **AST**.
+- The `toModel` function converts **AST** to **Model**.
 - The `stringify` function converts **AST** to **DOT**.
 - The `parse` function to convert from **DOT** to **AST**.
 
-> **Note** As you can see from the above figure, the `toDot` function provided by the `ts-graphviz` package is a composite function of `fromModel` and `stringify`.
+> **Note** As you can see from the above figure, the `toDot` function provided by the `ts-graphviz` package is a composite of `fromModel` and `stringify`. The `fromDot` function is a composite of `parse` and `toModel`.
 
 Detailed usage is TODO.
 Please refer to the TypeScript type definition.

package/lib/ast/index.cjs

@@ -59,7 +59,7 @@ const endOfLine = (eol) => {
   }
 };
 
-const AttributeListPrintPlugin$1 = {
+const AttributeListPrintPlugin = {
   match(ast) {
     return ast.type === 'AttributeList';
   },
@@ -253,8 +253,8 @@ const SubgraphPrintPlugin = {
   },
 };
 
-const defaultPlugins$1 = [
-  AttributeListPrintPlugin$1,
+const defaultPlugins$2 = [
+  AttributeListPrintPlugin,
   AttributePrintPlugin,
   CommentPrintPlugin,
   DotPrintPlugin,
@@ -273,7 +273,7 @@ const defaultPlugins$1 = [
 class Printer {
   options;
   /** @internal */
-  #plugins = [...defaultPlugins$1];
+  #plugins = [...defaultPlugins$2];
   constructor(options = {}) {
     this.options = options;
   }
@@ -5342,7 +5342,7 @@ function convertClusterChildren(context, model) {
   );
 }
 
-const AttributeListPrintPlugin = {
+const AttributeListPlugin = {
   match(model) {
     return model.$$type === 'AttributeList';
   },
@@ -5357,7 +5357,7 @@ const AttributeListPrintPlugin = {
   },
 };
 
-const EdgeConvertPlugin = {
+const EdgePlugin$1 = {
   match(model) {
     return model.$$type === 'Edge';
   },
@@ -5427,7 +5427,7 @@ const EdgeConvertPlugin = {
   },
 };
 
-const GraphConvertPlugin = {
+const GraphPlugin$1 = {
   match(model) {
     return model.$$type === 'Graph';
   },
@@ -5456,7 +5456,7 @@ const GraphConvertPlugin = {
   },
 };
 
-const NodeConvertPlugin = {
+const NodePlugin$1 = {
   match(model) {
     return model.$$type === 'Node';
   },
@@ -5481,7 +5481,7 @@ const NodeConvertPlugin = {
   },
 };
 
-const SubgraphConvertPlugin = {
+const SubgraphPlugin$1 = {
   match(model) {
     return model.$$type === 'Subgraph';
   },
@@ -5505,13 +5505,7 @@ const SubgraphConvertPlugin = {
   },
 };
 
-const defaultPlugins = [
-  AttributeListPrintPlugin,
-  EdgeConvertPlugin,
-  NodeConvertPlugin,
-  GraphConvertPlugin,
-  SubgraphConvertPlugin,
-];
+const defaultPlugins$1 = [AttributeListPlugin, EdgePlugin$1, NodePlugin$1, GraphPlugin$1, SubgraphPlugin$1];
 
 /**
  * @group Convert Model to AST
@@ -5519,7 +5513,7 @@ const defaultPlugins = [
 class FromModelConverter {
   options;
   /** @hidden */
-  #plugins = [...defaultPlugins];
+  #plugins = [...defaultPlugins$1];
   constructor(options = {}) {
     this.options = options;
   }
@@ -5530,7 +5524,6 @@ class FromModelConverter {
       commentKind,
       convert(m) {
         for (const plugin of plugins) {
-          /*  */
           if (plugin.match(m)) {
             return plugin.convert(context, m);
           }
@@ -5549,11 +5542,226 @@ function fromModel(model, options) {
   return new FromModelConverter(options).convert(model);
 }
 
+class CommentHolder {
+  comment = null;
+  set(comment) {
+    this.comment = comment;
+  }
+  reset() {
+    this.comment = null;
+  }
+  apply(model, location) {
+    if (location && this.comment?.location) {
+      if (this.comment?.kind === 'Block') {
+        if (this.comment.location.end.line === location.start.line - 1) {
+          model.comment = this.comment.value;
+        }
+      } else {
+        if (this.comment.location.end.line === location.start.line) {
+          model.comment = this.comment.value;
+        }
+      }
+    } else {
+      model.comment = this.comment?.value;
+    }
+    this.reset();
+  }
+}
+
+const DotPlugin = {
+  match(ast) {
+    return ast.type === 'Dot';
+  },
+  convert(context, ast) {
+    const commentHolder = new CommentHolder();
+    for (const stmt of ast.children) {
+      switch (stmt.type) {
+        case 'Comment':
+          commentHolder.set(stmt);
+          break;
+        case 'Graph':
+          const graph = context.convert(stmt);
+          commentHolder.apply(graph, stmt.location);
+          return graph;
+      }
+    }
+    throw Error();
+  },
+};
+
+function convertToEdgeTargetTuple(edge) {
+  return edge.targets.map((t) => {
+    switch (t.type) {
+      case 'NodeRef':
+        return { id: t.id.value, port: t.port?.value, compass: t.compass?.value };
+      case 'NodeRefGroup':
+        return t.children.map((t) => ({ id: t.id.value, port: t.port?.value, compass: t.compass?.value }));
+    }
+  });
+}
+
+const EdgePlugin = {
+  match(ast) {
+    return ast.type === 'Edge';
+  },
+  convert(context, ast) {
+    const edge = new context.models.Edge(
+      convertToEdgeTargetTuple(ast),
+      ast.children
+        .filter((v) => v.type === 'Attribute')
+        .reduce((prev, curr) => ({ ...prev, [curr.key.value]: curr.value.value }), {}),
+    );
+    return edge;
+  },
+};
+
+function applyStatements(graph, statements) {
+  const commentHolder = new CommentHolder();
+  for (const stmt of statements) {
+    switch (stmt.type) {
+      case 'Subgraph':
+        const subgraph = stmt.id ? graph.subgraph(stmt.id.value) : graph.subgraph();
+        applyStatements(subgraph, stmt.children);
+        commentHolder.apply(subgraph, stmt.location);
+        break;
+      case 'Attribute':
+        graph.set(stmt.key.value, stmt.value.value);
+        commentHolder.reset();
+        break;
+      case 'Node':
+        commentHolder.apply(
+          graph.node(
+            stmt.id.value,
+            stmt.children
+              .filter((v) => v.type === 'Attribute')
+              .reduce((prev, curr) => ({ ...prev, [curr.key.value]: curr.value.value }), {}),
+          ),
+          stmt.location,
+        );
+        break;
+      case 'Edge':
+        commentHolder.apply(
+          graph.edge(
+            convertToEdgeTargetTuple(stmt),
+            stmt.children
+              .filter((v) => v.type === 'Attribute')
+              .reduce((prev, curr) => ({ ...prev, [curr.key.value]: curr.value.value }), {}),
+          ),
+          stmt.location,
+        );
+        break;
+      case 'AttributeList':
+        const attrs = stmt.children
+          .filter((v) => v.type === 'Attribute')
+          .reduce((prev, curr) => ({ ...prev, [curr.key.value]: curr.value.value }), {});
+        switch (stmt.kind) {
+          case 'Edge':
+            graph.edge(attrs);
+            break;
+          case 'Node':
+            graph.node(attrs);
+            break;
+          case 'Graph':
+            graph.graph(attrs);
+            break;
+        }
+        commentHolder.reset();
+        break;
+      case 'Comment':
+        commentHolder.set(stmt);
+    }
+  }
+}
+
+const GraphPlugin = {
+  match(ast) {
+    return ast.type === 'Graph';
+  },
+  convert(context, ast) {
+    const G = ast.directed ? context.models.Digraph : context.models.Graph;
+    const graph = new G(ast.id?.value, ast.strict);
+    applyStatements(graph, ast.children);
+    return graph;
+  },
+};
+
+const SubgraphPlugin = {
+  match(ast) {
+    return ast.type === 'Subgraph';
+  },
+  convert(context, ast) {
+    const subgraph = new context.models.Subgraph(ast.id?.value);
+    applyStatements(subgraph, ast.children);
+    return subgraph;
+  },
+};
+
+const NodePlugin = {
+  match(ast) {
+    return ast.type === 'Node';
+  },
+  convert(context, ast) {
+    const node = new context.models.Node(
+      ast.id.value,
+      ast.children
+        .filter((v) => v.type === 'Attribute')
+        .reduce((prev, curr) => ({ ...prev, [curr.key.value]: curr.value.value }), {}),
+    );
+    return node;
+  },
+};
+
+const defaultPlugins = [NodePlugin, EdgePlugin, SubgraphPlugin, GraphPlugin, DotPlugin];
+
+/**
+ * @group Convert AST to Model
+ * @alpha
+ */
+class ToModelConverter {
+  options;
+  /** @hidden */
+  plugins = [...defaultPlugins];
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /**
+   * Convert AST to Model.
+   *
+   * @param ast AST node.
+   * @alpha
+   */
+  convert(ast) {
+    const plugins = [...this.plugins];
+    const context = {
+      models: common.createModelsContext(this.options.models ?? {}),
+      convert(m) {
+        for (const plugin of plugins) {
+          if (plugin.match(m)) {
+            return plugin.convert(context, m);
+          }
+        }
+        throw Error();
+      },
+    };
+    return context.convert(ast);
+  }
+}
+
+/**
+ * @group Convert AST to Model
+ * @beta
+ */
+function toModel(ast, options) {
+  return new ToModelConverter(options).convert(ast);
+}
+
 exports.Builder = Builder;
 exports.FromModelConverter = FromModelConverter;
 exports.Printer = Printer;
 exports.SyntaxError = SyntaxError;
+exports.ToModelConverter = ToModelConverter;
 exports.createElement = createElement;
 exports.fromModel = fromModel;
 exports.parse = parse;
 exports.stringify = stringify;
+exports.toModel = toModel;