文氏圖／歐拉圖（Venn / Euler diagram）

關於文氏圖與歐拉圖

**文氏圖（Venn diagram）**使用重疊的圓來顯示一組集合之間所有可能的邏輯關係——無論每個交集中是否實際包含元素。**歐拉圖（Euler diagram）**是更通用的形式：只在關係實際存在時繪製圓，因此完全包含在另一個集合中的集合以巢狀圓表示，兩個不相交的集合則完全不重疊。John Venn 於 1880 年提出了固定重疊形式；Leonhard Euler 在 1760 年代描述了通用的集合包含形式。

教育工作者用它來教導集合論；資料分析師用它來顯示各客群之間的受眾重疊（電子郵件名單 ∩ 行動使用者 ∩ 付費訂閱者）；生物學、語言學與醫學領域的研究人員用歐拉圖來映射分類或概念層次結構。Schematex 以一套 DSL 支援所有四種常見的使用模式——宣告式計數、元素列舉、區域標籤，以及歐拉子集／不相交／重疊關係——並可在單一圖表中混合使用。請參閱 Wikipedia 關於文氏圖與歐拉圖的文章以了解背景知識。

1. 第一個文氏圖

最小的實用圖：兩個集合、一個重疊，兩個獨有區域。

四條規則涵蓋 80% 的使用情境：

1. 以 venn 開頭，後面可接一個引號標題。
2. 以 set ID "Label" 宣告每個集合——id 供內部使用，標籤顯示於圖中。
3. 使用 A & B : value 為交集指定值，使用 A only : value 為獨有區域指定值。
4. 以 config: 行配置外觀；圖表模式（venn 與 euler）可以明確設定或留為 auto。

註解必須以 # 開頭，獨立成一行。

2. 集合

集合宣告在圖中建立一個圓。

set ID "Label" [color: "#hex"]

集合必須在區域或關係行中被引用之前宣告。

3. 區域

區域為交集或獨有區域指定一個值。四種 DSL 模式可在一個圖中混合使用。

3.1 宣告式模式——計數與百分比

為命名區域指定數字或百分比。區域鍵可以是以 & 分隔的集合 id 列表（用於交集），或 ID only（用於不被其他任何集合覆蓋的部分）。

A & B : 320          # 整數計數
A & B & C : 45       # 三路交集
A only : 1450        # A 減去所有其他集合
A & B : 18.5%        # 百分比值

3.2 區域標籤（文字）

使用 region 關鍵字前綴，並指定引號字串而非數字。字串渲染於區域內。

region A & B : "Nurture"
region B & C : "Convert"
region A & B & C : "Loyal customer"

3.3 列舉模式——元素列表

列出每個集合的實際元素。Schematex 自動計算所有交集。

ID = { element1, element2, element3 }

元素以逗號分隔的裸字或引號字串表示。列舉集合不需要明確的 set 宣告——宣告是隱式的。

4. 歐拉關係

歐拉關係表達結構性的包含或分離——一個集合是另一個集合的子集、兩個集合完全不相交，或它們僅部分重疊。它們必須引用已用 set 宣告的集合 id。

from subset to    # from 完全在 to 內部（也可用 "in"）
from in to        # "subset" 的別名
from disjoint to  # from 與 to 不重疊
from overlap to   # from 與 to 部分重疊（明確指定——對不相關集合而言是預設值）

5. 配置

config: 行調整圖表行為，每個設定獨立成一行。

設定也可以行內寫在標題行：venn "Title" [proportional: true, showPercent: true]。

venn "Segment overlap"
config: proportional = true
config: showPercent = true
config: blendMode = screen

佈局選擇：

• layout venn — config: diagram = venn 的替代形式（剖析結果相同）。
• layout euler — config: diagram = euler 的替代形式。
• layout auto — config: diagram = auto 的替代形式。

6. 標籤與註解

• 標題： venn "My diagram" — 僅限第一行。
• 集合標籤： set A "Email subscribers" — set 行上的引號字串。
• 區域值： 指定於 : 後的整數、百分比、引號字串或元素列表。
• 註解： # 位於行首（前方可有空白）。

7. 保留字與跳脫

行首保留字： venn（標題）、set、config:、layout、region。

區域鍵中的保留運算子： &（交集）、only（獨有區域）。

歐拉關係關鍵字： subset、in、disjoint、overlap——不可用作集合 id。

ID 規則： 必須符合 [A-Za-z][A-Za-z0-9_-]*。含空格的標籤放在引號 "Label" 欄位中。

8. 常見錯誤

9. 語法（EBNF）

document       = header (blank | comment | config | layout-stmt | set-decl | enum-decl | euler-rel | region)*

header         = "venn" ( ":"? WS quoted-string )? ( WS "[" config-props "]" )? NEWLINE
quoted-string  = '"' any-char-but-quote* '"'

config         = "config" WS ":" WS config-key WS "=" WS config-value NEWLINE
config-key     = "diagram" | "proportional" | "palette" | "blendMode" | "showCounts" | "showPercent"

layout-stmt    = "layout" WS ( "venn" | "euler" | "auto" ) NEWLINE

set-decl       = "set" WS id WS quoted-string ( WS "[" set-props "]" )? NEWLINE
set-props      = "color:" quoted-hex | "fill:" quoted-hex

enum-decl      = id WS "=" WS "{" element-list "}" NEWLINE
element-list   = element ( "," element )*
element        = quoted-string | bare-word

euler-rel      = id WS euler-op WS id NEWLINE
euler-op       = "subset" | "in" | "disjoint" | "overlap"

region         = "region"? WS region-key WS ":" WS region-value NEWLINE
region-key     = id WS "only"
               | id ( WS "&" WS id )+
region-value   = integer | percent | quoted-string | "[" element-list "]"

percent        = number "%"
id             = [A-Za-z] [A-Za-z0-9_-]*
comment        = "#" any NEWLINE

權威來源：src/diagrams/venn/parser.ts。若此文件與剖析器有所出入，以剖析器為準——請開立 issue 回報。

10. 路線圖

已規劃——目前尚無法剖析。 請勿在今日生成的 DSL 中使用以下功能；剖析器會拒絕或忽略它們。

• 三路與 N 路歐拉巢狀 — 渲染器目前在文氏圖模式下最多支援 3 個集合；具有複雜包含關係的大型歐拉圖尚未完全佈局。
• fill: 顏色別名 — set 上的 fill: 屬性被剖析器接受（作為 color: 的別名），但渲染器目前只使用 color:。
• 區域上的 label: — region A & B [label: "Core"] 語法，用於分離標籤與值。
• 面積比例歐拉圖 — proportional: true 目前只影響文氏圖模式；歐拉包含佈局忽略此旗標。
• and 關鍵字 — 自然語言的 A and B : 120 作為 A & B : 120 的別名。

如需提前實現以上功能，請在 GitHub issues 中追蹤進度。

相關範例

範例庫中的即用情境：