reladraw

reladraw

図のためのテキスト言語です。ソースを入力すると、ランタイム依存関係のないスタンドアロンの SVG が出力されます。

ほかの図言語では、配置をレイアウトエンジンに任せるため、要素がどこに配置されるかは、書いた内容から予測できない出力になります。reladraw はその逆です。ファイルには、人が声に出して言うような表現（right of api、below worker (gap: tight)、even with queue）で配置を記述し、ツールはそのとおりに描画します。配置を決めたり、スペースを作るためにボックスを動かしたり、線を何かの周りに引き回したりすることはありません。

ここでは特に重要な点です。生成した SVG を見ることはできません。自動レイアウトでは推測するしかありませんが、reladraw では配置が、たった今書いた文の中にあります。また、図が意図どおりに読み取れない可能性がある場合は、ツールが言葉で知らせてくれます。

インストール済みか、またこのスキルと同じバージョンか確認する

このスキルでは reladraw 0.19.0 を説明しています。セッションごとに最初のレンダリングを行う前に、次を実行してください。

reladraw --version

• **同じ場合：**何も言いません。
• 古い場合、または --version が認識されない場合（このオプションは 0.17.1 で導入されました）：このツールはこのページより古く、説明されている機能の一部を使用できません。ユーザーに伝え、npm install -g reladraw@latest を案内してください。
• **新しい場合：**このスキルの内容は古くなっています。ユーザーに伝え、更新するために npx skills add reladraw/reladraw -g を案内してください。その間は作業を続けてください。エラーに置き換え後の表記が示されている場合は、このページではなくエラーに従ってください。

reladraw がインストールされていない場合は、インストールせずに npx reladraw を使えます。また、npm install -g reladraw でインストールできます。

手順

1. .reladraw ファイルを作成します。
2. reladraw render diagram.reladraw -o diagram.svg を実行します。（-o - は標準出力に書き込みます。既定では入力パスの拡張子が .svg になります。）
3. 失敗した場合は、エラーに行番号と、代わりに何を書くべきかが示されます。修正して再実行します。
4. 成功した場合は、出力された指摘事項を読みます。それぞれ、意図どおりに読み取れない可能性がある箇所とその場所、程度を示す一行のメッセージです。

diagram.reladraw:12: warning(text-overlap): text "statements" covers the top-left corner of node resolver; the overlap is 3 units wide and 2 units tall
diagram.reladraw:9: warning(edge-node-overlap): line api -> db crosses node cache, in and out of its top

5. 配置を変えるか、線の経路を指定して、ソース内の各指摘事項を修正し、指摘事項がなくなるまで再実行します。reladraw check diagram.reladraw は SVG を書き出さずに指摘事項を出力します。
6. ファイルを引き渡す前に reladraw format diagram.reladraw を実行します。プロジェクトの .reladraw-format があればその設定に従って文を列に揃え、間隔を整えます。ファイルの描画内容は変わりません。これにより、作成したファイルもユーザーのプロジェクトに既にあるファイルと同じように読みやすくなります。

エラーも指摘事項もないファイルでは、どの要素もほかの要素に重なっていません。ただし、それだけで図がよいとは限りません。ソースを読み直し、配置が意図した内容になっていることを確認してください。また、大きな図の場合は、指摘事項を確認したものの、レンダリング結果は見ていないことをユーザーに伝えてください。

基本の考え方

**ファイルで要素の配置を指定し、ツールはそのとおりに描画します。**間隔は、指定した距離になります。ボックスは配置指定のとおりの場所に置かれ、何かに押されて動くことはありません。線は、四角形や曲線にするか、通過する場所を指定しない限り、2つのボックスの間を直線で結びます。重なるものはそのまま重ねて描画され、報告されます。

つまり、問題を解決するには、ツールがうまく処理してくれることを期待するのではなく、ソースに記述を加える必要があります。同じ場所にある2つのボックスは、片方をもう一方に接するように配置します。ボックスを通過する線は、via: を使って通過場所を指定します。ボックスに近すぎるテキストは、間隔を広げます。

ファイルを書く

文は行頭から始めます。長い文はインデントした次の行に続けます。空行またはインデントのない行があると文が終わります。インデントによって、ある要素が別の要素の内側に入ることはありません。// はコメントの開始を表し、文の後ろに置くこともできます。

文は、位置指定の先頭部分（キーワード、名前、テキスト）に続けて、属性と配置を任意の順序で記述します。コロンで終わる単語は属性の開始を表し、それ以外の単語は属性を開始しません。

ノード

node <name> ["<text>" [(<text settings>)]] [<placement> | <attribute>] ...

テキストを省略すると、ノードには名前が表示されます（node parser は「parser」と表示されます）。意図的に空白にするには "" と記述します。テキスト内の /（前後にスペースを置いたスラッシュ）は改行になります。TCP/IP と URL はそのまま表示されます。

本文は shape: rectangle | document | circle | diamond | pill | parallelogram | hexagon | trapezoid | triangle | cylinder | none（none はそのままのテキストで、メモやキャプションに使用します。幾何学的な名前のないフローチャート形状は flow- の後に意味を示す名前を付けます。たとえば flow-subprocess や flow-delay です。設定は角括弧内に続けます。shape: triangle (aim: up)）、または icon: disk | desktop | laptop | package | cubes | cube | database で、枠のない画像です。badge: <icon> とすると、ラベルの一部としてテキストの横に画像が表示されます。リストにない画像は icon <name> で宣言し、""" マークで囲んだ SVG を指定します。組み込みのものを優先してください。

node dump  "nightly dump"  shape: document
node unit  icon: cube  right of dump
node drive "External HD"  badge: disk  below dump
node aside "a remark that folds" (wrap: 20)  shape: none  right of drive

配置

above X          below X          left of X        right of X
above-left of X  above-right of X below-left of X  below-right of X
even with X      top even with X  bottom even with X  left even with X  right even with X

• ファイル内で配置されないノードは、基準となるノードの1つだけです。 それ以外のノードは、直接またはほかのノードを介して、何かに対して配置されます。
• 間隔は厳密です。 配置の角括弧内で none、tight、normal（デフォルト）、wide を指定します。たとえば right of a (gap: tight) のように指定するか、2 right of a のようにファイルの単位で数値を指定します。標準的なボックスの高さは約4単位です。
• 方向だけを指定すると、対象を基準に中央揃えされます。 right of a だけを指定すると、ボックスは a と同じ高さに配置されます。同じ軸上に別の配置を指定すると、中央揃えに代わります。right of a even with b
• 各軸は一度だけ指定します。 同じ軸に2つの配置を指定すると、拒否されます。例外は1つだけです。right of a left of b とすると、ボックスはその間の空間の中央に配置されます。その場合は、高さを指定する必要があります。
• 複数の対象は1つの領域として扱われます。 below a and b とすると、2つの下に、それらの中央に配置されます。
• ボックスを移動するものはありません。 2つのボックスに right of a を指定すると、両方が同じ位置に配置され、その旨が報告されます。連結する（b right of a、c right of b）か、レイアウトを指定したコンテナに入れてください。

コンテナ

ドットで区切られた名前は子要素です。server.api は server の中にあり、親を先に宣言します。コンテナは子要素を囲むボックスです。次の2つの方法のいずれかで配置します。

node server "Server"  layout: column (widths: match)
node server.api    "API"
node server.worker "Worker"

node lab "Lab"  right of server (gap: wide)
node lab.pc   "PC"
node lab.nas  "NAS"  right of lab.pc (gap: tight)

layout: column または layout: row を指定すると、子要素が記述された順に並びます。角括弧では gap:、widths: match、align-children: left | center | right を指定できます。レイアウトを指定しない場合は、子要素のうち1つだけが配置されず、残りはそれを基準に配置されます。コンテナに shape: none を指定するとボックスは描画されず、1つの形状として配置対象にできるグループになります。

タイトルはデフォルトで (inside top) に配置され、上辺に沿って中央揃えされます。(inside top, align: left) は左上に配置し、(on top) または (outside top) は枠上または枠の上に配置します。

テキスト

テキストに関する設定はすべて、テキストの後の角括弧内に記述します。color、size（small | normal | large）、wrap（n文字ごとに折り返し）、align を指定できます。

style dim  text: (color: theme-muted)
node grinder "Grinder / [dim]medium-fine[/dim]"
node note "a longer remark that folds" (size: small, wrap: 30)  shape: none  below grinder (gap: tight)

[dim]…[/dim] を使うと、テキストの一部にスタイルの見た目を適用できます。スタイルはキーに角括弧を付けて指定します。style aside text: (size: small, color: theme-muted) テキストだけを記述する場合は、必ず (wrap: n) を指定してください。 指定しないと、文が隣の要素の上を横切る長い1行になります。

線

edge [<name>] <from> -> <to> ["<text>" [(<placement>)]] [attributes]

<-、<->、--も使えます。また、両端に印を付けることもできます：a <|-- b、a *--o b、a diamond--> b。from:とto:は、最初と2番目に書いた名前の側を指定します：from: right to: left。

• デフォルトでは直線です。2つのボックスの間を通り、その間にあるものも通過して、レポートされます。線が接続する2つのボックスと側面から経路を読み取るには、line: (path: square)またはline: (path: curved)を指定します。
• via:で線が通過する場所を列挙します：via: cache topはcacheのすぐ上を通り、via: between a and bはそれらの間の点を通り、via: proxyはボックスの中心を通ります。これを使って、線を何かの周囲に迂回させます。
• テキストは線の中央に配置されます。 (at: start)、(at: 1/4)、(above edge)、(on: longest level)、(above some_box)で位置を指定します。テキストによってボックスが移動することはないため、ラベル付きの線には十分なスペースを確保してください。ラベル付きの線で結ばれたボックス間では、normalの間隔は単語を置くには狭すぎるため、(gap: 12)などを使います。
• line: (pattern: dashed, thickness: thick, corners: rounded, color: #d2904e)。line: redだけの場合は色を指定します。

ボックスの一部に対して配置する

node bob      "Bob the builder" (inside top)  height: 7
node bob_link "bob.example.com" (size: small)  inside bob bottom-center  shape: none
node count    "3"  on bob top-right  shape: circle

ボックスの一部には、text、top、bottom、left、rightの各辺、そして9つの点（top-left、top-center、… center … bottom-right）があります。insideはノードをボックス内のその部分に寄せて配置し、outsideはその外側に配置し、onはその部分の中央に配置します。

スタイルと色

style store  fill: theme-primary-subtle  border: theme-primary  badge: database
node records "Records"  style: store

fillはボックスの塗りつぶし、borderはその輪郭、lineは辺の線を指定します。テキストの色は角括弧内に指定します。corners: sharpはボックスの角を四角くします。ライトテーマとダークテーマの両方で見やすいテーマカラーを使うのがおすすめです。theme-primaryとtheme-secondaryはアクセントカラー、-subtleはページになじむように薄めたアクセントカラー（ボックスの塗りつぶしに使います）、theme-mutedは控えめなテキスト色です。16進数カラーやCSSカラーは、どのテーマでも同じ色になります。

小さなファイルの全体例

// A request path, left to right.
style store  fill: theme-primary-subtle  border: theme-primary  badge: database

node browser  "Browser"
node api      "API server"  right of browser (gap: 10)
node db       "Postgres"    right of api (gap: 10)  style: store
node worker   "Worker"      below api (gap: wide)

edge browser -> api  "HTTP"
edge api -> db       "SQL"
edge worker -> db    "writes"  to: bottom  line: (path: square)

node aside "The worker shares the database / but takes no HTTP traffic." (wrap: 30)  shape: none  below worker (gap: tight)

問題になりやすい点

• 同じ位置に配置された2つのボックス。 node b right of aとnode c right of aでは、bとcが同じ位置になります。cをbに対して配置するか、layout:を使ったコンテナを使ってください。
• 近接したボックス間のラベル付きの線。 テキストは線上に配置され、間隔は広がらないため、ボックスに重なり、レポートされます。配置の間隔を広げてください。
• 配置されていない2つのボックス。 配置されていないボックスは1つまでです。エラーには両方の名前が示されます。
• 軸を2回指定する。 right of a even with aは問題ありませんが、below a even with bは高さについて2つの指定をしているため、拒否されます。
• 古い構文。 level withはeven withに、ノードのgap:は配置の角括弧内に、below cやbetween a and bのような辺の節はvia: c bottomやvia: between a and bに、contents:はlayout: column (…)に、ノードのテキストに対するat:は(inside top, align: left)などに、deck:はコンテナとlayout: deck cards: "Drive 1" "Drive 2"に置き換えます。それぞれ、代わりに書くべき構文とともに拒否されます。
• note、box、link。 これらは文ではありません。ノートはnode … shape: noneで、キーワードはnodeとedgeです。
• 座標。 座標はありません。すべての位置は、図中の何かを基準にします。
• コメントとしての#。 これは16進数カラーの開始記号です。コメントには//を使います。
• 別の言語からの推測。 波括弧もセミコロンもサブグラフもありません。ここに書かれていないものを使いたい場合は、独自に構文を作る前にreference/syntax.mdを確認してください。

リファレンス

reference/syntax.mdは構文の完全なリファレンスです。すべての構文要素、点と領域、経由点と名前付き区間、バンドル、サイズ、ガイド、描画順、検出内容、この言語で拒否されるものとその理由、各バージョンでの変更点を網羅しています。このページで説明されていない構文要素が必要な場合や、エラーまたは検出内容が予想外の動作を示している場合に参照してください。