ts-graphviz 1.0.1 → 1.2.0

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,39 +126,98 @@ 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>
 
 
 #### 宣言的な API 😎
 
-`Graph` や `Digraph` を作成する際に、より **DOT** 言語に近い記法を提供するために _Builder Functuion_ を使うことができます。
+`Graph` や `Digraph` を作成する際に、より **DOT** 言語に近い記法を提供するために _Model Factory_ を使うことができます。
 
 **Model** にも宣言的な API を用意しており、一貫して宣言的なパラダイムを選択することもできます。
 
@@ -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";
 // }
 ```
 
@@ -155,7 +216,7 @@ const dot = toDot(g);
 
 #### Declarative API 😎
 
-When creating `Graph` or `Digraph`, you can use _Builder Function_ to provide a notation more similar to the **DOT** language.
+When creating `Graph` or `Digraph`, you can use _Model Factory_ to provide a notation more similar to the **DOT** language.
 
 **Model** also has a declarative API, so you can consistently choose a declarative paradigm.
 
@@ -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.