@cardenelabs/dragon 0.35.0 → 0.36.0

package/README.md

@@ -1,6 +1,6 @@
 # @cardenelabs/dragon
 
-動く図を、人は行ごとの記法で、AI は JSON で書くための package。
+動く図を、人は dragon記法で、AI は JSON で書くための package。
 
 ## 入れ方
 
@@ -12,15 +12,53 @@ npm install @cardenelabs/dragon
 今までの記法 (日本語の鍵の YAML と JSON)、`textDslToDiagram` と `jsonToDiagram` を含む入口、`@cardenelabs/cdl` へ渡して描く仕組みは [#2983](https://github.com/cardene777/dragon/issues/2983) で消した。
 作り直しで決めたことは [#2982](https://github.com/cardene777/dragon/issues/2982) にまとめている。
 
+0.36.0 では記法を dragon記法に作り直したため、0.35.x の記法の file は書き直さないと読めない。
+原本の JSON は 0.35.x と同じ形で、そのまま読める。
+書き直す時は、下の dragon記法の節と、前の形と新しい形の対応表を見る。
+
 この package は次の 4 つを持つ。
 
 | 持つ物 | 形 |
 |---|---|
 | 原本 | 共通の骨格と図の種類ごとの欄を持つ JSON。版を持ち、古い版は読む時に変換する |
-| 記法 | 1 行が 1 つの文になる行ごとの記法。JSON と行き来でき、日本語の語でも英語の語でも書ける ([書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.md)、[英語の語の書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.en.md)) |
+| 記法 | 行の頭の英語の語で行の種類が決まる dragon記法 (下の節)。JSON と行き来でき、名前と文は日本語でも書ける ([書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.md)、[英語の書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.en.md)) |
 | 描く部品 | 原本から時系列図と構成図を描き、段ごとに動かす部品。cdl には頼らない |
 | 書き出し | 同じ原本から mp4、GIF、HTML、PNG を書き出す命令 |
 
+## dragon記法
+
+どの行も次の決まり 4 つに従う。
+
+1. 行の種類は行の頭の英語の語で決まる。矢印の行だけは箱の名札から始まる
+2. 鍵と値はコロンで区切り、属性は `[ ]` の中に `,` で並べる
+3. 空白を含む名前と文は、行末か `[` の前に置く。`,` か `]` を含む値と、`[` を含む名前だけを `"` で囲む
+4. 入れ子は `group … end` だけ。段は次の `step` までで、字下げは読みやすさのために付ける。`say` の続きの行だけは `say` より深く字下げする
+
+行の頭の語は `sequence` `architecture` `group` `end` `box` `strip` `step` `say` `code` `act` `note` `set` で、線の行は `名札 -> 名札` と書く。
+
+```dragon
+architecture 注文を倉庫へ回す
+
+group 店側 as 店 [note: 注文を受ける側, color: blue, icon: cart]
+  box 受付 [note: 注文を受ける, icon: app]
+end
+
+group 倉庫側 as 倉庫 [note: 品物を送る側, color: green, icon: box]
+  box 出荷 [note: 品物を送る, icon: truck]
+end
+
+step 出荷に回す
+  say
+    受付が注文の番号を 2 つまとめて出荷に回す。
+    出荷は届いた番号の順に品物を送る。
+  受付 -> 出荷: 送ってよい [tag: "#42, #43"]
+```
+
+`parseNotation` は記法を原本の JSON に、`printNotation` は原本の JSON を記法に直す。
+誤りの文の言葉は `parseNotation(text, { lang: "en" })` のように渡した言葉で決まり、渡さなければ日本語になる。
+前の形の記法 (`時系列図` か `構成図` で始まる形) は読まず、その行の新しい形を示す誤りで止まる。
+前の形と新しい形の対応表は [`CHANGELOG.md`](https://github.com/cardene777/dragon/blob/main/CHANGELOG.md) にある。
+
 ## 書き出し
 
 書き出しは画面なしの Chromium で、頁と同じ描画を時刻を止めて 1 コマずつ撮る。
@@ -44,7 +82,7 @@ dragon export ccip.json --out out
 | `--width <px>` | 枠の幅。見せ方 (全体を止める / 寄って追う) を選び、寄って追う窓の幅になる |
 | `--palette <名前>` | 色味 (`clear` / `paper` / `night`、既定は `paper`) |
 | `--theme <明暗>` | `light` か `dark` |
-| `--lang <言葉>` | 図の中の字 (全体図の札、HTML の読み上げの名前、描けない時の断りの文) と、命令が出す使い方の文と誤りの文の言葉 (`ja` か `en`)。既定は記法の file の言葉で、JSON の原本と file を読む前の誤りは `ja`。記法の行の誤りだけは、書き方の例が合うよう記法の file の言葉で出す |
+| `--lang <言葉>` | 図の中の字 (全体図の札、HTML の読み上げの名前、描けない時の断りの文) と、命令が出す使い方の文と誤りの文の言葉 (`ja` か `en`)。記法の file でも JSON の原本でも、既定は `ja` |
 | `--fps <数>` | mp4 の 1 秒のコマの数 (既定 30) |
 | `--gif-fps <数>` | GIF の 1 秒のコマの数 (既定 10) |
 | `--format <形>` | 書き出す形を `,` で区切る (既定 `mp4,gif,html,png`) |