最初に
今回はpintoraというJavaScriptライブラリを使用してテキストでダイアグラムを書いてみようと思います！
pintoraはブラウザとNode.jsで動作する拡張可能なJavaScriptライブラリです。
執筆時点ではActivity Diagram、Component Diagram、Entity Relationship Diagram、Mind Map、Sequence Diagramをサポートしています。
また、VSCodeを利用している場合は専用のプラグインを導入することで構文ハイライトとプレビューのサポートを提供しています。
ドキュメントはこちらにあります。
私はCodeSandboxを利用して試しに書いてみたのでサンプルコードを載せておきます。
それでは一通りダイアグラムを触ってみたいと思います。
サンプルコード
pintora-exercise - CodeSandbox
注意
pintoraをReactで使ってみたのですが、JSX周りで上手く変換できていないのかドキュメント通りに書いても上手く表示されませんでした。
なのでHTMLでscriptタグを使ってpintoraを読み込ませています。
そしてダイアグラムのコードをそのまま書いても表示されません。
class="pintora"を要素に追加してあげることで要素内の文字列をダイアグラムのコードと認識してくれます。
mermaid.jsなどを触ったことがある方はわかるかなと思います。
Activity Diagram
それではまずはActivity図からやってみましょう！
<div class="pintora"> activityDiagram :Action 1; :Action 2; </div>
まずはどの種類のダイアグラムを使うかを定義します。
アクティビティ図を使う場合はactivityDiagramと書きます。
その下にアクションを:と;で囲みます。
さらにその下に繋げたいアクションを書くと以下の用に表示されます。
矢印は勝手に着くのでつなげたい順に書いていけば良いです。
どんどんつなげてみます。
次にアクティビティ図では開始と終了の印があるかと思います。
それは以下のように書きます。
<div class="pintora"> activityDiagram start :Action 1; :Action 2; :Action 3; :Action 4; end </div>
アクションをstartとendで囲ってあげます。
そうすると以下のようになります。
それでは次に条件分岐をしてみましょう。
Action2の処理結果が成功したならAction3を、失敗したならAction4に分岐します。
<div class="pintora"> activityDiagram start :Action 1; if (Action2が成功したか？) then :Action 3; else (no) :Action 4; endif end </div>
以下のように出力されます。
プログラマブルにかけますね。
ちょっと解析周りが弱いのかスペース入れるところをちゃんとしないと上手く出力されません…
今後の改善でしょうか。
最後にループを試してみましょう。
<div class="pintora"> activityDiagram start :Action 1; :Action 2; while (n > 100) :Action 3; endwhile :Action 4; end </div>
このように出力されます。
Component Diagram
コンポーネント図を書いてみます。
<div class="pintora"> componentDiagram component comp1 [comp2] [comp3] as c3 </div>
コンポーネントの定義はコンポーネント名の前にcomponentと宣言するか、[と]でコンポーネント名を囲むことで作れます。
またasを使うことでエイリアスを作成でき、後でリレーションを行う時に役立つそうです。
そしてインターフェースの作るときはinterfaceを先頭に付けてあげるか、()を付けることで定義できます。
気になったのがcomponentの場合は、コンポーネント名を"で囲みませんが、interfaceの場合はインターフェース名を"で囲む必要があることです。
詳細は分かりませんが、ちょっとやりにくさを感じました。
<div class="pintora"> componentDiagram interface "I1" () "I2" () "I3" as impl3 </div>
リレーションを付けてみます。
書き方を見てみたかったのでドキュメントのコードをそのままコピペさせていただきました。
<div class="pintora"> componentDiagram DataQuery -- [Component] [Component] ..> HTTP : use </div>
要素間のリレーションは--、-->、..、..>で表現できます。
また[、]で囲わないとインターフェースとして出力されるようです。
あと:を付けることで要素間に説明を入れることができます。
Entity Relationship Diagram
ER図を書いてみます。
以下のように書きました。
結構適当に書いたので雰囲気を感じ取っていただければと思います。
<div class="pintora"> erDiagram USER { bigint id PK string name string email } CURT { bigint user_id FK bigint item_id FK } ITEM { bigint id PK string name } USER ||--|{ CURT : have ITEM ||--|{ CURT : add </div>
ER図を出力するにはerDiagramを付けます。
そのあとにエンティティを定義して、リレーションを付けています。
エンティティは直感で書けそうですね。
リレーションの記号を覚えるのがちょっと難しそうですが、||--||、||--o{、||--|{、}|..|{と書けます。
||--||：1対1
||--|{：1対多
}|..|{：多対多
を表現でき、非依存であるかをoを付けることで表現します。
Mind Map
最後にマインドマップを書いてみようと思います。
以下のように書けます。
<div class="pintora"> mindmap * マインドマップとは？ ** 使い方 *** 会議 *** ブレインストーミング *** チーム ** 利用シーン *** 会議 *** 企画時 -- 考え方 --- アイデア -- 書き方 --- ホワイトボード --- 付箋 -- :改行して 書けます; </div>
マインドマップが一番マークダウンに近い感じで書けますね！
基本は*を使って*の個数により階層を表現します。
デフォルトの向きは左から右です。
しかし、-を使うことで向きを逆転できます。
そして、:と;で囲むことでマルチラインで書くことができます。
出力はこんな感じです
最後に
やってみた感想としては書き方を覚えてしまえば、ダイアグラムの作成が楽になるのではないでしょうか！
図の配置とかも気にする必要ないですし、いい感じに出力してくれます。
何よりこういった図をテキストでかけることは開発との相性が良いと思います。
gitで管理しやすいかなと感じました！
また完全に妄想ですが、ビジュアルリグレッションテストでCIと組み合わせてプッシュしたら画像を生成してマージ先の画像と差分チェックしたりすると、より視覚的に変更点がわかるかなと思います。
あとは構文エラー時の出力結果がもう少しわかりやすく表示してくれるとありがたいです。
今後に期待したいと思います。
興味ある方は是非使ってみてはいかがでしょうか？
