mdom 0.2.0 → 0.3.0

data/lib/mdom/node/nodes.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require_relative "../node"
+
+# Markdown DOM 的 AST1 节点定义。
+#
+# 块级解析产出的树只描述**块结构**：段落、标题、列表等的正文一律以
+# +attributes[:text]+ 保存**尚未做行内解析**的原文，等待后续的 InlineParser
+# 展开为行内节点。嵌入节点（RubyEmbed）保存嵌入源码原文与位置，不求值。
+#
+# 每个具体节点类只固定自己的 +type+ 与语义属性，其余能力（挂载、遍历、
+# 导航、深度维护……）全部继承自 +BaseNode+。
+module MDOM
+  module Node
+    # 文档根节点。
+    class Document < BaseNode
+      def initialize(attributes: {}, children: [])
+        super(:document, attributes: attributes, children: children)
+      end
+
+      # 文档级元数据（+Hash+，惰性创建）。钩子常往里放东西（CSM §5.3），
+      # +MDOM.compile+ 也会把它作为 +:after_serialize+ 的第二个参数交出去。
+      def meta
+        attributes[:meta] ||= {}
+      end
+    end
+
+    # 节块：连续四个 `\n` 开启的新节，映射为 `<div>`。
+    class Div < BaseNode
+      def initialize(attributes: {}, children: [])
+        super(:div, attributes: attributes, children: children)
+      end
+    end
+
+    # 段落。+text+ 是尚未做行内解析的原文。
+    class Paragraph < BaseNode
+      def initialize(text = "", attributes: {}, children: [])
+        super(:paragraph, attributes: { text: text }.merge(attributes), children: children)
+      end
+
+      def text
+        attributes[:text]
+      end
+
+      def text=(value)
+        attributes[:text] = value
+      end
+    end
+
+    # ATX 标题。+level+ 为 1–6。
+    class Heading < BaseNode
+      def initialize(level, text = "", closed: false, attributes: {}, children: [])
+        attrs = { level: level, text: text, closed: closed }.merge(attributes)
+        super(:heading, attributes: attrs, children: children)
+      end
+
+      def level
+        attributes[:level]
+      end
+
+      def text
+        attributes[:text]
+      end
+
+      # 是否以**等长**的 `#` 收尾（CSM §1.2 的 hgroup 用法）。
+      def closed?
+        attributes[:closed]
+      end
+    end
+
+    # 内容策略为 FLOW 的容器（CSM 元素表：`blockquote` / `li` / `dd`）。
+    #
+    # 它们的正文**不直接挂在容器上**，而是先成为一个段落——FLOW 容器的直接子节点
+    # 是块级节点。+text+ 因此是派生读取：取第一个段落子节点的原文。
+    module FlowBody
+      # 正文原文；还没有段落时返回 +nil+。
+      def text
+        paragraph = children.find { |child| child.type == :paragraph }
+        paragraph&.text
+      end
+    end
+
+    # 块引用。正文（FLOW 内容）在 +children+ 里，通常是段落。
+    class Blockquote < BaseNode
+      include FlowBody
+
+      def initialize(attributes: {}, children: [])
+        super(:blockquote, attributes: attributes, children: children)
+      end
+
+      # `>-` 的出处：派生自 #Cite 子节点（CSM §1.4），没有时 +nil+。
+      def cite
+        source = children.find { |child| child.type == :cite }
+        source&.text
+      end
+    end
+
+    # 引用来源（`<cite>`，由 `>-` 收尾产生）。内容策略为 PHRASING（CSM §1.4），
+    # 所以正文直接是行内节点。
+    class Cite < BaseNode
+      def initialize(text = "", attributes: {}, children: [])
+        super(:cite, attributes: { text: text }.merge(attributes), children: children)
+      end
+
+      def text
+        attributes[:text]
+      end
+
+      def text=(value)
+        attributes[:text] = value
+      end
+    end
+
+    # 围栏代码块。+code+ 是围栏内的原文（不做任何转义）。
+    class CodeBlock < BaseNode
+      def initialize(code = "", lang: nil, params: nil, fence: 3, attributes: {}, children: [])
+        attrs = { code: code, lang: lang, params: params, fence: fence }.merge(attributes)
+        super(:code_block, attributes: attrs, children: children)
+      end
+
+      def code
+        attributes[:code]
+      end
+
+      def lang
+        attributes[:lang]
+      end
+
+      def params
+        attributes[:params]
+      end
+
+      # 围栏的反引号个数（CSM §1.5：3–6 个）。
+      def fence
+        attributes[:fence]
+      end
+    end
+
+    # 列表容器。+ordered+ 为 +true+ 时是有序列表；+task+ 为 +true+ 时是任务列表。
+    class List < BaseNode
+      def initialize(ordered: false, task: false, marker: "-", attributes: {}, children: [])
+        attrs = { ordered: ordered, task: task, marker: marker }.merge(attributes)
+        super(:list, attributes: attrs, children: children)
+      end
+
+      def ordered?
+        attributes[:ordered]
+      end
+
+      def task?
+        attributes[:task]
+      end
+    end
+
+    # 列表项。正文（FLOW 内容）在 +children+ 里，通常是段落。
+    # +checked+ 仅在任务列表中非 +nil+（+true+ / +false+）。
+    class ListItem < BaseNode
+      include FlowBody
+
+      def initialize(marker: "-", task: false, checked: nil, attributes: {}, children: [])
+        attrs = { marker: marker, task: task, checked: checked }.merge(attributes)
+        super(:list_item, attributes: attrs, children: children)
+      end
+
+      def marker
+        attributes[:marker]
+      end
+
+      def task?
+        attributes[:task]
+      end
+
+      def checked
+        attributes[:checked]
+      end
+    end
+
+    # 定义列表容器。
+    class DefinitionList < BaseNode
+      def initialize(attributes: {}, children: [])
+        super(:definition_list, attributes: attributes, children: children)
+      end
+    end
+
+    # 定义术语（`<dt>`）。
+    class Term < BaseNode
+      def initialize(text = "", attributes: {}, children: [])
+        super(:term, attributes: { text: text }.merge(attributes), children: children)
+      end
+
+      def text
+        attributes[:text]
+      end
+    end
+
+    # 定义内容（`<dd>`）。正文（FLOW 内容）在 +children+ 里，通常是段落。
+    class Definition < BaseNode
+      include FlowBody
+
+      def initialize(attributes: {}, children: [])
+        super(:definition, attributes: attributes, children: children)
+      end
+    end
+
+    # 表格（FLOW，**纯结构**）：行是 +TableRow+，行内是 +TableHeaderCell+ /
+    # +TableCell+。单元格内容策略为 PHRASING（CSM §1.12）。
+    class Table < BaseNode
+      def initialize(attributes: {}, children: [])
+        super(:table, attributes: attributes, children: children)
+      end
+    end
+
+    # 表格行（`<tr>`，纯结构）。
+    class TableRow < BaseNode
+      def initialize(attributes: {}, children: [])
+        super(:table_row, attributes: attributes, children: children)
+      end
+    end
+
+    # `th` / `td` 共用：正文（PHRASING 原文）与列对齐。
+    # +align+ 为 +nil+（默认对齐）/ +:left+ / +:center+ / +:right+（CSM §1.12）。
+    module Cell
+      def text
+        attributes[:text]
+      end
+
+      def text=(value)
+        attributes[:text] = value
+      end
+
+      def align
+        attributes[:align]
+      end
+
+      def align=(value)
+        attributes[:align] = value
+      end
+    end
+
+    # 表头单元格（`th`）。由分隔行把它前面那一行提升而来。
+    class TableHeaderCell < BaseNode
+      include Cell
+
+      def initialize(text = "", align: nil, attributes: {}, children: [])
+        attrs = { text: text, align: align }.merge(attributes)
+        super(:table_header_cell, attributes: attrs, children: children)
+      end
+    end
+
+    # 数据单元格（`td`）。
+    class TableCell < BaseNode
+      include Cell
+
+      def initialize(text = "", align: nil, attributes: {}, children: [])
+        attrs = { text: text, align: align }.merge(attributes)
+        super(:table_cell, attributes: attrs, children: children)
+      end
+    end
+
+    # 分隔线（`<hr>`）。
+    class Hrule < BaseNode
+      def initialize(attributes: {}, children: [])
+        super(:hrule, attributes: attributes, children: children)
+      end
+    end
+
+    # 块级公式（`$$…$$`，FLOW）。+tex+ 是 TeX 原文（由 KaTeX 渲染，CSM §1.11）。
+    class MathBlock < BaseNode
+      def initialize(tex = "", attributes: {}, children: [])
+        super(:math_block, attributes: { tex: tex }.merge(attributes), children: children)
+      end
+
+      def tex
+        attributes[:tex]
+      end
+    end
+
+    # Ruby 嵌入块（三类通道统一为此节点）。
+    #
+    # * +source+ —— 已剥离块首行 CSM 缩进后的源码原文；
+    # * +form+ —— +:begin+（引导块关键字）/ +:free+（方法调用带块）/ +:tilde+（`~` 行）；
+    # * +lines+ —— 在**文档**中的行号区间（+Range+，1 起）；
+    # * +indent+ —— 块首行的 CSM 缩进（空格数）；
+    # * +render+ —— 是否以 `.render` 收尾（`~` 行恒为 +false+）。
+    #
+    # 节点只承载「已剥离 N 层缩进」的字符串；块在 CSM 树中的层级由节点在树中的
+    # 位置决定，不由字符串承载。
+    class RubyEmbed < BaseNode
+      def initialize(source:, form:, lines:, indent: 0, render: false, attributes: {}, children: [])
+        attrs = {
+          source: source,
+          form: form,
+          lines: lines,
+          indent: indent,
+          render: render
+        }.merge(attributes)
+        super(:ruby_embed, attributes: attrs, children: children)
+      end
+
+      def source
+        attributes[:source]
+      end
+
+      def form
+        attributes[:form]
+      end
+
+      def lines
+        attributes[:lines]
+      end
+
+      def indent
+        attributes[:indent]
+      end
+
+      def render?
+        attributes[:render]
+      end
+    end
+
+    # `__END__` 边界。其后的原文挂在 +data+ 上，直通给 Ruby 的 +DATA+。
+    class EndMarker < BaseNode
+      def initialize(line, data = nil, attributes: {}, children: [])
+        super(:end_marker, attributes: { line: line, data: data }.merge(attributes), children: children)
+      end
+
+      def line
+        attributes[:line]
+      end
+
+      def data
+        attributes[:data]
+      end
+    end
+  end
+end